@cardstack/choreo 0.0.0 → 0.1.0-unstable.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `@cardstack/choreo` are recorded here.
+
+This file follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+`glimmer-motion` and `@cardstack/choreo` release in lockstep: every version
+of one is a version of the other, and `@cardstack/choreo` peer-depends on the
+exact `glimmer-motion` version it was released with.
+
+Pre-1.0 caveat: the public API is intentionally unstable. Minor and patch
+versions may change behavior until `1.0.0`.
+
+## [Unreleased]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cardstack Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,58 @@
 # @cardstack/choreo
 
-This version is a placeholder. It reserves the package name so that
-releases can be published from the
-[cardstack/boxel](https://github.com/cardstack/boxel) monorepo through npm
-Trusted Publishing. It contains no code.
+**Motion, choreographed.** `<Choreo>` watches a region's render passes, hands each one's changeset
+(inserted, removed and kept participants, with their bounds before and after) to a timeline declared
+inside it, and plays that timeline on the [Motion](https://motion.dev) engine. It is built on
+[`glimmer-motion`](../glimmer-motion), whose `{{motion}}` elements are the participants.
 
-Real versions are published under the `unstable` dist-tag first, and
-under `latest` once a stable release is cut.
+```gts
+import { Choreo } from '@cardstack/choreo';
+import { motion } from 'glimmer-motion';
+
+<template>
+  <Choreo as |c|>
+    {{#each @messages key='id' as |message|}}
+      <article {{motion id=message.id role='message'}}>
+        {{message.subject}}
+      </article>
+    {{/each}}
+    <c.Sequence>
+      <c.Tween @of={{c.removed 'message'}} @opacity={{0}} @ms={{200}} />
+      <c.Move @of={{c.kept 'message'}} />
+    </c.Sequence>
+  </Choreo>
+</template>
+```
+
+## Install
+
+```
+pnpm add @cardstack/choreo glimmer-motion motion-dom motion-utils
+```
+
+Peers: `glimmer-motion` at exactly the same version (the two packages release together), `motion-dom` /
+`motion-utils` in the same ranges glimmer-motion declares, so both packages share one engine,
+`ember-modifier`, `@glimmer/component`, `@glimmer/tracking`, `ember-source >= 5.4`. A v2 addon with
+TypeScript types and Glint signatures.
+
+## Entry points
+
+| import                           | what                                                                                                                                                                              |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@cardstack/choreo`              | `Choreo` and its yielded vocabulary, `beacon`, anchors (`at`, `after`), `createArming`, easings, the region registry, plane-space helpers, `StepComponent` and the timeline types |
+| `@cardstack/choreo/film`         | the film construct: `Film`, its clips, joins, overlays, player and graph                                                                                                          |
+| `@cardstack/choreo/test-support` | `setupChoreo(hooks)`, `advanceGate()`, `seekTo()`, `live()`, `orphanCount()`, `strandedTransforms()`                                                                              |
+
+Deep imports (`@cardstack/choreo/compile`, `@cardstack/choreo/film/math`, …) are the same modules.
+
+## How it plugs into glimmer-motion
+
+A region is a glimmer-motion participant host: `{{motion}}` elements with an `id` or `role` join the
+nearest region when they mount, and a region can claim a leaving element to keep it on screen for as long
+as the timeline names it. The region's in-flight runs count toward glimmer-motion's settle checks through a
+busy probe, and `setupChoreo(hooks)` is glimmer-motion's `setupMotion(hooks)` with Choreo's document-wide
+state (beacons, the far-match barrier, gesture samples) added to the resets it runs.
+
+## License
+
+MIT.

package/addon-main.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+const { addonV1Shim } = require('@embroider/addon-shim');
+module.exports = addonV1Shim(__dirname);

package/declarations/anchors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Anchors — "with / after build N", as typed helpers rather than a string
+ * micro-DSL (docs/choreo-constructs.md §4.2). A step names itself with
+ * `@name`; any later step may start against it with `@at`:
+ *
+ *   <c.Tween @name='head' … />
+ *   <c.Tween @at={{at 'head' 0.4}} … />     start at 40% of head
+ *   <c.Tween @at={{after 'head' 0.2}} … />  start 0.2s after head ends
+ *
+ * `at name 1` and `after name` are the same moment. Anchors point up the
+ * score, the way Keynote's build list does; a forward reference is a
+ * compile error, as is a duplicate name.
+ */
+export interface AnchorRef {
+    anchor: string;
+    /** seconds past the named step's end (`after`) */
+    delay?: number;
+    edge: 'end' | 'start';
+    /** 0..1 of the named step's own length (`at`) */
+    progress?: number;
+}
+/** start at the named step's start, plus `progress` (0–1) of its length */
+export declare function at(name: string, progress?: number): AnchorRef;
+/** start at the named step's end, plus `delay` seconds */
+export declare function after(name: string, delay?: number): AnchorRef;
+//# sourceMappingURL=anchors.d.ts.map

package/declarations/anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,wBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,SAAS,CAExD;AAED,0DAA0D;AAC1D,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,SAAS,CAExD"}

package/declarations/arming.d.ts

@@ -0,0 +1,33 @@
+import type { Run } from './run.ts';
+/** the sliver of a region a watch needs: the run it is playing right now */
+export interface ArmingRegion {
+    readonly run: Run | null | undefined;
+}
+export interface Arming {
+    /** tracked: a crossing this arming is watching is under way */
+    active(): boolean;
+    /**
+     * Arm now, and watch `region` until the run that survives has settled (or
+     * the deadline passes). Called again while armed, it re-arms: the earlier
+     * watch is abandoned rather than allowed to stand the new one down.
+     */
+    begin(region: ArmingRegion): void;
+    /** stand down by hand — a test reset, or a host that knows the pass is off */
+    end(): void;
+    /**
+     * Resolves when this arming stands down, immediately when nothing is armed.
+     * What a host waits on before paying for an expensive mount.
+     */
+    settled(): Promise<void>;
+}
+export interface ArmingOptions {
+    /**
+     * How long to wait for a run to appear before standing down anyway, in ms
+     * (default 4000). The backstop for a crossing that never produced a pass.
+     */
+    deadline?: number;
+    /** run whenever the arming stands down — where a host clears its own flags */
+    onStandDown?: () => void;
+}
+export declare function createArming(options?: ArmingOptions): Arming;
+//# sourceMappingURL=arming.d.ts.map

package/declarations/arming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arming.d.ts","sourceRoot":"","sources":["../src/arming.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,MAAM;IACrB,+DAA+D;IAC/D,MAAM,IAAI,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,8EAA8E;IAC9E,GAAG,IAAI,IAAI,CAAC;IACZ;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAeD,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAsEhE"}

package/declarations/beacon.d.ts

@@ -0,0 +1,9 @@
+export declare const beacon: import("ember-modifier").FunctionBasedModifier<{
+    Args: {
+        Positional: [string];
+        Named: import("ember-modifier/-private/signature").EmptyObject;
+    };
+    Element: Element;
+}>;
+export default beacon;
+//# sourceMappingURL=beacon.d.ts.map

package/declarations/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,MAAM;;;;;;EAMjB,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/declarations/beacons.d.ts

@@ -0,0 +1,23 @@
+import type { Bounds } from './types.ts';
+export declare function registerBeacon(name: string, element: Element): () => void;
+/**
+ * Measure every live beacon, in the same window the region measures `final`.
+ *
+ * Re-measured every pass, never cached: the trash can move without the list
+ * rendering at all — a header that hides, a column that resizes, a scroll.
+ */
+export declare function measureBeacons(root: DOMRect): Map<string, Bounds>;
+/**
+ * Forget every claimed name. The registry outlives any one owner, so a test
+ * that tore down mid-flight would otherwise leave a dead element holding a
+ * name the next test wants — first-wins turns into first-test-wins.
+ * `setupChoreo(hooks)` runs this before and after every test; nothing in an
+ * app should.
+ */
+export declare function resetBeacons(): void;
+/** `{{c.beacon 'trash'}}` — a named point, not a sprite query */
+export interface BeaconRef {
+    beacon: string;
+}
+export declare const isBeaconRef: (v: unknown) => v is BeaconRef;
+//# sourceMappingURL=beacons.d.ts.map

package/declarations/beacons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacons.d.ts","sourceRoot":"","sources":["../src/beacons.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAKzC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,IAAI,CASzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CASjE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,SAE3B;AAED,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SAGD,CAAC"}

package/declarations/changeset.d.ts

@@ -0,0 +1,46 @@
+/**
+ * boxel-motion's Changeset: the sprites one render pass produced, and the
+ * spritesFor / spriteFor queries its transitions selected them with.
+ */
+import type { Bounds, ChangesetLike, Query, Sprite } from './types.ts';
+export declare class Changeset implements ChangesetLike {
+    readonly inserted: Sprite[];
+    readonly kept: Sprite[];
+    readonly removed: Sprite[];
+    /**
+     * The box a `{{beacon}}` claimed this pass, or null if nothing claimed that
+     * name. It is a measurement, not a sprite: a beacon is never inserted, kept
+     * or removed, and a missing one is a no-op for whatever wanted to borrow it.
+     *
+     * Closed over rather than stored as a field, so this class stays structurally
+     * identical to ChangesetLike — a property function written against the
+     * concrete Changeset must still accept the interface it is handed.
+     */
+    readonly beacon: (name: string) => Bounds | null;
+    /**
+     * The camera zoom the world was measured under (§6.3). Every box in this
+     * changeset is a page-space measurement taken through the region's frame
+     * transform, but a step's values are written in the sprite's own local
+     * space — so geometry that becomes inline pixels must be divided back by
+     * this before it is animated. 1 when the frame is at rest.
+     */
+    readonly measureZoom: number;
+    /** the frame's own size in local pixels, from the same final layout */
+    readonly frame?: {
+        height: number;
+        width: number;
+    };
+    /** what the page shows behind this region — see ChangesetLike.ground */
+    readonly ground?: string;
+    constructor(inserted: Sprite[], removed: Sprite[], kept: Sprite[], beacons?: Map<string, Bounds>, measureZoom?: number, frame?: {
+        height: number;
+        width: number;
+    }, ground?: string);
+    get all(): Sprite[];
+    /** something happened this pass that a choreography could animate */
+    get dirty(): boolean;
+    sprites(query: Query | Query[]): Sprite[];
+    sprite(query: Query | Query[]): Sprite | null;
+}
+export default Changeset;
+//# sourceMappingURL=changeset.d.ts.map

package/declarations/changeset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changeset.d.ts","sourceRoot":"","sources":["../src/changeset.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AA+BvE,qBAAa,SAAU,YAAW,aAAa;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAE3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAEjD;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAEnD,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAGvB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAa,EACxC,WAAW,SAAI,EACf,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EACzC,MAAM,CAAC,EAAE,MAAM;IAWjB,IAAI,GAAG,IAAI,MAAM,EAAE,CAElB;IAED,qEAAqE;IACrE,IAAI,KAAK,IAAI,OAAO,CAMnB;IAED,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,MAAM,EAAE;IAuDzC,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,MAAM,GAAG,IAAI;CAS9C;AAED,eAAe,SAAS,CAAC"}

package/declarations/choreo.d.ts

@@ -0,0 +1,261 @@
+import type Owner from '@ember/owner';
+import Component from '@glimmer/component';
+import { type BeaconRef } from './beacons.ts';
+import Changeset from './changeset.ts';
+import { type Pass } from './far.ts';
+import { type GestureRef } from './gesture.ts';
+import { type ChoreoHost, type ChoreoProvider } from './registry.ts';
+import { type ChoreoRun } from './run.ts';
+import { Aim, Attach, Camera, Camera3D, Crossing, Follow, Frame, Gate, Hold, Move, Pan, Parallel, Perform, Raise, Scroll, Sequence, SlowZoom, Spring, Tether, Tween, Wait } from './steps';
+import type { Camera3DState, CameraState, ChoreoNode, PerformCommand, Query } from './types.ts';
+/** `{{c.kept 'card'}}` narrows by role; bare `{{c.kept}}` is handed over uncalled, so the function is a Query too */
+type Selector = ((role?: string) => Query) & Query;
+/** what the region yields: the step components and the sprite queries */
+export interface ChoreoContext {
+    Aim: typeof Aim;
+    Attach: typeof Attach;
+    Camera: typeof Camera;
+    Camera3D: typeof Camera3D;
+    Crossing: typeof Crossing;
+    Follow: typeof Follow;
+    Frame: typeof Frame;
+    Gate: typeof Gate;
+    Hold: typeof Hold;
+    Move: typeof Move;
+    Pan: typeof Pan;
+    Parallel: typeof Parallel;
+    Perform: typeof Perform;
+    Raise: typeof Raise;
+    Scroll: typeof Scroll;
+    Sequence: typeof Sequence;
+    SlowZoom: typeof SlowZoom;
+    Spring: typeof Spring;
+    Tether: typeof Tether;
+    Tween: typeof Tween;
+    Wait: typeof Wait;
+    /** open the gate the run is parked at; template-stable, because gates are wired in templates */
+    advance: () => void;
+    all: Selector;
+    /** `{{c.beacon 'trash'}}` — a named box to borrow, for Move's @from / @to */
+    beacon: (name: string) => BeaconRef;
+    /**
+     * Where the region's frame stands — tracked, updated when a camera step
+     * lands or cancels, deliberately not per frame (§9): app logic may derive
+     * from it (the zoom-threshold transmute) without a feedback loop.
+     */
+    readonly camera: CameraState;
+    /** the removed half an arriving element claimed — orphaned, ready to cross-fade */
+    counterpart: Selector;
+    /** the live drag as geometry: its pose as a box, its velocity into springs */
+    gesture: GestureRef;
+    id: (id: string) => Query;
+    inserted: Selector;
+    kept: Selector;
+    moved: Selector;
+    /** narrow any query to sprites a viewport can actually see (§4.7) */
+    onstage: (query: Query) => Query;
+    /** kept only because it claimed a leaver's identity: the receiving half of a counterpart or far match */
+    received: Selector;
+    removed: Selector;
+    role: (role: string) => Query;
+    /** the current pass's run, as a value you can hold — null between passes (§4.6) */
+    readonly run: ChoreoRun | null;
+    still: Selector;
+}
+interface Signature {
+    Args: {
+        /**
+         * WHERE THE SHOT STANDS BEFORE THE FIRST RUN. A `@through` spline
+         * prepends the pose in force, and with no prior run that pose is the
+         * default rig — dolly 1, yaw 0 — somewhere no film ever authored. A
+         * host that hard-opens on a known pose (it seated its own scene there
+         * before the score existed) declares it here, and the first segment
+         * starts from the shot instead of travelling to it. Read once, before
+         * the first run; after that the pose in force is the run's own.
+         */
+        camera3dFrom?: Camera3DState;
+        /** outline the region and its participants; console.table each run */
+        debug?: boolean;
+        id?: string;
+        /**
+         * A `c.Camera3D` cue moved the shot. Called every frame it changes —
+         * scrubs included, since the pose is sampled from the score — with a
+         * pose the host applies to whatever it is drawing with.
+         */
+        onCamera3D?: (state: Camera3DState) => void;
+        /**
+         * The dispatcher for `<c.Perform>` commands (§C4). Called once per
+         * command as the run's clock comes to include it — during forward
+         * playback as the clock crosses it, after a seek that lands past it,
+         * and again for the whole remaining prefix after a backward fold.
+         * Dispatches are deferred past the render pass, so a command may
+         * mutate tracked state freely.
+         */
+        onPerform?: (command: PerformCommand) => void;
+        /**
+         * The backward half of the fold: the clock moved to before a command
+         * the host already holds. Reset every commanded state here; the run
+         * re-dispatches the remaining prefix, in order, immediately after.
+         */
+        onPerformReset?: () => void;
+        /**
+         * Freeze the rest of the page for the span of each run (§4.7): when a
+         * run starts, every animation in the document that is running AT THAT
+         * MOMENT — and that the run itself does not own — is paused, and played
+         * again when the run lands or is cancelled. The run's own animations
+         * are exempt by construction: the sweep happens before they exist.
+         * Pausing is not stopping — a loop resumes exactly where it was, which
+         * is what makes this safe to do to work the region did not write.
+         * Animations that START during the run are not caught; gating those is
+         * the host's job (the crossing flag the gallery's entrances check).
+         */
+        quiet?: boolean;
+        /**
+         * Treat a subtree swap as one crossing pass (§4.7): scroll intent is
+         * applied inside the pass — after the swap renders, before final bounds
+         * are measured — and the tempo control's zero means no run at all. The
+         * region stays router-agnostic (§9): any swap qualifies, however the
+         * host caused it.
+         */
+        route?: boolean;
+        /** where the arriving scene wants the window: the top, or wherever the thunk says */
+        scroll?: 'top' | (() => number);
+    };
+    Blocks: {
+        default: [ChoreoContext];
+    };
+    Element: HTMLDivElement;
+}
+export declare class Choreo extends Component<Signature> implements ChoreoHost {
+    private element?;
+    private orphanLayer?;
+    private raisedLayer?;
+    private tetherLayer?;
+    /** tracked mirror of the frame's resting state — see ChoreoContext.camera */
+    cameraState: CameraState;
+    /**
+     * 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 */
+    private resting3d;
+    private restingCamera;
+    private participants;
+    /** registered since the last pass */
+    private arrived;
+    /** destroyed before the pass that removed them has been processed */
+    private claimed;
+    /** removed participants this region is keeping alive in its orphan layer */
+    private orphans;
+    /** participants whose Presence is letting them go: removed once, not on every pass while they leave */
+    private leaving;
+    private snapshots;
+    private rootSnapshot?;
+    private passPending;
+    private rendered;
+    run?: ChoreoRun;
+    private context;
+    /** the last changeset this region built — read it from a property function or a test */
+    changeset?: Changeset;
+    constructor(owner: Owner, args: Signature['Args']);
+    /** SPIKE (Lane): providers from outside the markup, appended to every collected tree */
+    private contributors;
+    contribute(provider: ChoreoProvider): () => void;
+    /** the run an attachment drives: the one playing or holding, none between runs */
+    currentRun(): ChoreoRun | null;
+    /** the region's own steps in document order, then whatever was contributed from outside */
+    private collectTree;
+    register(node: ChoreoNode): () => void;
+    claim(node: ChoreoNode): boolean;
+    get renderDetector(): undefined;
+    private snapshot;
+    /** phase 1: what changed this pass, measured — nothing is played yet */
+    measurePass(): Pass | undefined;
+    /** phase 3: identities are settled — compile this region's timeline and play it */
+    finishPass(pass: Pass): void;
+    private orphanBounds;
+    /** the fingerprint of the tree the current run compiled from (see treePrint) */
+    private scorePrint?;
+    /** the layout every participant stood in when the run compiled (see layoutPrint) */
+    private 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.
+     */
+    private layoutOf;
+    /**
+     * 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.
+     */
+    private fastKeep;
+    /** what quiet() paused, accumulated across replaced runs, resumed as one */
+    private quieted;
+    private quiet;
+    private unquiet;
+    private orphan;
+    /** a removed sprite's row has ended */
+    private finish;
+    private drop;
+    private log;
+    host: import("ember-modifier").FunctionBasedModifier<{
+        Args: {
+            Positional: unknown[];
+            Named: import("ember-modifier/-private/signature").EmptyObject;
+        };
+        Element: HTMLDivElement;
+    }>;
+    layer: import("ember-modifier").FunctionBasedModifier<{
+        Args: {
+            Positional: unknown[];
+            Named: import("ember-modifier/-private/signature").EmptyObject;
+        };
+        Element: HTMLDivElement;
+    }>;
+    raised: import("ember-modifier").FunctionBasedModifier<{
+        Args: {
+            Positional: unknown[];
+            Named: import("ember-modifier/-private/signature").EmptyObject;
+        };
+        Element: HTMLDivElement;
+    }>;
+    tethers: import("ember-modifier").FunctionBasedModifier<{
+        Args: {
+            Positional: unknown[];
+            Named: import("ember-modifier/-private/signature").EmptyObject;
+        };
+        Element: SVGSVGElement;
+    }>;
+}
+export default Choreo;
+//# sourceMappingURL=choreo.d.ts.map

package/declarations/choreo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choreo.d.ts","sourceRoot":"","sources":["../src/choreo.gts"],"names":[],"mappings":"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"}

package/declarations/compile.d.ts

@@ -0,0 +1,45 @@
+import type { ChangesetLike, Compiled, Cue, DeliveryOrder, Sprite, TimelineNode } from './types.ts';
+/**
+ * The rung each index takes on the stagger ladder, under a delivery order.
+ * 'center' delivers from the middle outward; 'random' shuffles per run —
+ * seeded input is the native driver's requirement, not this one's.
+ */
+export declare function ladder(n: number, order: DeliveryOrder): number[];
+export default function compile(tree: TimelineNode[], cs: ChangesetLike): Compiled;
+/**
+ * A replacement pass's continuity cue (§3.1): the prior run was driving
+ * this sprite through space and the new score does not name it. Unnamed
+ * it would be released to its rest in one frame — the whole-bay snap —
+ * so the region completes the score: one shape-matched move from the
+ * painted box (which is what a mid-flight sprite's `initial` IS, by
+ * design) to its rest. Transform-only, so a continuation can never
+ * reflow the scene it is tidying; on the interrupted cue's own spring
+ * when it had one, so the carry-on keeps the flight's character.
+ */
+export declare function continuation(sprite: Sprite, cs: ChangesetLike, inherited?: Record<string, unknown>): Cue | null;
+/**
+ * Whether two compiled scores are the SAME statement — used by the region
+ * to keep an in-flight run when an unrelated render replays the pass (the
+ * render detector is volatile by design, so on a busy page every region
+ * re-passes on every app render; a neighbouring demo writing tracked state
+ * per frame must not restart this region's clock).
+ *
+ * The comparison is deliberately conservative. A FLIGHT is measured off the
+ * page and is not comparable by value: any cue carrying one makes the scores
+ * different, and the pass replays exactly as it always did. Values that ARE
+ * comparable (targets, transitions, delivery plans, holds, camera aims)
+ * compare structurally, so an edit that retimes or re-aims anything replays.
+ *
+ * Tethers, raises and scrolls used to be lumped in with flights, and that was
+ * wrong in a way that only showed up on standing annotations: a wire that is
+ * simply ON was recompiled to the identical statement on every pass and, being
+ * declared different every time, had its run torn down and rebuilt — the path
+ * element removed from the layer and a new one appended, sixty times a second
+ * on a busy page. None of the three carries measured geometry in its cue: a
+ * tether is two sprites and a function, a raise is a sprite and a flag, a
+ * scroll is a sprite and an alignment. They compare by IDENTITY, which is
+ * exactly what "the same statement" means for them — and it matters most for
+ * the scroll, where replacing the cue is a visible restart of the scroll.
+ */
+export declare function sameScore(a: Cue[], b: Cue[]): boolean;
+//# sourceMappingURL=compile.d.ts.map

package/declarations/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAGV,aAAa,EACb,QAAQ,EACR,GAAG,EACH,aAAa,EAWb,MAAM,EAEN,YAAY,EAEb,MAAM,YAAY,CAAC;AAoIpB;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CA2BhE;AAw6BD,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,IAAI,EAAE,YAAY,EAAE,EACpB,EAAE,EAAE,aAAa,GAChB,QAAQ,CAuQV;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,aAAa,EACjB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,GAAG,GAAG,IAAI,CAuBZ;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAErD"}

package/declarations/deliver.d.ts

@@ -0,0 +1,44 @@
+import type { Cue, DeliveryBy, Easing, SpringSpec } from './types.ts';
+interface Slot {
+    el: HTMLElement;
+}
+interface Split {
+    /** put the original nodes back; safe to call twice */
+    restore(): void;
+    slots: Slot[];
+}
+export declare function split(el: HTMLElement, by: Exclude<DeliveryBy, 'item'>): Split;
+export interface Window {
+    at: number;
+    ms: number;
+}
+/**
+ * `@stagger` seconds between starts, window = what remains of the span; with
+ * no stagger, the Build Order demo's policy: a 0.55-of-span window with the
+ * starts distributed across the remainder.
+ */
+export declare function windows(n: number, span: number, stagger: number): Window[];
+/** cue.target, as WAAPI property-indexed keyframes */
+export declare function keyframesOf(target: Record<string, unknown>, times?: number[], ease?: string): PropertyIndexedKeyframes;
+export declare function cssEasing(ease: Easing | undefined, ms: number): string;
+/** a spring's clock, pre-sampled: its real duration and a linear() easing */
+export declare function springEasing(spec: SpringSpec | undefined): {
+    easing: string;
+    ms: number;
+};
+export interface Delivery {
+    cancel(): void;
+    /** finish NOW: land the end values and give the text back — a scrub past
+     *  the cue's end must not leave paused spans standing in for the sprite */
+    complete(): void;
+    finished: Promise<void>;
+    pause(): void;
+    play(): void;
+    /** place the whole delivery at `ms` past its cue start (unscaled) */
+    seek(ms: number): void;
+    speed(rate: number): void;
+}
+/** play one delivery cue: split, animate the slots, restore, land the end values */
+export declare function deliver(cue: Cue, speed: number): Delivery;
+export {};
+//# sourceMappingURL=deliver.d.ts.map

package/declarations/deliver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliver.d.ts","sourceRoot":"","sources":["../src/deliver.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,GAAG,EACH,UAAU,EACV,MAAM,EAEN,UAAU,EACX,MAAM,YAAY,CAAC;AAKpB,UAAU,IAAI;IACZ,EAAE,EAAE,WAAW,CAAC;CACjB;AAED,UAAU,KAAK;IACb,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAC;IAChB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AA8BD,wBAAgB,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,KAAK,CA+E7E;AAID,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAa1E;AAYD,sDAAsD;AACtD,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,IAAI,CAAC,EAAE,MAAM,GACZ,wBAAwB,CA2B1B;AAkBD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ,CAMA;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,IAAI,IAAI,CAAC;IACf;+EAC2E;IAC3E,QAAQ,IAAI,IAAI,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,qEAAqE;IACrE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,oFAAoF;AACpF,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CA0FzD"}