@cardstack/choreo 0.0.0 → 0.1.0-unstable.1

package/dist/choreo.js

@@ -0,0 +1,1026 @@
+import { registerDestructor } from '@ember/destroyable';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { consumeTag, VOLATILE_TAG } from '@glimmer/validator';
+import { modifier } from 'ember-modifier';
+import { registerBusyProbe, snapshotOnRender, motionSpeed, postRender, flushPendingMounts } from 'glimmer-motion';
+import { measureBeacons } from './beacons.js';
+import { Changeset } from './changeset.js';
+import compile, { continuation, sameScore } from './compile.js';
+import { leave, join, setPassScheduler, setBeforeMeasure } from './far.js';
+import { trackGestures, GESTURE } from './gesture.js';
+import { measure, boundsOf } from './measure.js';
+import { setChoreoHost } from './registry.js';
+import { execute } from './run.js';
+import { collect, Wait, Tween, Tether, Spring, SlowZoom, Sequence, Scroll, Raise, Perform, Parallel, Pan, Move, Hold, Gate, Frame, Follow, Crossing, Camera3D, Camera, Attach, Aim } from './steps.js';
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+import { g, i } from 'decorator-transforms/runtime';
+
+const selector = type => Object.assign(role => role === undefined ? {
+  type
+} : {
+  role,
+  type
+}, {
+  type
+});
+/** what the region yields: the step components and the sprite queries */
+
+function contextFor(region) {
+  return {
+    Aim,
+    Attach,
+    Camera,
+    Camera3D,
+    Crossing,
+    Follow,
+    Frame,
+    Gate,
+    Hold,
+    Move,
+    Pan,
+    Parallel,
+    Perform,
+    Raise,
+    Scroll,
+    Sequence,
+    SlowZoom,
+    Spring,
+    Tether,
+    Tween,
+    Wait,
+    advance: () => region.run?.advance(),
+    all: selector(),
+    beacon: beacon => ({
+      beacon
+    }),
+    gesture: GESTURE,
+    counterpart: selector('counterpart'),
+    id: id => ({
+      id
+    }),
+    inserted: selector('inserted'),
+    kept: selector('kept'),
+    moved: selector('moved'),
+    onstage: query => ({
+      ...query,
+      onstage: true
+    }),
+    received: selector('received'),
+    removed: selector('removed'),
+    role: role => ({
+      role
+    }),
+    get camera() {
+      return region.cameraState;
+    },
+    get run() {
+      return region.run ?? null;
+    },
+    still: selector('still')
+  };
+}
+let debugStyle;
+/**
+ * Two rules every region shares. An orphaned skin flies with its
+ * backdrop-filters OFF: a backdrop-filter can never be cached — it
+ * re-samples and re-blurs whatever is behind it on every frame — and
+ * inside a scaling, fading leaver that is paid at full price for the
+ * whole flight (the camera demo's four glass panels, over its gradient
+ * washes, was the return trip's jank). It is also the wrong picture: a
+ * skin is a memory of the OLD scene, and its glass sampling the new
+ * scene behind it shows the wrong world. The panels keep their own
+ * translucent grounds, so they still read as glass in the crossfade.
+ *
+ * And an orphaned skin does not REPLAY ITS BIRTH: re-inserting a node
+ * restarts every CSS animation on it, so a leaver re-parented into the
+ * orphan layer re-ran its entrance choreography — rules drawing
+ * themselves, letters settling out of a blur — while it was supposed to
+ * be dying. A one-frame-old memory acting out its own arrival is the
+ * flash the Towers film chased for a night. The run's own exit motion
+ * is WAAPI and survives re-parenting untouched; only stylesheet
+ * animations restart, and on a memory they are all lies.
+ */
+let orphanStyle;
+function ensureOrphanStyle() {
+  if (orphanStyle) {
+    return;
+  }
+  orphanStyle = document.createElement('style');
+  orphanStyle.setAttribute('data-choreo-style', '');
+  orphanStyle.textContent = '[data-choreo-orphans] *,' + '[data-choreo-orphans] *::before,' + '[data-choreo-orphans] *::after' + '{backdrop-filter:none!important;' + '-webkit-backdrop-filter:none!important;' + 'animation:none!important;}';
+  document.head.appendChild(orphanStyle);
+}
+/**
+ * A fingerprint of the collected timeline tree, for telling an EDIT from
+ * noise while a run's own orphans are aloft. Mid-flight, compiled cues are
+ * value-laden (every re-measure shifts them), so sameScore cannot answer
+ * "did the author change the timeline?" — but the tree can: it is template
+ * state, identical under noise, different under any real edit. Functions
+ * (property sources) print by identity: a fresh function is a change we
+ * cannot disprove, and recompiling is the safe answer.
+ */
+const fnIds = new WeakMap();
+let nextFnId = 0;
+function treePrint(tree) {
+  return JSON.stringify(tree, (_key, value) => {
+    if (typeof value === 'function') {
+      let id = fnIds.get(value);
+      if (id === undefined) {
+        fnIds.set(value, id = ++nextFnId);
+      }
+      return `fn#${id}`;
+    }
+    return value;
+  });
+}
+/**
+ * The color the page actually shows behind this region — the nearest
+ * ancestor (the region itself included) wearing a background with any
+ * alpha at all. What a crossing blends a semi-transparent skin against
+ * when it turns opacity into an actual color (§4.7). Undefined when the
+ * whole chain is transparent; the crossfade then stays a plain dissolve.
+ */
+function groundOf(root) {
+  let el = root;
+  while (el) {
+    const bg = getComputedStyle(el).backgroundColor;
+    if (bg && bg !== 'transparent' && !/rgba\([^)]*,\s*0\)$/.test(bg)) {
+      return bg;
+    }
+    el = el.parentElement;
+  }
+  return undefined;
+}
+/**
+ * The barrier books one post-render callback for every region taking part in a
+ * pass. `joinPass(this)` is where the region's PassHost contract (measurePass /
+ * finishPass) is type-checked — it is not on the class, because a `.gts` class
+ * header cannot carry two `implements` clauses through the build.
+ */
+setPassScheduler(run => postRender(run));
+setBeforeMeasure(() => flushPendingMounts());
+class Choreo extends Component {
+  element;
+  orphanLayer;
+  raisedLayer;
+  tetherLayer;
+  /** tracked mirror of the frame's resting state — see ChoreoContext.camera */
+  static {
+    g(this.prototype, "cameraState", [tracked], function () {
+      return {
+        x: 0,
+        y: 0,
+        zoom: 1
+      };
+    });
+  }
+  #cameraState = (i(this, "cameraState"), void 0);
+  /**
+  * The same state, untracked, for the pass pipeline itself. A pass runs
+  * inside computations that must not CONSUME the tracked mirror — a pass
+  * that read it would be invalidated by the very landing it causes, and
+  * the region would render forever.
+  */ /** where a c.Camera3D left the shot, carried between runs — seeded by
+     *  `@camera3dFrom` when the host knows its own opening pose */
+  resting3d = this.args.camera3dFrom ? {
+    ...this.args.camera3dFrom
+  } : {
+    dolly: 1,
+    pitch: 0,
+    x: 0,
+    y: 0,
+    yaw: 0
+  };
+  restingCamera = {
+    x: 0,
+    y: 0,
+    zoom: 1
+  };
+  participants = new Set();
+  /** registered since the last pass */
+  arrived = new Set();
+  /** destroyed before the pass that removed them has been processed */
+  claimed = new Set();
+  /** removed participants this region is keeping alive in its orphan layer */
+  orphans = new Set();
+  /** participants whose Presence is letting them go: removed once, not on every pass while they leave */
+  leaving = new Set();
+  snapshots = new Map();
+  rootSnapshot;
+  passPending = false;
+  rendered = false;
+  run;
+  context = contextFor(this);
+  /** the last changeset this region built — read it from a property function or a test */
+  changeset;
+  constructor(owner, args) {
+    super(owner, args);
+    trackGestures();
+    // what `animationsSettled()` waits for: a pass announced but not yet run,
+    // or a timeline still playing. Orphans are deliberately not counted — a
+    // leaver stranded in the layer is a bug, and a probe that reported it
+    // would turn every one of those into a timeout instead of a failed
+    // assertion with a name on it.
+    const stopProbe = registerBusyProbe(() => {
+      if (this.passPending) {
+        return `<Choreo${this.args.id ? ` ${this.args.id}` : ''}> pass pending`;
+      }
+      // parked is a still and STANDING is an annotation that is simply on
+      // (a score of nothing but open steps never ends): both are settled,
+      // and a probe that called either one "in flight" would turn every
+      // wire the page leaves up into a suite-wide timeout
+      if (this.run && !this.run.isDone() && !this.run.parked && !this.run.standing) {
+        return `<Choreo${this.args.id ? ` ${this.args.id}` : ''}> run in flight`;
+      }
+      return false;
+    });
+    registerDestructor(this, () => {
+      stopProbe();
+      leave(this);
+      this.run?.cancel();
+      this.run = undefined;
+      // a quiet region must not take its pause to the grave
+      this.unquiet();
+      for (const node of [...this.orphans, ...this.claimed]) {
+        this.drop(node);
+      }
+    });
+  }
+  /* ---- ChoreoHost ---- */ /** SPIKE (Lane): providers from outside the markup, appended to every collected tree */
+  contributors = new Set();
+  contribute(provider) {
+    this.contributors.add(provider);
+    return () => {
+      this.contributors.delete(provider);
+    };
+  }
+  /** the run an attachment drives: the one playing or holding, none between runs */
+  currentRun() {
+    return this.run ?? null;
+  }
+  /** the region's own steps in document order, then whatever was contributed from outside */
+  collectTree(root) {
+    const tree = collect(root);
+    for (const provider of this.contributors) {
+      tree.push(provider.node());
+    }
+    return tree;
+  }
+  register(node) {
+    this.participants.add(node);
+    this.arrived.add(node);
+    if (this.args.debug && node.element) {
+      node.element.style.outline = '1px dotted #16a34a';
+      // the seam lints (§5.3): inside a region the timeline is the only
+      // animation authority, and Presence double-retains participants
+      if (node.ownAnimation) {
+        console.warn(`choreo: participant '${node.id ?? node.role}' carries its own ` + 'animate/exit/initial — a second scheduler beside the timeline');
+      }
+      if (node.presenceManaged) {
+        console.warn(`choreo: participant '${node.id ?? node.role}' is inside a ` + '<Presence> — the region already retains its own leavers');
+      }
+    }
+    return () => {
+      // a destroyed participant may still be claimed (below); the sets that decide that survive until drop()
+      this.participants.delete(node);
+      this.arrived.delete(node);
+    };
+  }
+  claim(node) {
+    if (this.orphans.has(node)) {
+      return true;
+    }
+    if (this.passPending) {
+      // its pass has not been processed yet: decide then
+      this.claimed.add(node);
+      return true;
+    }
+    return false;
+  }
+  /* ---- the render pass ---- */ /* eslint-disable ember/no-side-effects -- this getter IS the render hook: boxel-motion's render detector,
+                                  re-evaluated on every render pass before the DOM is patched (React's getSnapshotBeforeUpdate slot) */
+  get renderDetector() {
+    consumeTag(VOLATILE_TAG);
+    // A region is a layout boundary as well: projecting participants
+    // (`layout` / `layoutId`) snapshot here too, so `{{motion layout=true}}`
+    // works inside a <Choreo> without a <LayoutGroup> wrapped around it.
+    snapshotOnRender();
+    if (!this.passPending) {
+      this.passPending = true;
+      this.snapshot();
+      // every region announces here, while Glimmer is still rendering, so the
+      // barrier knows the whole cast before anybody measures
+      join(this);
+    }
+    return undefined;
+  }
+  /* eslint-enable ember/no-side-effects */
+  snapshot() {
+    this.snapshots.clear();
+    this.rootSnapshot = this.element?.getBoundingClientRect();
+    for (const node of this.participants) {
+      const el = node.element;
+      if (el?.isConnected && !this.orphans.has(node)) {
+        this.snapshots.set(node, measure(el));
+      }
+    }
+  }
+  /** phase 1: what changed this pass, measured — nothing is played yet */
+  measurePass() {
+    this.passPending = false;
+    const root = this.element;
+    if (!root) {
+      return undefined;
+    }
+    // THE FAST PATH: a volatile re-pass that cannot change the run. On a
+    // busy page every app render replays every region's pass, and the full
+    // pipeline is destructive even when its verdict is "keep" — release
+    // puts the world at rest (stopping the very animations it measures
+    // around), and standing them back up once per frame IS the jitter the
+    // keep exists to prevent. So a pass with no arrivals, no new leavers
+    // and the same timeline tree is declined before anything is touched:
+    // the run plays on, undisturbed.
+    if (this.fastKeep(root)) {
+      return undefined;
+    }
+    // `initial` was captured before the DOM changed, with any in-flight Move's
+    // values still on the elements — that is what was on screen. `final` must
+    // be the layout the stylesheet actually asks for, so put everything the
+    // last run touched back to rest before measuring anything.
+    this.run?.releaseForMeasure();
+    // @route: scroll is part of the move (§4.7) — the window is placed where
+    // the arriving scene wants it after the swap renders and BEFORE final
+    // bounds are measured, so every landing is measured where it will live
+    if (this.args.route && this.arrived.size && this.snapshots.size) {
+      const intent = this.args.scroll ?? 'top';
+      const y = intent === 'top' ? 0 : intent();
+      window.scrollTo(0, y);
+    }
+    const before = this.rootSnapshot ?? root.getBoundingClientRect();
+    const after = root.getBoundingClientRect();
+    const inserted = [];
+    const removed = [];
+    const kept = [];
+    const sprite = (node, type, initial, final) => ({
+      delta: initial && final ? {
+        height: final.page.height - initial.page.height,
+        width: final.page.width - initial.page.width,
+        x: final.page.x - initial.page.x,
+        y: final.page.y - initial.page.y
+      } : undefined,
+      element: node.element,
+      final,
+      id: node.id,
+      initial,
+      node,
+      role: node.role,
+      type
+    });
+    const candidates = new Set([...this.participants, ...this.claimed, ...this.orphans]);
+    for (const node of candidates) {
+      const el = node.element;
+      if (!el) {
+        continue;
+      }
+      const snap = this.snapshots.get(node);
+      if (this.orphans.has(node)) {
+        // still in flight from an earlier run: addressable again as removed
+        const prior = this.orphanBounds.get(node);
+        removed.push(sprite(node, 'removed', prior));
+      } else if (this.arrived.has(node)) {
+        inserted.push(sprite(node, 'inserted', undefined, boundsOf(measure(el), after)));
+      } else if (!el.isConnected || this.claimed.has(node)) {
+        if (this.leaving.has(node)) {
+          // its Presence has let it go — we already played its exit
+          this.leaving.delete(node);
+          this.drop(node);
+        } else if (snap) {
+          removed.push(sprite(node, 'removed', boundsOf(snap, before)));
+        } else if (this.claimed.has(node)) {
+          this.drop(node);
+        }
+      } else if (!node.isPresent) {
+        if (!this.leaving.has(node) && snap) {
+          this.leaving.add(node);
+          removed.push(sprite(node, 'removed', boundsOf(snap, before)));
+        }
+      } else if (snap) {
+        this.leaving.delete(node);
+        kept.push(sprite(node, 'kept', boundsOf(snap, before), boundsOf(measure(el), after)));
+      }
+    }
+    // an inserted id that matches a removed one: the new element carries the old as its counterpart
+    for (const s of inserted) {
+      if (s.id === null) {
+        continue;
+      }
+      const old = removed.find(r => r.id === s.id && !r.counterpart);
+      if (old) {
+        old.claimed = true;
+        s.counterpart = old;
+        s.initial = old.initial;
+        s.type = 'kept';
+        s.delta = s.initial && s.final && {
+          height: s.final.page.height - s.initial.page.height,
+          width: s.final.page.width - s.initial.page.width,
+          x: s.final.page.x - s.initial.page.x,
+          y: s.final.page.y - s.initial.page.y
+        };
+      }
+    }
+    this.arrived.clear();
+    this.snapshots.clear();
+    const claimed = [...this.claimed];
+    this.claimed.clear();
+    // the barrier now pairs any id inserted here against the same id removed in
+    // ANOTHER region, before finishPass compiles a timeline against the result
+    return {
+      claimed,
+      host: this,
+      inserted,
+      kept,
+      removed,
+      root
+    };
+  }
+  /** phase 3: identities are settled — compile this region's timeline and play it */
+  finishPass(pass) {
+    const {
+      claimed,
+      inserted,
+      kept,
+      root
+    } = pass;
+    // a sprite whose identity was received by another region is not leaving:
+    // the element that carries it on is already being animated over there
+    const removed = pass.removed.filter(s => !s.sent);
+    for (const s of pass.removed) {
+      if (s.sent) {
+        this.finish(s);
+      }
+    }
+    const after = root.getBoundingClientRect();
+    // The zoom every box below was measured under (§6.3) — read from the
+    // PAINTED frame, never from the run's bookkeeping. While a camera cue
+    // flies on WAAPI the shadow value is one rAF behind the compositor,
+    // and inside a fast cue that one frame is the whole flight: fitted
+    // zooms cancel the mismatch, but translate targets keep it forever,
+    // and a chain of replacement passes compounds it (the reel's loop
+    // seams landed every shot hundreds of pixels off, differently per
+    // loop). getComputedStyle samples the same frozen timeline the rects
+    // above were measured under, so zoom and boxes are one measurement.
+    //
+    // It is the TOTAL scale between the page and this region's local
+    // space: the root's painted width over its LAYOUT width, not the
+    // region's own camera alone. Those two are the same number right up
+    // until something above the region is scaled, and then they are not.
+    // An ancestor `transform: scale(s)` multiplies every box this pass
+    // measures while the run still writes local pixels, so every flight
+    // is off by exactly s — a region inside a scale(1.5) card starts its
+    // flights a thousand pixels from where they belong. Reading the
+    // root's own rect subsumes the camera and everything above it in one
+    // measurement, taken in the same window as the boxes.
+    const layoutWidth = root.offsetWidth;
+    const shadow = this.run?.camera.zoom ?? this.restingCamera.zoom;
+    const painted = layoutWidth > 0 ? after.width / layoutWidth : 0;
+    // …snapped to the exact bookkeeping value whenever the two agree: the
+    // layout width is an integer, and letting that quantisation into the
+    // divide gives two passes of the same still landings a thousandth of
+    // a pixel apart. The painted value only OVERRULES the shadow when
+    // they genuinely diverge — which now means "something outside is
+    // scaling us" as well as "the camera is mid-cue".
+    const measureZoom = !painted || Math.abs(painted - shadow) < 0.004 ? shadow : painted;
+    const changeset = new Changeset(inserted.filter(s => s.type === 'inserted'), removed, [...kept, ...inserted.filter(s => s.type === 'kept')],
+    // measured in the same window as `final`, and re-measured every pass: a
+    // beacon can move without this region rendering at all
+    measureBeacons(after), measureZoom,
+    // the frame's own size in the same final layout, local pixels — the
+    // camera's centre reference, so aim terms are internally consistent
+    {
+      height: after.height / measureZoom,
+      width: after.width / measureZoom
+    }, groundOf(root));
+    this.changeset = changeset;
+    const firstRender = !this.rendered;
+    this.rendered = true;
+    // instant means instant on a crossing: no run, not a zero-length run
+    if (this.args.route && motionSpeed() === 0) {
+      for (const node of claimed) {
+        this.drop(node);
+      }
+      for (const s of removed) {
+        this.finish(s);
+      }
+      return;
+    }
+    // A pass whose changeset is all-kept still runs its timeline (§3.1):
+    // the share badge, the hot wire — a Hold with a lifetime fired by an
+    // event that inserts, removes and moves nothing. Steps that select
+    // change (inserted / removed / moved) produce no cues on such a pass.
+    const tree = firstRender ? [] : this.collectTree(root);
+    const compiled = tree.length ? compile(tree, changeset) : {
+      cues: [],
+      gates: []
+    };
+    const cues = compiled.cues;
+    // CONTINUITY (§3.1): sprites the prior run is still driving through
+    // space, which this new score does not name, would be dropped to
+    // rest in ONE FRAME — the whole-bay snap every conditional timeline
+    // had to hand-patch with a `c.moved` twin. The changeset already
+    // reads a flying sprite as kept-and-moved (its initial is the painted
+    // box, by design), so the score is completed rather than overridden:
+    // each gets a continuation move from where it is painted to its rest.
+    // Before the empty-score bail on purpose — a timeline that un-renders
+    // mid-flight compiles NOTHING, and that bail neither cancels the run
+    // nor reasserts the world: the release itself was the snap. A sprite
+    // that merely REFLOWED is untouched — it was never driven.
+    if (this.run && !this.run.isDone()) {
+      const scored = new Set(cues.map(c => c.sprite.node));
+      for (const [node, transition] of this.run.midflight()) {
+        if (scored.has(node)) {
+          continue;
+        }
+        const s = changeset.kept.find(k => k.node === node);
+        if (!s) {
+          continue;
+        }
+        const cue = continuation(s, changeset, transition);
+        if (cue) {
+          cues.push(cue);
+        }
+      }
+    }
+    if (!cues.length) {
+      // nothing to play: let every leaver go now
+      for (const node of claimed) {
+        this.drop(node);
+      }
+      for (const s of removed) {
+        // §5.3, from the other side of the seam: on a pass this region
+        // declines to animate, a <Presence>-managed leaver still mid-exit
+        // belongs to its Presence — calling exitComplete here would cut
+        // that animation short. The region stands aside; when the exit
+        // ends, Presence unmounts the element and it leaves for real.
+        if (s.node.presenceManaged && !s.node.isPresent && s.element.isConnected && !this.orphans.has(s.node)) {
+          this.leaving.delete(s.node);
+          continue;
+        }
+        this.finish(s);
+      }
+      return;
+    }
+    // An unrelated render replays every region's pass — the detector is
+    // volatile by design, so on a busy page (the gallery: a neighbouring
+    // demo writing tracked state per frame) a region re-passes on every
+    // app render. A finished run replays (§3.1's Hold re-fire). An
+    // all-still pass — no arrivals, leavers, or moved boxes — is noise
+    // (a parent writing `hot`, a neighbour ticking at 60fps) and must
+    // not restart the clock. Gates and path-moves make a freshly compiled
+    // cue list incomparable (zero-delta Moves drop; flights exist), so
+    // sameScore cannot be the only detector.
+    //
+    // A removed sprite that is one of this region's own ORPHANS is not a
+    // new leaver: it re-enters every changeset on purpose (addressable
+    // again), and while one is aloft a recompiled score is NOT
+    // authoritative — the pairing that produced the run's flights lived
+    // in the pass that removed and inserted together, and a later pass
+    // sees only the orphan half. Counting orphans as dirt meant a
+    // crossing on a busy page was cancelled into a leave-only rump by
+    // its own neighbours' renders, every frame.
+    const print = treePrint(tree);
+    const nothingNew = !inserted.length && pass.removed.every(s => this.orphans.has(s.node)) && (
+    // A sprite mid-flight reads as "moved" on every re-pass — its initial
+    // is the painted box, by design — so while this run's own orphans are
+    // aloft, kept-motion cannot justify a recompile either: the score it
+    // would produce is the degraded one above.
+    this.orphans.size > 0 || !changeset.sprites({
+      type: 'moved'
+    }).length) &&
+    // …but an EDITED timeline is never noise: a changed tree replays,
+    // exactly as it would with no orphans aloft (the build-order
+    // transport's delay nudge, made while a leaver is frozen mid-park)
+    print === this.scorePrint;
+    if (this.run && !this.run.isDone() && nothingNew) {
+      for (const node of claimed) {
+        this.drop(node);
+      }
+      // the measurement above put the run's world at rest; a keep must be
+      // invisible, so the run stands its picture back up (see reassert)
+      this.run.reassert();
+      return;
+    }
+    // dirty but the compiled score is the one already in flight (tween-only
+    // measurement jitter): keep that run too.
+    //
+    // The TREE has to be the one in flight as well, not just the cues it
+    // compiled to. Identical cues are not proof of an identical timeline:
+    // a score that plays a slice of itself — a chapter skip that re-cuts
+    // to the head it is already inside — compiles to the same cue list at
+    // the same offsets, and keeping the run there hands the "new" film
+    // the old one's CLOCK. The score restarts on paper and carries on
+    // playing in fact: beats land early, some never land at all, and the
+    // picture runs ahead of the words that name it. An author who wants a
+    // re-execution says so by editing the tree (a fresh sequence name is
+    // the usual way, which is why the name is in the print).
+    if (this.run && !this.run.isDone() && !inserted.length && !pass.removed.length && !compiled.gates.length && print === this.scorePrint && sameScore(this.run.cues, cues)) {
+      for (const node of claimed) {
+        this.drop(node);
+      }
+      this.run.reassert();
+      return;
+    }
+    // the removed participants the run names stay; the rest go now
+    const named = new Set(cues.map(c => c.sprite));
+    for (const s of [...kept, ...inserted]) {
+      if (s.counterpart && named.has(s)) {
+        named.add(s.counterpart);
+      }
+    }
+    const prior = this.run;
+    // Which camera the replacement starts from is decided by WHAT it is.
+    // The same score recompiled mid-run is a re-execution of the same
+    // timeline: it inherits the prior run's fold origin, so a seek's
+    // reconstruction folds the score's prefix once and only once —
+    // handing it the pose in force would fold every relative cue on top
+    // of the pose that cue already produced, and the world doubles
+    // (world-dock-test). A NEW score responds to the world as it stands:
+    // it starts from the pose actually applied, which mid-flight is the
+    // prior run's live shadow, not the last landed state.
+    const inherited = prior !== undefined && !prior.isDone() ? print === this.scorePrint ? {
+      aim: prior.initialAim,
+      camera: prior.initialCamera
+    } : {
+      aim: prior.cameraAim,
+      camera: prior.camera
+    } : {
+      aim: prior?.cameraAim ?? null,
+      camera: this.restingCamera
+    };
+    // the shot carries run to run for the same reason the frame does: a
+    // replacement pass must continue the move, not snap back to framing
+    const shot3d = prior !== undefined && !prior.isDone() ? prior.camera3d : this.resting3d;
+    prior?.cancel(new Set([...named].map(s => s.node)));
+    for (const s of removed) {
+      if (!named.has(s)) {
+        this.finish(s);
+      } else if (!s.element.isConnected || claimed.includes(s.node)) {
+        this.orphan(s, removed, s.claimed === true);
+      }
+    }
+    if (this.args.debug) {
+      // the hierarchy lint (§6.3): a removed participant no step names will
+      // simply vanish — the uncanny valley the deck warns about
+      for (const s of removed) {
+        if (!named.has(s)) {
+          console.warn(`choreo: removed participant '${s.id ?? s.role}' is named by ` + 'no step — it vanishes without a frame');
+        }
+      }
+      this.log(changeset, cues);
+    }
+    this.scorePrint = print;
+    // taken here, with the world released and measured: the resting layout
+    // this run is about to fly away from (see fastKeep)
+    this.layoutPrint = this.layoutOf();
+    // @quiet: pause everything running RIGHT NOW — the run's own animations
+    // do not exist yet, so they are exempt by construction. Accumulated,
+    // not replaced: an interrupted run's replacement sweeps again, and
+    // everything resumes together when the run that survives settles.
+    if (this.args.quiet) {
+      this.quiet();
+    }
+    this.run = execute(compiled, {
+      camera: {
+        ...inherited.camera
+      },
+      camera3d: {
+        ...shot3d
+      },
+      cameraFrame: this.element,
+      // the aim point in force carries run to run, so a re-aim lerps from
+      // what is actually applied rather than assuming an unaimed frame —
+      // except a same-score re-execution, which carries the fold origin
+      cameraAim: inherited.aim,
+      // updated at step boundaries only — a still value app logic can
+      // read. Guarded by equality: the landing itself renders, the render
+      // is an all-kept pass, and the pass replays the camera step — an
+      // unguarded set would revalidate forever.
+      onCamera3D: state => {
+        this.resting3d = state;
+        this.args.onCamera3D?.(state);
+      },
+      onCamera: state => {
+        const prior = this.restingCamera;
+        this.restingCamera = state;
+        if (prior.zoom !== state.zoom || prior.x !== state.x || prior.y !== state.y) {
+          // the library's own host hook — the Ember adapter installs the
+          // runloop's afterRender behind it, and this file stays host-blind
+          postRender(() => this.cameraState = state);
+        }
+      },
+      raisedLayer: this.raisedLayer,
+      tetherLayer: this.tetherLayer,
+      // ember-animated's continuity, in the terms motion-dom offers: it sums a
+      // corrective curve onto the one it interrupted, which transfers velocity
+      // implicitly; a spring takes a velocity outright, so the run that is
+      // being replaced hands over how fast everything was going.
+      inherit: prior?.velocities,
+      onPerform: this.args.onPerform,
+      onPerformReset: this.args.onPerformReset,
+      onSpriteDone: s => this.finish(s),
+      removed: removed.filter(s => named.has(s)),
+      // nothing in this region is staying: no participant kept, none
+      // arriving, and every one it can see on its way out. A region in that
+      // state is not watching a departure, it is inside one — see `park`.
+      doomed: !kept.length && !inserted.length && removed.length > 0
+    });
+    if (this.args.quiet) {
+      const run = this.run;
+      void run.finished.then(() => {
+        // only the run still in charge hands the page back — a cancelled
+        // one was replaced, and its replacement holds the pause
+        if (this.run === run) {
+          this.unquiet();
+        }
+      });
+    }
+  }
+  /* ---- orphans: a removed participant kept alive, locked where it was ---- */
+  orphanBounds = new Map();
+  /** the fingerprint of the tree the current run compiled from (see treePrint) */
+  scorePrint;
+  /** the layout every participant stood in when the run compiled (see layoutPrint) */
+  layoutPrint;
+  /**
+  * Where the stylesheet puts each participant, as a string.
+  *
+  * `offsetLeft/Top/Width/Height` and NOT a bounding rect, because the
+  * difference is the whole point: a rect includes the transform a flight
+  * is writing, so a moving element reads as different on every frame,
+  * while offsets are the box layout asked for — steady under a transform,
+  * and different the moment something actually reflows. Integers, too,
+  * which quietly forgives the sub-pixel noise a busy page generates.
+  *
+  * A Move that animates real width/height (`@size={{true}}`) does change
+  * these, so such a run never takes the fast path. That is the honest
+  * answer rather than a missed optimisation: a run writing layout cannot
+  * be told apart from a page writing layout without measuring.
+  *
+  * Offsets are accumulated up the offset chain to the region, not read
+  * at the participant alone, because what a render moves may be an
+  * ANCESTOR that is no participant of anything — Escort's seat, one
+  * positioned wrapper carrying three participants. Read flat, the
+  * fingerprint was blind to exactly the reflow a retarget makes, the
+  * pass was declined, and the old run played on against the moved
+  * layout: card, badge and shadow teleported a whole bay, together. The
+  * walk stops at the region's edge so the page above it stays out of the
+  * print — a busy neighbour reflowing above the region must not cancel
+  * its runs.
+  */
+  layoutOf() {
+    const root = this.element;
+    const parts = [];
+    for (const node of this.participants) {
+      const el = node.element;
+      if (!el || !el.isConnected) {
+        continue;
+      }
+      let x = 0;
+      let y = 0;
+      let walk = el;
+      while (walk && walk !== root && root?.contains(walk)) {
+        x += walk.offsetLeft;
+        y += walk.offsetTop;
+        const parent = walk.offsetParent;
+        walk = parent instanceof HTMLElement ? parent : null;
+      }
+      parts.push(`${node.id ?? node.role ?? ''}@${x},${y},` + `${el.offsetWidth},${el.offsetHeight}`);
+    }
+    return parts.join('|');
+  }
+  /**
+  * Can this pass be declined outright? Only while a run is in flight, and
+  * only when nothing the pass could discover would change it: no arrivals,
+  * no retentions pending, every participant either present or already a
+  * known leaver, the collected timeline tree fingerprints identical to the
+  * one the run compiled from (an EDIT always replays), and every
+  * participant standing in the same layout box it compiled in (a REFLOW
+  * always replays — it is what a Move is FOR). Anything else takes the
+  * full pipeline.
+  */
+  fastKeep(root) {
+    if (!this.run || this.run.isDone() || this.claimed.size || this.arrived.size) {
+      return false;
+    }
+    // A HELD RUN CANNOT BE MEASURED AROUND.
+    //
+    // Everything below this line decides "nothing changed" by looking at the
+    // page — and while a run is holding, what the page reports is what the
+    // RUN wrote. A Move keeps inline width and height on its sprites for as
+    // long as it owns them, and `layoutOf` reads exactly those. So a run
+    // parked at the pose it compiled TO reports a layout identical to the
+    // one recorded when it compiled, and a genuine change to the resting
+    // layout arrives on a pass that declines itself: the score is never
+    // recompiled and the new pose never lands.
+    //
+    // That is not hypothetical. It is what a host scrubbing `run.time` hits
+    // every time it swaps to a neighbouring segment — the swap happens at a
+    // waypoint, and a waypoint is the pose the outgoing run is parked at by
+    // definition.
+    //
+    // Measuring the resting layout instead would mean releasing the run, and
+    // releasing is the destructive thing this path exists to avoid. So the
+    // rule is simply: the fast path is for a run flying under its own clock.
+    // A run whose clock somebody else is holding takes the full pipeline —
+    // which costs nothing in practice, because a host that owns a clock is
+    // not the busy-gallery case this path was written for. It scrubs; it
+    // does not re-render.
+    if (this.run.paused) {
+      return false;
+    }
+    for (const node of this.participants) {
+      const el = node.element;
+      if (!el || !el.isConnected) {
+        return false;
+      }
+      if (!node.isPresent && !this.leaving.has(node) && !this.orphans.has(node)) {
+        return false;
+      }
+    }
+    return treePrint(this.collectTree(root)) === this.scorePrint && this.layoutOf() === this.layoutPrint;
+  }
+  /* ---- @quiet: the rest of the page, paused for the span of a run ---- */ /** what quiet() paused, accumulated across replaced runs, resumed as one */
+  quieted = [];
+  quiet() {
+    for (const animation of document.getAnimations()) {
+      if (animation.playState === 'running') {
+        animation.pause();
+        this.quieted.push(animation);
+      }
+    }
+  }
+  unquiet() {
+    for (const animation of this.quieted.splice(0)) {
+      try {
+        animation.play();
+      } catch {
+        // an animation whose element left with the old scene: nothing to resume
+      }
+    }
+  }
+  orphan(s, removed, extract = false) {
+    // Only the topmost removed element is moved; what it contains comes with
+    // it — EXCEPT a claimed skin. Its whole job is to cross inside the flight,
+    // and riding a fading ancestor instead is the View Transitions nesting
+    // rule (never name a container of named things) sneaking back in. A
+    // claimed sprite is lifted out of the doomed subtree; both end up locked
+    // to the same page coordinates in the same layer, so the lift is
+    // invisible — all it leaves behind is a hole in the ancestor, which is
+    // exactly where the eye expects one while the skin is elsewhere.
+    const inside = removed.some(o => o !== s && o.element !== s.element && o.element.contains(s.element));
+    if (inside && !extract || !s.initial) {
+      return;
+    }
+    const layer = this.orphanLayer;
+    const root = this.element;
+    if (!layer || !root) {
+      return;
+    }
+    // Page measurements carry every transform above the region — its own
+    // camera, and whatever is carrying the whole region this frame (a
+    // page crossing scaling the stage). The lock is written as LOCAL
+    // pixels inside the equally-transformed orphan layer, so the scale
+    // must come back out or it is applied twice and the leaver jumps the
+    // moment it is lifted — the raise learned this same rule.
+    const now = root.getBoundingClientRect();
+    const sx = root.offsetWidth ? now.width / root.offsetWidth : 1;
+    const sy = root.offsetHeight ? now.height / root.offsetHeight : 1;
+    if (inside) {
+      // hold the seat: the ancestor is itself a leaver, and without this its
+      // remaining children reflow into the gap mid-fade. The placeholder
+      // lives only inside that doomed subtree, so it leaves with it.
+      const seat = document.createElement('div');
+      seat.style.width = `${s.initial.page.width / sx}px`;
+      seat.style.height = `${s.initial.page.height / sy}px`;
+      s.element.parentElement?.insertBefore(seat, s.element);
+    }
+    // locked where it was ON THE PAGE: the region itself may have moved in the same pass
+    const {
+      page
+    } = s.initial;
+    const el = s.element;
+    el.style.position = 'absolute';
+    el.style.left = `${(page.x - now.left) / sx}px`;
+    el.style.top = `${(page.y - now.top) / sy}px`;
+    el.style.width = `${page.width / sx}px`;
+    el.style.height = `${page.height / sy}px`;
+    el.style.boxSizing = 'border-box';
+    el.style.margin = '0';
+    el.style.pointerEvents = 'none';
+    // one texture, transformed — not a subtree re-rastered per frame
+    el.style.willChange = 'transform, opacity';
+    layer.appendChild(el);
+    this.orphans.add(s.node);
+    this.orphanBounds.set(s.node, s.initial);
+  }
+  /** a removed sprite's row has ended */
+  finish(s) {
+    if (this.orphans.has(s.node) || this.participants.has(s.node)) {
+      if (!s.element.isConnected || this.orphans.has(s.node)) {
+        this.drop(s.node);
+      } else if (!s.node.isPresent) {
+        s.node.exitComplete();
+      }
+    } else {
+      this.drop(s.node);
+    }
+  }
+  drop(node) {
+    const el = node.element;
+    if (el && this.orphans.has(node) && el.parentElement === this.orphanLayer) {
+      el.remove();
+    }
+    this.orphans.delete(node);
+    this.orphanBounds.delete(node);
+    this.claimed.delete(node);
+    this.leaving.delete(node);
+    this.participants.delete(node);
+    node.release();
+  }
+  /* ---- debug ---- */
+  log(changeset, cues) {
+    const id = this.args.id ?? '';
+    const row = s => ({
+      choreo: id,
+      final: s.final ? JSON.stringify(s.final.context) : null,
+      id: s.id,
+      initial: s.initial ? JSON.stringify(s.initial.context) : null,
+      role: s.role,
+      type: s.type
+    });
+    console.table(changeset.all.map(row));
+    console.table(cues.map(c => ({
+      choreo: id,
+      duration: Math.round(c.duration),
+      sprite: c.sprite.id ?? c.sprite.role,
+      start: Math.round(c.start),
+      step: c.kind,
+      values: JSON.stringify(c.target ?? c.hold?.values ?? null)
+    })));
+  }
+  /* ---- template ---- */
+  host = modifier(el => {
+    this.element = el;
+    setChoreoHost(el, this);
+    ensureOrphanStyle();
+    if (getComputedStyle(el).position === 'static') {
+      el.style.position = 'relative';
+    }
+    if (this.args.debug) {
+      el.style.outline = '1px dashed #2563eb';
+      if (!debugStyle) {
+        debugStyle = document.createElement('style');
+        debugStyle.textContent = '[data-choreo-orphans] > * { outline: 1px dotted #dc2626 !important; }';
+        document.head.appendChild(debugStyle);
+      }
+    }
+    return () => {
+      setChoreoHost(el, undefined);
+      this.element = undefined;
+    };
+  });
+  layer = modifier(el => {
+    this.orphanLayer = el;
+    return () => {
+      this.orphanLayer = undefined;
+    };
+  });
+  raised = modifier(el => {
+    this.raisedLayer = el;
+    return () => {
+      this.raisedLayer = undefined;
+    };
+  });
+  tethers = modifier(el => {
+    this.tetherLayer = el;
+    return () => {
+      this.tetherLayer = undefined;
+    };
+  });
+  /**
+  * The host is the scene: participants are its DIRECT children, so the
+  * author's own grid/flex layout on the region element applies to them —
+  * a wrapper here would silently unhook every gap and track. c.Camera
+  * therefore drives the host element itself (§6.3), and the overlay
+  * layers ride the frame with the content they annotate.
+  */
+  static {
+    setComponentTemplate(precompileTemplate("{{this.renderDetector}}\n<div data-choreo={{if @id @id \"\"}} data-motion-host {{this.host}} ...attributes>\n  <div data-choreo-orphans style=\"position:absolute;inset:0;pointer-events:none;overflow:visible\" {{this.layer}}></div>\n  {{!-- the elevated layer: where c.Raise promotes the living \u2014 above every\n      stacking context and clip in the region (\xA76.3) --}}\n  <div data-choreo-raised style=\"position:absolute;inset:0;pointer-events:none;overflow:visible;z-index:2147483000\" {{this.raised}}></div>\n  {{!-- the wires: geometry drawn between sprites, every frame (\xA76.1) --}}\n  <svg data-choreo-tethers style=\"position:absolute;inset:0;width:100%;height:100%;pointer-events:none;overflow:visible\" {{this.tethers}}></svg>\n  {{yield this.context}}\n</div>", {
+      strictMode: true
+    }), this);
+  }
+}
+
+export { Choreo, Choreo as default };
+//# sourceMappingURL=choreo.js.map