@cardstack/choreo 0.0.0 → 0.1.0-unstable.0

package/declarations/measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAW/C,0BAA0B;AAC1B,eAAO,MAAM,IAAI,GAAI,GAAG,OAAO,KAAG,IAKhC,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,KAAK,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,IAK7C,CAAC;AAEH,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,IAAI,OAAO,KAAG,OAAO,GAAG,SAY9C,CAAC;AAeF,gFAAgF;AAChF,eAAO,MAAM,SAAS,GAAI,IAAI,OAAO,KAAG,OAKb,CAAC;AAE5B,eAAO,MAAM,OAAO,GAAI,IAAI,OAAO,KAAG,QAWpC,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,QAAQ,GAAI,MAAM,QAAQ,EAAE,MAAM,OAAO,KAAG,MAMvD,CAAC;AAEH,oEAAoE;AACpE,eAAO,MAAM,aAAa,GAAI,IAAI,OAAO,EAAE,MAAM,OAAO,KAAG,MAC9B,CAAC"}

package/declarations/path.d.ts

@@ -0,0 +1,73 @@
+/**
+ * THE CAMERA'S PATH — the arithmetic behind `c.Camera3D @through`, and
+ * the only place in Choreo that owns a curve rather than a tween.
+ *
+ * Everything here is a pure function of PROGRESS. That is the whole
+ * point: a seek must land the shot exactly where playing there would, so
+ * nothing in this file may remember a previous frame. A spline that is
+ * sampled rather than integrated can be scrubbed, rendered a frame at a
+ * time, and played, and all three agree by construction.
+ */
+import type { Camera3DState, Camera3DWaypoint } from './types.ts';
+/**
+ * Sample the spline at overall progress p ∈ [0, 1] (uniform segments).
+ *
+ * SPLICES (docs/choreo-splices.md): a waypoint marked `cut` starts a new
+ * SHOT. Each shot is a clamped spline of its own points — endpoint
+ * tangents one-sided, so no shot's velocity crosses a seam — and each
+ * shot's window runs from its first slot to the next seam, its points
+ * spread uniformly across it. The outgoing shot therefore plays through
+ * the seam instant (its motion stretches by one slot rather than
+ * parking), the incoming one begins exactly on it, and the sampled pose
+ * is a step function at the seam. Waypoints keep their uniform slots, so
+ * cues anchored to waypoint moments keep their clock. A cut on the first
+ * waypoint drops the pose-in-force seed: the score opens inside its
+ * first shot.
+ */
+export declare function sampleThrough(from: Camera3DState, through: Camera3DWaypoint[], progress: number, tension?: number): Camera3DState;
+/**
+ * A SETTLE — the operator's second hand, written as a function of time.
+ *
+ * A cardinal spline crosses its waypoints with continuous velocity but
+ * not continuous acceleration: at every control point the curvature
+ * steps, and the eye reads that step as a tick. The usual cure is a
+ * spring chasing the pose, which works and costs the two things a
+ * seekable engine cannot pay — it remembers the last frame, so a scrub
+ * lands somewhere a play would not, and it lags, so the camera is always
+ * behind the score by however much smoothing it was given.
+ *
+ * This is the same cure without either cost: the reported pose is a
+ * Hann-weighted average of the SAME spline sampled around the current
+ * progress. Averaging a curve is a low-pass filter, and a Hann window
+ * kills the acceleration steps outright, so the result is a hand rather
+ * than a mechanism. Being centred, it has no lag — it reads slightly
+ * ahead of the score exactly as much as it reads behind. Being an
+ * average of one pure function, it is still a pure function: play,
+ * scrub and frame-by-frame render all report the same pose.
+ *
+ * TWO EDGES IT MUST NOT CROSS. A cut is a step in the pose on purpose,
+ * and an average that straddled it would smear the cut into a very fast
+ * pan. The window is therefore TAPERED to the shot the progress is in:
+ * near either edge the kernel shrinks to the room it has, reaching zero
+ * at the edge itself. So a cut stays a cut, a path still lands exactly
+ * on its last waypoint, and the pose handed forward to the next cue is
+ * the waypoint rather than an average of one — the filter is an identity
+ * at every boundary and a smoother everywhere else.
+ *
+ * The taper is `tanh`, not a `min`, and the difference is the whole
+ * reason it works. A hard `min(width, 2 × room)` has a corner in it
+ * where the two branches meet, and a filter whose width has a corner
+ * puts one back into what it filters: measured against a path with two
+ * right-angle corners in it, the hard taper LOST ground as the window
+ * widened (worst jerk 8.7e-4 at a window of 0.175, 2.5e-3 at 0.3) while
+ * the smooth one held 8.0e-4 at every width against 4.2e-3 unfiltered.
+ * `tanh(x) ≤ x` everywhere, which is what keeps the taps inside the
+ * shot; it is smooth, which is what keeps the tick out.
+ *
+ * `width` is in progress, not seconds: the kinks being filtered are at
+ * the waypoints, which are spread uniformly across the clock, so a
+ * window measured against the clock is a window measured against the
+ * spacing of the things it exists to smooth. The caller converts.
+ */
+export declare function settleThrough(from: Camera3DState, through: Camera3DWaypoint[], progress: number, tension: number | undefined, width: number, taps?: number): Camera3DState;
+//# sourceMappingURL=path.d.ts.map

package/declarations/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAmHlE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,aAAa,CAwCf;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,EACb,IAAI,SAAK,GACR,aAAa,CA0Df"}

package/declarations/registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A region is a participant host (glimmer-motion/participant): its root
+ * renders `data-motion-host` beside `data-choreo`, and registering a region
+ * here registers it as that element's participant host too, so the {{motion}}
+ * elements inside join it. The lookups below are Choreo's own, for code that
+ * already speaks in regions.
+ */
+import { type ParticipantHost } from 'glimmer-motion';
+import type { ChoreoRun } from './run.ts';
+import type { ChoreoNode, TimelineNode } from './types.ts';
+declare module 'glimmer-motion/participant' {
+    interface ParticipantArgs {
+        /**
+         * How Choreo measures this element for a shape-matched flight.
+         * `'box'` (default) is the layout border box — right for plates, cards,
+         * stages. `'content'` is the shrink-wrap (the ink): a full-bleed title
+         * still matches as a word. Written as `data-choreo-pack`; an explicit
+         * `[data-choreo-substance]` descendant still wins.
+         */
+        pack?: 'box' | 'content';
+    }
+}
+/** anything that can put a node on a region's timeline — a step component, or a lane from outside */
+export interface ChoreoProvider {
+    node(): TimelineNode;
+}
+export interface ChoreoHost extends ParticipantHost {
+    /** a destroyed participant asks whether the region still needs its element; true → the region unmounts it later */
+    claim(node: ChoreoNode): boolean;
+    /**
+     * SPIKE (Lane): a provider from OUTSIDE the region's markup — a parent's
+     * lane addressed at this region — whose node joins the tree the region
+     * collects on every pass, after its own steps. Returns the remover.
+     */
+    contribute(provider: ChoreoProvider): () => void;
+    /** the run the region is playing or holding, for an attachment to drive; null between runs */
+    currentRun(): ChoreoRun | null;
+    register(node: ChoreoNode): () => void;
+}
+export declare function setChoreoHost(el: Element, host: ChoreoHost | undefined): void;
+export declare function closestChoreo(el: Element): ChoreoHost | undefined;
+/** the host of a region element itself (not an ancestor's) */
+export declare function choreoHostAt(el: Element): ChoreoHost | undefined;
+/** the host of the region rendered with `@id` — a lane's way of naming the region it plays in */
+export declare function choreoHostById(id: string): ChoreoHost | undefined;
+//# sourceMappingURL=registry.d.ts.map

package/declarations/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,eAAe,EAAsB,MAAM,gBAAgB,CAAC;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK3D,OAAO,QAAQ,4BAA4B,CAAC;IAC1C,UAAU,eAAe;QACvB;;;;;;WAMG;QACH,IAAI,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC1B;CACF;AAED,qGAAqG;AACrG,MAAM,WAAW,cAAc;IAC7B,IAAI,IAAI,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,mHAAmH;IACnH,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,IAAI,CAAC;IACjD,8FAA8F;IAC9F,UAAU,IAAI,SAAS,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,IAAI,CAAC;CACxC;AAMD,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,QAkBtE;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAGjE;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAEhE;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEjE"}

package/declarations/run.d.ts

@@ -0,0 +1,406 @@
+import type { Camera3DState, CameraState, ChoreoNode, Compiled, Cue, PerformCommand, Sprite } from './types.ts';
+/** how fast each value was moving, in units per second, keyed by element then property */
+export type Velocities = Map<HTMLElement, Map<string, number>>;
+export interface Run {
+    /** open the gate the run is parked at; mid-segment, complete the segment and park (§4.1) */
+    advance(): void;
+    /** stop everything; removed sprites are released unless a next run is keeping them (`keep`) */
+    cancel(keep?: Set<ChoreoNode>): void;
+    cues: Cue[];
+    /** the run's full length in seconds at 1×, gates included */
+    readonly duration: number;
+    finished: Promise<void>;
+    /** nothing left to play: the run completed or was cancelled */
+    isDone(): boolean;
+    /**
+     * The sprites this run is DRIVING through space right now — an
+     * unfinished move/spring/tween writing geometry — with each cue's
+     * transition. A replacement pass reads this to complete its score: a
+     * flying sprite the new score does not name gets a continuation move
+     * instead of a one-frame release to rest (§3.1).
+     */
+    midflight(): Map<ChoreoNode, Record<string, unknown> | undefined>;
+    /** standing at a gate, waiting for advance() — a still, and settled */
+    readonly parked: boolean;
+    pause(): void;
+    /**
+     * The run is not advancing itself: paused, parked at a gate, or otherwise
+     * held. Its clock belongs to whoever stopped it.
+     *
+     * A held run keeps writing: inline width, height and transform stay on
+     * every sprite it owns, so the geometry the page reports is the run's
+     * rather than the stylesheet's. Anything deciding whether the world has
+     * changed by measuring it has to know not to trust what it sees.
+     */
+    readonly paused: boolean;
+    play(): void;
+    /** a pass measured and decided to keep this run: put the picture back */
+    reassert(): void;
+    /** put every element this run has touched back to its resting layout NOW */
+    releaseForMeasure(): void;
+    /**
+     * One build backwards — Keynote's rule. Land PARKED at the previous
+     * gate with everything ahead re-closed, and HOLD: a retreat never
+     * plays, never self-opens a @delay gate, and the next advance() replays
+     * the un-built segment forward. False when nothing stands behind the
+     * clock (the caller falls through to whatever "back" means one level
+     * out — an outer run, the previous slide).
+     */
+    retreat(): boolean;
+    /** which gate-bounded segment the clock is in */
+    readonly segment: number;
+    /** playback rate: 1 is normal, 0.5 half, as Motion's controls */
+    speed: number;
+    /**
+     * This run has no end of its own: its score is nothing but OPEN steps, so
+     * it holds them — drawing its wires, keeping its holds — until it is
+     * cancelled or replaced. A standing run is SETTLED, not in flight: there
+     * is nothing to wait for, and `finished` will not resolve until a cancel.
+     */
+    readonly standing: boolean;
+    /** the clock, in seconds at 1× — settable; setting it across a gate parks there */
+    time: number;
+    /** what every driven value was doing at the moment of interruption */
+    velocities: Velocities;
+}
+interface RunOptions {
+    /** where the region's frame stands as this run begins */
+    camera?: CameraState;
+    /** where the SHOT stands as this run begins — a 3D host's own pose */
+    camera3d?: Camera3DState;
+    /** the aim point the prior run left applied — see ChoreoRun.cameraAim */
+    cameraAim?: {
+        x: number;
+        y: number;
+    } | null;
+    /** the element the camera transform drives (the region's scene wrapper) */
+    cameraFrame?: HTMLElement;
+    /**
+     * Nothing in this region is staying — every participant it can see is a
+     * leaver. See the note in `park`: it decides whether a gate this run stops
+     * at is a gate anybody could still open.
+     */
+    doomed?: boolean;
+    inherit?: Velocities;
+    /** a camera step landed or the run ended: the frame's new resting state */
+    onCamera?(state: CameraState): void;
+    /**
+     * The 3D shot moved. Called every frame a `c.Camera3D` cue changes the
+     * pose — including on a scrub, because the pose is sampled from the
+     * score rather than remembered from playback. Choreo has no renderer of
+     * its own; this is where the host's does the drawing.
+     */
+    onCamera3D?(state: Camera3DState): void;
+    /**
+     * A `c.Perform` command entered the folded set: dispatch it (§C4).
+     * Deferred past the render pass, in time order, once per fold entry.
+     */
+    onPerform?(command: PerformCommand): void;
+    /**
+     * The folded set shrank — the clock moved to before a command the host
+     * already holds. Reset commanded state; the remaining prefix is
+     * re-dispatched, in order, immediately after.
+     */
+    onPerformReset?(): void;
+    onSpriteDone(sprite: Sprite): void;
+    /** the region's elevated layer, where c.Raise promotes the living */
+    raisedLayer?: HTMLElement;
+    removed: Sprite[];
+    /** the svg the tethers draw into */
+    tetherLayer?: SVGSVGElement;
+}
+export declare class ChoreoRun implements Run {
+    cues: Cue[];
+    velocities: Velocities;
+    finished: Promise<void>;
+    private master;
+    private playing;
+    private parkedAt;
+    private rate;
+    private readonly scale;
+    readonly standing: boolean;
+    private readonly total;
+    private readonly gates;
+    private tracks;
+    private readonly rowEnd;
+    private released;
+    private pending;
+    private readonly options;
+    private borrowedValues;
+    /** rest is what releaseForMeasure jumps to: 0 for translates, 1 for scales, 'none' for clips */
+    private movedValues;
+    /** what the last releaseForMeasure retired, so a kept pass can put it back */
+    private retired;
+    private owned;
+    private cancelled;
+    private ended;
+    private resolveFinished;
+    private ticking;
+    private autoTimer;
+    constructor(compiled: Compiled, options: RunOptions);
+    get duration(): number;
+    get paused(): boolean;
+    get time(): number;
+    set time(seconds: number);
+    get speed(): number;
+    set speed(rate: number);
+    get segment(): number;
+    get parked(): boolean;
+    /**
+     * ATTACH: write each attached region's clock from this one's.
+     *
+     * Several windows may name one region — a film's every beat has a plate
+     * window, and the plate is one region re-keyed per beat — so the run
+     * resolves ONE governing window per region on every evaluate: the window
+     * that holds `now`; else the latest past one, if it holds; else the
+     * earliest future one, which stands the child at its head (Remotion's
+     * premount: mounted early, clock frozen at `in`). The child's run is
+     * paused and told `in + (now − start) × rate`. No history is kept on
+     * either side, which is what makes a seek into a window land where
+     * playing there would.
+     */
+    private driveAttachments;
+    /** does this run's score integrate — a spring, a follow — so that its state is its history? */
+    hasIntegrator(): boolean;
+    isDone(): boolean;
+    midflight(): Map<ChoreoNode, Record<string, unknown> | undefined>;
+    pause(): void;
+    play(): void;
+    advance(): void;
+    retreat(): boolean;
+    private startTicking;
+    private stopTicking;
+    private tick;
+    private park;
+    private finish;
+    private setPaused;
+    private seekTo;
+    /**
+     * The one cost WAAPI acceleration charges a scrubbable run: a finished
+     * accelerated animation commits its finals asynchronously, and that
+     * commit can land AFTER a still's jump and overwrite it. So a still is
+     * re-asserted on the two frames after it is entered — by then any
+     * pending commit has landed, and the computed frame wins again.
+     */
+    private restillPending;
+    private scheduleRestill;
+    private restill;
+    private evaluate;
+    /** perform tracks whose commands the host currently holds (see foldPerforms) */
+    private performed;
+    /** dispatches queued for after the render pass, in fold order */
+    private pendingPerforms;
+    private performFlushBooked;
+    /**
+     * The command fold (§C4): the set of Perform cues at or before the
+     * clock IS the commanded state. Every evaluate — a play tick and a seek
+     * alike — re-derives the eligible set; growth dispatches the new
+     * commands in time order, and any shrink (a backward seek) resets the
+     * host first and replays the whole remaining prefix. Commands are
+     * idempotent statements of state by contract (`lamp.on`, never a
+     * toggle), which is exactly what makes the replay a re-derivation.
+     *
+     * Dispatches are DEFERRED past the render pass: the constructor's first
+     * evaluate runs while Glimmer may still be rendering, and a command
+     * exists to mutate application state. A reset collapses the queue — the
+     * dropped dispatches were never seen, and the replay that follows
+     * restates everything still standing.
+     */
+    private foldPerforms;
+    /**
+     * Stand rewound tracks back on their origins — the part of a backward
+     * seek that must be ORDERED. A sprite with sequential cues has one
+     * origin per cue, each equal to the previous cue's landing; restored
+     * in track order they clobber forward and the sprite ends up standing
+     * on its LAST future cue's origin (the Playhead demo's hand parked on
+     * 'place' after a scrub to zero; its receipt refusing to dismiss). So:
+     * latest-first, which leaves the EARLIEST future cue's origin — the
+     * value the timeline actually holds at `now` — standing; and a key
+     * that any track AT or BEFORE `now` writes is not touched at all,
+     * because that track's own sample or landing is the answer.
+     */
+    private rewind;
+    /** the eased progress of a plain clock-driven track */
+    private flightlessProgress;
+    /**
+     * The orbit pose in force. Public for the same reason `camera` is: it is
+     * hand-off state, and a replacement run must continue from where this
+     * one left the shot rather than snapping back to the framing.
+     */
+    camera3d: Camera3DState;
+    private readonly initial3d;
+    camera: CameraState;
+    /**
+     * The aim point P in force, local px. With transform-origin pinned at
+     * 0 0, the applied transform is translate(x + (1−z)·P) scale(z) — the
+     * frame's centre cancels out of the algebra entirely, so neither a
+     * board that reflows mid-cue nor a stage that changes height between
+     * cues can move the picture: the formula reads no live DOM at all.
+     * z = 1 is the identity for any P. Public because it is hand-off state:
+     * the next run lerps from the point THIS run left aimed, exactly as it
+     * inherits the camera.
+     */
+    cameraAim: {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * The absolute pose a camera cue lands on, resolved against the pose it
+     * starts from. Absolute fields pass through; missing fields hold; a
+     * relative cue (Pan / SlowZoom) offsets and multiplies the pose in
+     * force — which is why resolution happens AT START (live) or during the
+     * prefix fold (reconstruction), never at compile.
+     */
+    private static resolveCameraTo;
+    private cameraProgress;
+    /**
+     * The camera and aim this run inherited, frozen at construction — the
+     * fold origin every reconstruction starts from. Public because a
+     * replacement run that re-executes the SAME score must inherit this
+     * origin, not the pose in force: the pose in force is what the score's
+     * prefix already produced, and folding the prefix from it applies every
+     * relative cue twice (the world-dock law).
+     */
+    readonly initialCamera: CameraState;
+    readonly initialAim: {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Rebuild the camera fold from the score prefix before a seek's still
+     * (notes/external-clock-camera-seek-handoff.md). Forward playback folds
+     * each camera cue's landing into the run's cumulative camera as the
+     * clock crosses it — but a random-access seek can jump clean over a
+     * window, and a cue that never starts never folds: the clock reads `t`
+     * while the picture holds an earlier shot. So every camera track's
+     * bookkeeping (started, cameraFrom, aimFrom/aimTo, cameraP) is
+     * re-derived here in timeline order from the run's initial camera;
+     * evaluate() then recomputes exactly the numbers forward playback would
+     * have produced, and play-after-scrub resumes from them. Pure
+     * arithmetic over frozen numbers, like the rest of the camera: no DOM
+     * is read, so backward and repeated seeks agree to the pixel.
+     */
+    private reconstructCameraAt;
+    /**
+     * The damped counter-scale (§6.4): steady sprites scale with the host but
+     * not 1:1 — pow(z, .30) zoomed out so they stay readable, pow(z, .70)
+     * zoomed in so they don't feel stuck, clamped to what the eye tolerates.
+     */
+    private static damped;
+    /**
+     * The frame's APPLIED transform for a camera state at aim progress `p`.
+     *
+     * Transform-origin is pinned at 0 0, so the applied transform is
+     * translate(x + (1−z)·P) scale(z) with P the lerped aim point — pure
+     * arithmetic over frozen numbers. Nothing here reads the DOM, so a board
+     * that reflows mid-cue cannot move the camera, and every boundary
+     * (landing, re-aim, next run) agrees to the pixel. At z = 1 the aim term
+     * vanishes: an unpanned camera is EXACTLY the identity.
+     */
+    private appliedCamera;
+    private static cameraCss;
+    /**
+     * Fly the region's frame on the platform: two transform keyframes and the
+     * eased clock pre-sampled into a linear() easing. The biggest layer in the
+     * region composites off the main thread for the whole move.
+     */
+    private startCameraAnimation;
+    /**
+     * Retire the frame's platform animation and hand the picture back to
+     * inline style, written from the shadow state — so a cancel mid-zoom
+     * freezes exactly where the eye was, and a landing holds its final.
+     */
+    private dropCameraAnimation;
+    private applyCamera;
+    private tetherDrawScheduled;
+    private scheduleTetherDraw;
+    /**
+     * One frame of a derived value (§4.10): compose the context from the
+     * pass's measurements, hand it to the author's function, write what
+     * comes back.
+     *
+     * Nothing here touches the DOM — that is the design, not an
+     * optimisation (docs/postmortem-follow.md). The resting boxes were
+     * measured by the pass with every moved value released, and a source's
+     * `now` is its resting box composed with the motion values driving it
+     * this frame: JS-side numbers, not a measurement. So a follower is pure
+     * BY CONSTRUCTION — there is no live box in reach, it cannot read back
+     * its own output, and it cannot force a style recalculation in the
+     * middle of a move. It is also correct under INTERRUPTION for free: a
+     * replacement run's pass re-measures, so a run born mid-flight computes
+     * from rests that are right immediately, with no "last frame" to
+     * disagree with.
+     *
+     * `set`, not an animation: a derived value IS the frame, so there is
+     * nothing to interpolate toward and nothing the compositor could be
+     * given — this is the main-thread cost the step charges, and the reason
+     * it is the same cost `c.Tether` already pays.
+     */
+    private drive;
+    /** the window closed (or was scrubbed out of): put the declared rest back */
+    private restDerived;
+    private drawTether;
+    /**
+     * The scale between the layer's own pixels and the screen's, per axis.
+     *
+     * A promotion reads client rects and writes LOCAL pixels, and every
+     * transform above the region — a camera zoom, a page crossing carrying the
+     * whole scene, any ancestor with a scale on it — sits between the two. Read
+     * off the layer itself: its rect is what the screen shows, its offset size
+     * is what its own coordinate system calls that. Dividing by the camera zoom
+     * alone would catch the region's own transform and miss everything outside
+     * it, which is the double-scale the tether draw already dodges by mapping
+     * through the screen CTM.
+     */
+    private static layerScale;
+    private promote;
+    private restore;
+    private startScroll;
+    private stopScroll;
+    /** stop a track's animations at the value level — an async animation
+     *  cancelled before it resolves stays 'idle' forever if only the controls
+     *  are stopped, and its value then reads as animating for good */
+    private stopTrack;
+    /** land a cue's end values without ever having played it */
+    private jumpFinals;
+    private startTrack;
+    /** put the sprite at progress `p` of its sampled flight path (§4.4) */
+    private applyFlight;
+    /** the eased progress a flight sits at, `ms` into its window */
+    private flightProgress;
+    /**
+     * The sampled path as platform keyframes: each point becomes a transform,
+     * uniformly spaced (the points were sampled uniformly in progress), and
+     * the eased clock rides the animation's easing instead of per-frame JS.
+     */
+    private flightKeyframes;
+    private startFlight;
+    /** compute one still frame of a cue and jump the values onto the element */
+    private sampleStill;
+    private completeTrack;
+    private pinStarts;
+    private sampleVelocities;
+    releaseForMeasure(): void;
+    /**
+     * A pass measured this run's world at rest and then decided to KEEP the
+     * run — but the measurement itself was destructive: releaseForMeasure
+     * cancels platform animations, returns borrowed values, and jumps every
+     * moved value to rest, and a MotionValue.jump() STOPS the animation
+     * driving it. Left like that, a kept run keeps its clock and its landing
+     * but loses its picture: the flight freezes at rest until the finals
+     * land — which on a busy page (the gallery: neighbours re-pass the
+     * region every render) is every crossing, every time. So the keep path
+     * calls this: moved and borrowed values are stood back where they were,
+     * their bookkeeping is re-registered, every in-flight track's animation
+     * is retired so evaluate re-enters it — the machinery a scrub-then-play
+     * already uses — and the re-entered animations are seeked back onto the
+     * run's own clock, so a keep is invisible rather than a restart.
+     */
+    reassert(): void;
+    cancel(keep?: Set<ChoreoNode>): void;
+}
+/** every live run, for the test helpers that drive gates and clocks */
+export declare const activeRuns: Set<ChoreoRun>;
+export declare function execute(compiled: Compiled, options: RunOptions): ChoreoRun;
+export {};
+//# sourceMappingURL=run.d.ts.map

package/declarations/run.d.ts.map

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

package/declarations/space.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The coordinate contract (docs/planes-and-cameras.md).
+ *
+ * A plane's camera is pure arithmetic over frozen numbers: with
+ * transform-origin pinned at 0 0, the applied transform is
+ * `translate(x + (1−z)·P) scale(z)` for aim point P (§6.3). Because it
+ * is arithmetic, it is invertible WITHOUT reading the DOM — and these
+ * two inverses are the whole compositor ⇄ plane-local ⇄ viewport
+ * conversion: cross-plane flights, cross-plane hit testing, and
+ * eventually cross-plane drag all reduce to them.
+ *
+ * A plane that scrolls adds its scroll offset to the same arithmetic —
+ * the one place a DOM read (the scroll position) legitimately enters,
+ * read once per conversion, never per frame.
+ */
+import type { CameraState, Rect } from './types.ts';
+export interface PlanePoint {
+    x: number;
+    y: number;
+}
+/**
+ * The translate the camera actually applies at aim point `aim` — the
+ * same algebra `applyCamera` paints with. At z = 1 the aim term
+ * vanishes: an unpanned camera is exactly the identity.
+ */
+export declare function appliedCamera(cam: CameraState, aim?: PlanePoint): PlanePoint;
+/** plane-local box → page space, through the plane's camera and scroll */
+export declare function toPage(local: Rect, cam: CameraState, aim?: PlanePoint, scroll?: PlanePoint): Rect;
+/** page-space box → the plane's local space: `(page − applied)/z + scroll` */
+export declare function toLocal(page: Rect, cam: CameraState, aim?: PlanePoint, scroll?: PlanePoint): Rect;
+//# sourceMappingURL=space.d.ts.map

package/declarations/space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space.d.ts","sourceRoot":"","sources":["../src/space.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,WAAW,EAChB,GAAG,GAAE,UAAmB,GACvB,UAAU,CAKZ;AAED,0EAA0E;AAC1E,wBAAgB,MAAM,CACpB,KAAK,EAAE,IAAI,EACX,GAAG,EAAE,WAAW,EAChB,GAAG,GAAE,UAAmB,EACxB,MAAM,GAAE,UAAmB,GAC1B,IAAI,CAQN;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CACrB,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,WAAW,EAChB,GAAG,GAAE,UAAmB,EACxB,MAAM,GAAE,UAAmB,GAC1B,IAAI,CAQN"}