@cardstack/choreo 0.0.0 → 0.1.0-unstable.0

package/declarations/film/film.d.ts

@@ -0,0 +1,1208 @@
+import Component from '@glimmer/component';
+import { type FilmVocabulary } from './graph/host';
+import type { PictureSpec } from './picture';
+import { type RailMark } from './rail';
+import { TICK } from './schedule.ts';
+import type { Beat, Chapter, FilmClock, FilmHandle, Join, Over, Picture } from './types.ts';
+/**
+ * `<Film>` — a headless cutting room, in which a 3D scene takes the place
+ * of the video track.
+ *
+ * The model is an editor: one clock, a shot list dropped onto it, and
+ * components that read the clock — the lens, the joins, the type, the
+ * voice, the timeline. The film is a pure function of that clock, which
+ * is why a beat can be widened and the type, the voice, the transport
+ * and the readout all re-time together. The picture is whatever the film
+ * hands in through the `Picture` port; two reference films hand in a
+ * WebGL page in an iframe (notes/film-construct.md).
+ *
+ * THE CAMERA. The score authors the shot and the lens CHASES it: one
+ * critically-damped stage here, the page's own chase as the second, so
+ * two integrators in series bound the jerk. That is what gives the films
+ * their hand-held quality, and it is exactly what forfeits seeking — so
+ * a skip here is an edit, never a seek: the score is re-cut from a
+ * chapter's head and replays.
+ *
+ * WHAT THE POSE ARGS MEAN (an orbit rig):
+ *   yaw    → the orbit's azimuth, degrees
+ *   pitch  → elevation, degrees
+ *   dolly  → magnification: 1 fits the subject, bigger is tighter
+ *   lookY  → how far up the subject the lens aims, from the rig's mid-height
+ *   fx, fz → where on the ground the lens aims
+ *   ox     → an off-centre frustum, fractions of the frame
+ */
+/**
+ * ONE TICK IS TWO SECONDS, and every beat is a whole number of them.
+ * `@through` splits its clock evenly between waypoints, so a beat buys
+ * the screen time it wants by contributing that many waypoints to the
+ * path — and a beat that wants to HOLD contributes the same pose several
+ * times over, which a Catmull-Rom spline comes smoothly to rest on.
+ */
+export { TICK };
+export interface FilmSignature {
+    Args: {
+        /** which cut of the film this is: logged at boot, shown under `?debug` */
+        build?: string;
+        /** the film's own clock, when the picture keeps one (years) */
+        clock?: FilmClock;
+        /** mounted in a page's iframe: the door still opens it, but no transport and no plate */
+        embed?: boolean;
+        /** the seam a beat gets when it names none */
+        join?: Join;
+        /** the chapter menu's second line */
+        menuSub?: string;
+        /** the film's name, as the menu heads it */
+        menuTitle: string;
+        /** a short name for the film (a body class, the boot log) */
+        name: string;
+        /** the air of a shot has been applied: grade, sun, weather — a hook for what the construct does not know */
+        onAir?: (beat: Beat, picture: Picture, hard: boolean) => void;
+        /** a beat has landed — a hook for what the construct does not know */
+        onBeat?: (beat: Beat, picture: Picture) => void;
+        /**
+         * HOW DEEP THE FILM'S SEAMS GO, when a beat does not say. `picture`
+         * (the default) transitions the picture and makes the incoming type
+         * wait for the seam; `everything` puts the seam above the type, the
+         * insert and the clip, so the incoming setting is already under way
+         * when the sweep reveals it. See `Over`.
+         */
+        over?: Over;
+        /**
+         * THE RAIL — the film on one line, on the picture: chapters as dots
+         * on a rule, the head riding it, the year when the rule is a clock.
+         * It is the second film's transport and not every film's: a film
+         * whose own bar is the whole story of its progress says `false` and
+         * keeps the floating player alone.
+         */
+        rail?: boolean;
+        /**
+         * HOW THE FILM SEEKS — the fork everything hangs on.
+         *
+         * `cut` (the default) is the hand-held film: a cascaded spring chases
+         * the score, which is what gives the lens its sway and its arrival at
+         * pace, and exactly what forfeits random access — a spring's state is
+         * its history, so a skip re-cuts the score from a chapter's head.
+         *
+         * `exact` makes the whole film a pure function of one clock: no
+         * integrator in the pose path, the beat in force derived from the
+         * time, the seams driven by it, the type's run seeked to it. Scrub
+         * anywhere and the frame is correct; `renderAt(t)` on a fresh page is
+         * the same frame as playing there. It used to cost the hand — the
+         * spring was the only thing softening the spline, and an exact film
+         * could not have one. `@settle` is that hand written as a function of
+         * the clock, so it no longer does.
+         *
+         * What `exact` still costs is a read-back per cut: every seam holds a
+         * still of the outgoing frame, because the page's own dissolves run
+         * on their own clock.
+         */
+        seek?: 'cut' | 'exact';
+        /**
+         * THE OPERATOR'S SECOND HAND, in seconds.
+         *
+         * The camera path is a spline through every shot's pose, and a spline
+         * crosses its control points with a step in curvature — a tick, on
+         * every waypoint, for the whole running time. A spring chasing the
+         * pose hides it and cannot be seeked; this is an average of the path
+         * over a window this wide, which is the same cure written as a pure
+         * function of the clock (`settleThrough`). Zero turns it off.
+         *
+         * Keep it well under the gap between waypoints — a film that holds a
+         * pose for two seconds wants a fraction of a second here, not two —
+         * or the lens stops visiting the poses the score wrote.
+         */
+        settle?: number;
+        /** the level each line was mixed to (0..1) */
+        voGain?: Record<string, number>;
+    };
+    Blocks: {
+        /** under the stage, outside the picture: a wall plate, a cutting room */
+        default: [FilmContext];
+        /** the back matter, inside the end card */
+        end: [FilmHandle];
+        /** the front matter, on the door */
+        gate: [FilmHandle];
+        /** the picture: a component that registers what it is (`IframePicture`), and declares `f.picture.*` */
+        picture: [(spec: PictureSpec | null) => void];
+    };
+}
+/** what the blocks are given: the handle, and the vocabulary a film's score is written in */
+export type FilmContext = FilmHandle & FilmVocabulary;
+export declare class Film extends Component<FilmSignature> {
+    /**
+     * THE GRAPH, compiled. A film written as `f.Spine` / `f.Chapter` /
+     * `f.Shot` in the default block compiles to the same rows a table would
+     * hand in (`graph/compile.ts`); the table arguments, when given, win.
+     */
+    private graph;
+    private takeGraph;
+    /**
+     * THE PICTURE, as it registered itself from the `<:picture>` block: the
+     * page, its files, how it is seated, its rig, its moods. Nothing here
+     * is about the edit, which is why none of it is an argument any more.
+     */
+    private picture;
+    private takePicture;
+    private get assets();
+    private get standing();
+    private get frameTitle();
+    /**
+     * THE WHOLE SHOT LIST, and there is only one place it comes from: the
+     * score in the default block, compiled. The film used to take a
+     * `Beat[]` as an argument as well, which is how both films were fed
+     * until Phase 2 migrated them; the table path is gone now that nothing
+     * hands one in, and the graph is the only way to write a film.
+     */
+    private get all();
+    private get chapters();
+    private get voSecs();
+    private get voGain();
+    private get grades();
+    private get lookFx();
+    private get lutAmount();
+    private get defaultJoin();
+    /**
+     * WHERE THIS SEAM IS PLAYED. A seam the PICTURE declares by name is
+     * played in its glass with that name; the three the film knows how to
+     * mix are played there under the film's own law; everything else is an
+     * overlay in this document. The name is the only thing that decides,
+     * which is what makes the vocabulary open: a picture that declares
+     * `ridged-burn` gets `<f.Join @presentation="ridged-burn" />` for free,
+     * and the film learns nothing about it but its length.
+     */
+    private glassFor;
+    /** how deep a seam goes when nothing says: the film's own default */
+    private get defaultOver();
+    /**
+     * HOW DEEP THIS BEAT'S SEAM GOES. The row says, or the presentation
+     * says, or the film does. A seam that covers the furniture is always a
+     * seam with a still in the DOM: the picture's own glass is inside the
+     * canvas and cannot cover anything outside it.
+     */
+    private overOf;
+    /** every seam the film can play: its own twelve, and any the score brought */
+    private get presentations();
+    /** seconds a seam holds the picture; nothing, for one the film does not know */
+    private secsOf;
+    /** does the seam paint a still of the outgoing frame over the incoming one */
+    private holdsStill;
+    /** how much of a frosted city a film frame can carry */
+    private get cityGlass();
+    /** the rig's mid-height: `lookY` is world height minus this */
+    private get rigMid();
+    /** how much the passing cloud thickens the air */
+    private get cloudHaze();
+    /** the face type in the world is set in; a film that names none of it
+     *  leaves the page's own */
+    private get worldFamily();
+    private get worldWeight();
+    private get worldTrack();
+    /** the editorial accent: the film's own, or the scene's palette by day */
+    private accentFor;
+    /** the film's handles, as the door and the card are given them */
+    get handle(): FilmContext;
+    private get exact();
+    /** the master clock: seconds into the whole film (exact mode) */
+    private t;
+    /** a seek happened since the last fold: it lands instantly, seam re-made */
+    private jumped;
+    /** the score region's context, read every frame for its current run */
+    private scoreCtx;
+    private scoreRun;
+    /** the element the seam overlays live in, so their animations can be seeked */
+    private joinsEl?;
+    /** where the seam on screen began, film seconds, and how long it plays */
+    private seamAt;
+    private seamLen;
+    /** the lead whose air has been applied ahead of its beat */
+    private airedFor;
+    /** where the sun was before this beat asked, for a deterministic walk */
+    private sunFrom;
+    /**
+     * THE CLIPS ON SCREEN, one row per lane, in lane order — which is also
+     * paint order. There used to be one of these and a beat that declared
+     * two clips kept the second one only.
+     */
+    private clipRows;
+    /** the picture read back, per lane, for a freeze */
+    private clipFreezes;
+    private clipNow;
+    private clipMedia;
+    private clipEl;
+    /**
+     * THE CLIP, EVERY FRAME. Resolve what should be on screen at this film
+     * time, land the DOM when that changes (a new window is a new element,
+     * so the entrance replays), and drive the media: a playing video is
+     * left to run and corrected when it drifts, a paused or scrubbed one
+     * is seeked, a held one stands at its out point, a frozen one is left
+     * alone. A freeze reads the picture back when its window opens — or,
+     * on a seek into it, after the page has been stood at that moment.
+     */
+    private clips;
+    /**
+     * ONE LANE'S MEDIA, every frame. A playing video is left to run and
+     * corrected when it drifts, a paused or scrubbed one is seeked, a held
+     * one stands at its out point, a frozen one is left alone.
+     *
+     * A CLIP'S SOUND NEVER STEPS. The element arrives at zero and is eased
+     * up to its level, and when its window closes it is eased back down
+     * before the exit fade takes the element away — a source that starts or
+     * stops at level is a click, whatever it is playing.
+     */
+    private driveClip;
+    /**
+     * THE PICTURE AT A MOMENT THAT HAS PASSED. A freeze seeked into needs
+     * the frame from its window's head: the score is stood there for one
+     * evaluation (the camera step reports the pose), the page is posed and
+     * clocked to that moment, and the fold's own time is restored after
+     * the read-back.
+     */
+    private freezeClipAt;
+    /**
+     * FILM SECONDS AT WHICH A BEAT'S OWN SHOT BEGINS. The cues fire one
+     * tick after the beat table says, because the pose-in-force seed
+     * occupies the spline's first slot — so the windows the exact clock
+     * derives carry the same offset, and the picture and the type agree
+     * with the cut film to the frame.
+     */
+    private beatStart;
+    /** the beat in force at a film time */
+    private indexAt;
+    /** the score's region, held so its run can be driven by the clock */
+    private grabScore;
+    private joinsWrap;
+    /** the score must stand even while paused: a paused exact film is a still */
+    get scoreOn(): boolean;
+    /**
+     * SEEK. In exact mode the clock is set and the next fold lands there;
+     * in cut mode the nearest shot's head is re-cut to, which is the only
+     * honest seek a chased lens has.
+     */
+    private seek;
+    /**
+     * A STILL AT A TIME, for a capture worker: pause, seek, run one frame
+     * of the loop against a zero step, and give the page two frames to
+     * draw it. The same code path as playing there — that is the claim.
+     */
+    /** a frame is being rendered rather than scrubbed to: seams play */
+    private rendering;
+    /**
+     * A RENDER OPENS THE DOOR ITSELF.
+     *
+     * `?from=0` puts the title card up and leaves the film unbooted — and
+     * an unbooted film HAS NO SCORE, because the whole `<Choreo>` sits
+     * behind `{{#if this.booted}}` (the rig has to be an insertion before
+     * the camera step has a subject). So `fold`'s `run.time = t` wrote to
+     * a null run, `onCamera3D` never fired, `goal` stayed wherever the
+     * load path's `snap` seated it, and exact mode copied that one pose
+     * forward on every frame. Measured on towers, a stepped render swept
+     * half a degree of yaw across 273 seconds where the compiled path
+     * sweeps 380 — a whole render of a frozen lens, and `film-render.mjs`
+     * hit it every time, because its default `--from` is 0.
+     *
+     * A render is a request for the film, not for the lobby. So it opens
+     * the door itself, MUTED — nothing was clicked, and no browser hands
+     * out audio for a gesture nobody made.
+     */
+    private renderAt;
+    /**
+     * THE DOOR, OPENED BY A SCRIPT. Two waits, and neither is optional.
+     *
+     * The handle publishes itself from the mount modifier, a frame before
+     * the iframe's load seats the port — so a renderer that polls for
+     * `__choreo[name]` can call in before there is a picture to begin
+     * against, and `begin` would only pocket the choice. And `begin`
+     * itself DEFERS the lap bump that buys the score region its second
+     * render pass: until that pass lands the run does not exist, and a
+     * seek against a missing run is exactly the frozen lens this avoids.
+     *
+     * Both waits are bounded. A render against a film that never arrives
+     * degrades to the frame it would have drawn before, rather than
+     * hanging the worker on a promise that will not settle.
+     */
+    private openTheDoor;
+    /**
+     * THE FOLD (exact mode): the beat in force is the one whose window
+     * holds the clock; entering it — forward by playing, or by a seek in
+     * either direction — applies it whole, because every beat asserts its
+     * complete state and never inherits. A seek that lands inside a seam
+     * re-makes the outgoing frame first, so the seam plays from the middle
+     * exactly as it would have played into it.
+     */
+    private fold;
+    /** a line, from the middle: what a seek owes the voice */
+    private speakAt;
+    /**
+     * THE SEAM'S GATE (`film/seam.ts`). A join's still is a JPEG the
+     * browser has not decoded yet on the frame it is handed over, and the
+     * lens moves on that frame — so every cut used to show three frames of
+     * the incoming shot before the outgoing one was on screen. The gate
+     * decodes first and holds the cut; a seam with no still runs at once.
+     */
+    private seam;
+    /**
+     * THE SEAM, EXACT. Every join that carries the outgoing frame carries it
+     * as a still in the DOM — the page's own dissolves run on the page's
+     * clock and cannot be stood at a time — and the whip, which is the
+     * chaser's, becomes a cut. The overlay is then driven by the fold.
+     */
+    private seamExact;
+    /** the seam itself: the still on screen, the lens on the incoming shot */
+    private seamPlay;
+    /** the last cue has run: hold the pose, settle the music, offer the card */
+    private end;
+    /** the beat on screen; the score names it, the front layer renders it */
+    private beatIndex;
+    private playing;
+    /** bumping this edits the score, which is how a finite film loops */
+    private lap;
+    private booted;
+    /** which seam is playing, and a key that replays it: bumped on every cut */
+    private joinKind;
+    private joinStamp;
+    /** the seam on screen covers the furniture, not only the picture */
+    private joinOver;
+    private overTimer;
+    /**
+     * THE SEAM IN THE GLASS. Its kind, how long it has and the colour it
+     * passes through — and `reveal`, how much of the incoming frame is NOT
+     * covered by it, which is the film's other half: the type, the stamp
+     * and the inserts wear it, so a caption is uncovered by the same
+     * gesture that uncovers the picture.
+     */
+    private glassKind;
+    /** the picture's own name for it, when the picture declared this seam */
+    private glassName;
+    private glassLen;
+    private glassColor;
+    private reveal;
+    /** the captured outgoing frame every freeze-based join plays with */
+    private freeze;
+    /** the 'dip' join's veil colour */
+    private dipColor;
+    /** where the iris closes to, as inline custom properties */
+    private irisAt;
+    /** dev beacon: the first uncaught error, worn on the sleeve */
+    private fault;
+    /**
+     * THE SEAM, DRIVEN. Half of it is the picture, which is handed two
+     * numbers and composites them in light; half is the furniture, which
+     * wears what is left over. Both come from one progress, and that
+     * progress is a function of the clock — so a seek through a seam needs
+     * nothing stood at a time, which is what the DOM overlay always did.
+     */
+    /** take a driven seam off: the picture back to live, the furniture whole */
+    private endSeam;
+    private driveSeam;
+    /**
+     * Run a seam's overlay: a new element per cut, from its own first
+     * frame. A seam played `everything` is lifted above the type, the
+     * insert and the clip for as long as it runs, and put back after — an
+     * empty layer left standing over the furniture would swallow the next
+     * shot's pointer events, and there is no event for a CSS animation the
+     * film did not start.
+     */
+    private play;
+    /**
+     * THE ENDING. A film that laps back to its own first frame has no
+     * ending, and the coda earns one — so when the last cue has run, the
+     * run simply stops: the final pose holds, the music settles down a
+     * step, and a card offers the way back in. Replay is a choice the
+     * viewer makes, never something the clock does to them.
+     */
+    private ended;
+    /**
+     * THE YEAR IS THE SUBJECT. A film whose whole argument is that one
+     * building took a hundred and forty-four years cannot leave the audience
+     * to infer the date from the state of the scaffolding: the year is on
+     * screen, and it is on a line from the first stone to the present, so
+     * 1954 is not a number but a POSITION — two thirds along a rule that
+     * still has a third to run.
+     */
+    private yearNow;
+    private yearSent;
+    /** whether the announced year is currently seated in the scene */
+    private stampOn;
+    /** the page has been told the picture is static — see the frame loop */
+    private idled;
+    private gradeSent;
+    private rakeSent;
+    private rakeDeg;
+    /** which beat's lightning cue has fired (reset on every beat change) */
+    private struck;
+    /** which of the beat's hours (Beat.hours) is in force; -1 between beats */
+    private hourStep;
+    /** the next grade goes to the glass without its ease (a still-join) */
+    private gradeSnap;
+    /** the last stock sent to the glass, by name; undefined before the first */
+    private lutSent;
+    /** the last hour a beat named, so the night can be known without naming it again */
+    private hourNow;
+    /** the scrub track's width in px, kept by a ResizeObserver */
+    private trackW;
+    private trackRO?;
+    /** the chapter fractions the bar is drawn with, computed once */
+    private segFr?;
+    private trackWrap;
+    /**
+     * THE KNOB IS THE FILL'S END. The bar is chapters with a gap between
+     * them, so the playhead's position is not linear in the playhead's
+     * value — a second formula for the knob drifts from the fill inside
+     * every segment. This is the one formula: the same fractions the fill
+     * uses, over the measured track, with the gaps added back.
+     */
+    private headPx;
+    /** which tower the lineup's metronome is on; -1 between lineups */
+    private cycleStep;
+    private film?;
+    /**
+     * THE FRAME'S DRESSING, WHERE THE PICTURE CAN TAKE IT.
+     *
+     * The wash and the cloud were CSS layers over the canvas, which meant a
+     * seam could not touch them: the picture dissolved and the paper behind
+     * the type snapped on the cut frame — two edits at once. A transition
+     * applies to what its own container renders, so they belong in the
+     * container, and the container is the picture's post pass (where the
+     * vignette, the grain, the split tone and the grade already live). A
+     * picture that offers `wash`/`cloud` gets them and the film stops
+     * drawing its own; one that does not keeps the CSS layers.
+     */
+    private washInGlass;
+    private cloudInGlass;
+    private dimInGlass;
+    /** the palette's paper, as `wear` last read it, for the wash */
+    private paperNow;
+    /** the last wash the picture was told about: mode and paper, told on change */
+    private washSent;
+    private frameEl?;
+    private lineEl?;
+    private dotEl?;
+    private tetherEl?;
+    private dim?;
+    /** the dim's own value, chased rather than cut so it never snaps on */
+    private dimNow;
+    private plateEl?;
+    private rowEls;
+    private raf;
+    private lastTick;
+    /** when the current beat was entered, for the clocks it owns */
+    private beatAt;
+    /** where the beat's sky word was planted, in world azimuth */
+    private skyAz;
+    /** the azimuth the mark word is planted on, behind the building */
+    private markAz;
+    /** a sideways nudge in world units, for a word too short to centre */
+    private markOff;
+    /** the height the word rises FROM — set when it actually arrives */
+    private markFrom;
+    private markSeated;
+    /** the last pose actually pushed — the final smoothing stage */
+    private sent?;
+    /** the light in force, and the light the beat asked for */
+    private sunNow;
+    private sunGoal;
+    private idle;
+    /** the fraction the hand is holding while scrubbing, else null */
+    private scrubAt;
+    /** the fraction under a resting pointer on the bar, else null */
+    private hoverAt;
+    /** the master fader, 0..1, remembered across visits */
+    private vol;
+    /** the centre-screen glyph that confirms a play or a pause */
+    private burst;
+    /** the viewer's pause: the run, the page and the beat clock all hold */
+    private paused;
+    private pausedAt;
+    /** the lap whose head beat the cut itself already applied */
+    private primedLap;
+    /** the bar's own element, for the slider's live value */
+    private scrubEl?;
+    private shownPct;
+    private clock;
+    private full;
+    private idleTimer;
+    private shownSec;
+    /** the whole film, in seconds, leads included */
+    private get totalSecs();
+    private secsBefore;
+    /** one segment per chapter, sized and placed in whole-film fractions */
+    get playbar(): {
+        head: number;
+        n: string;
+        style: string;
+        title: string;
+    }[];
+    private static mmss;
+    get duration(): string;
+    /**
+     * What the hand is pointing at — resting on the bar or dragging it:
+     * the chapter under it and the time, on two lines, the way every
+     * player's hover bubble does. A drag wins over a hover.
+     */
+    get tip(): {
+        ch: string;
+        t: string;
+    } | null;
+    /** rolling AND not held by the viewer: what the play button shows */
+    get live(): boolean;
+    /** the fader's setting, as it was left last time — one setting for
+     *  every film, the way a viewer's volume is theirs and not the film's */
+    private static savedVol;
+    /** sound on, and the fader up: the speaker glyph's three states */
+    get loud(): 'high' | 'low' | 'off';
+    get volStyle(): string;
+    /**
+     * THE FADER. Dragging it up while muted unmutes, because that is what
+     * the hand means; the value is the page's master gain, under the mix
+     * and the mute, and it is remembered for the next visit.
+     */
+    private fade;
+    /** the glyph that flashes in the middle of the picture on play/pause */
+    private pop;
+    private burstDone;
+    /**
+     * A tap on the picture is play/pause and two taps are full screen —
+     * the grammar of every player since the first one. The controls, the
+     * door, the end card, the rail and the menu keep their own clicks.
+     */
+    private static onGlass;
+    private tap;
+    private tapTwice;
+    /** the bar's own element, for the slider's live value */
+    private slider;
+    private wake;
+    private scrubFrom;
+    /**
+     * The bubble and the ghost fill follow the pointer, not the playhead:
+     * the bubble's x in pixels (held off the edges so it never clips) and
+     * the hover fraction, both as properties, both without a re-render.
+     */
+    private point;
+    private scrubDown;
+    private scrubMove;
+    private scrubLeave;
+    /**
+     * THE PLAYHEAD SNAPS TO A SHOT, because this film cannot seek: the
+     * lens is an integrator and a run dropped into its own middle arrives
+     * with the wrong velocity (docs/choreo-splices.md). So the drag reads
+     * as time, the label names the shot under the hand, and the release
+     * RE-CUTS from that shot's head — which is the same edit the chapter
+     * buttons and the arrow keys make.
+     */
+    /**
+     * A HAND ON THE BAR NEVER LANDS ON THE CARD. The bar's right edge is
+     * the film's last second, and a click there — or a drag that ran off
+     * the end — seeks to the total, which is the ending itself: the card
+     * came up under a hand that wanted the last shot. The bar stops two
+     * seconds short; the ending is reached by playing to it.
+     */
+    private barSecs;
+    private scrubUp;
+    private screen;
+    private fullChange;
+    /**
+     * THE POINTER MOVES THE WORLD A LITTLE.
+     *
+     * A film that cannot be touched is a video, and the whole argument
+     * here is that this is a scene. So the cursor gets a few degrees of
+     * lean: the lens takes a fraction of it (real parallax — the building
+     * and the hills separate) and the type planes take more of it in the
+     * other direction, each layer by its own depth. It is small enough to
+     * be felt rather than played with, and damped, so it never fights the
+     * shot the score is composing.
+     */
+    private lean;
+    private leanTo;
+    private aim;
+    /** the haze the beat asked for — the weather drift breathes around it */
+    private hazeBase;
+    private goal;
+    private mid;
+    private midV;
+    private now;
+    private nowV;
+    /** the world-layer plane's own fade, so a chapter's type breathes in */
+    private skyOn;
+    /**
+     * THE SKY WORD'S OPACITY AS ACTUALLY SENT — not the ramp above.
+     *
+     * `skyOn` only says a word is WANTED; what the word is actually wearing
+     * is that ramp times the beat's own in and out, and the out takes it to
+     * nothing by 68% of the beat. When the next beat had no word the film
+     * used to hand the picture `skyOn` to fade from — a number still sitting
+     * near 1 — so a word that had been gone for seconds snapped back to 92%
+     * on the frame after the cut and faded out a second time, across the
+     * seam. Fade from what the word is wearing instead.
+     */
+    private skyA;
+    /** the time of day the furniture is currently dressed for */
+    private wearing;
+    /** the cast-shadow offset the type is currently wearing, px */
+    private shadow;
+    private pageEl?;
+    /**
+     * WHERE THE CUT STARTS — the arrow keys' one piece of state.
+     *
+     * A film this long is unwatchable without chapter skip, and seeking a run
+     * that carries an integrator is not honest (the chaser's pose depends on
+     * its history, which is the price Drift's doctrine names out loud). So
+     * skipping RE-CUTS instead of seeking: the beat list is sliced here, the
+     * path and the cues are both derived from that list, and the score the
+     * region sees is a different, shorter film. An edited timeline replays
+     * from its own head, which is exactly the behaviour wanted — and it is
+     * the same move Sylva's lap makes to loop.
+     *
+     * `?from=N` seeds it, so a shot can be linked to.
+     */
+    /**
+     * The deep link's shot, as asked (`?from=N`). Clamped against the
+     * rows when READ, never when set: with the score a graph the rows
+     * arrive a frame after construction, and clamping here against zero
+     * rows once made every deep link −1.
+     */
+    private fromRaw;
+    private get from();
+    private set from(value);
+    /** sound is off until asked for: nobody's first second should be音 */
+    private sound;
+    /**
+     * THE GATE. This film is narrated, and narration behind a mute button
+     * is a film shown with the projector lamp off — so the front door asks.
+     * One held frame, one choice, and the choice IS the user gesture that
+     * autoplay policy wants anyway: the browser unlocks audio on the same
+     * click that starts the picture. Museums have worked this way forever.
+     *
+     * `?from` skips it (an authoring link wants the shot, not the lobby)
+     * and so does embedding.
+     */
+    private gate;
+    /** the scene is loaded and seated behind the gate — the door can open */
+    private ready;
+    /**
+     * One pass BEHIND `booted`, on purpose. A region's first render
+     * collects no score, so anything standing in it on that pass — the
+     * first beat's type, a head photo — was never inserted and never
+     * animates. Content mounts on this flag instead, which flips a tick
+     * later: the same render that gives the score its first real pass
+     * hands the front layer a genuine insertion, and the opening beat's
+     * type is DELIVERED like every other beat's instead of being found
+     * already on the glass.
+     */
+    private rolling;
+    get beats(): Beat[];
+    /** the first beat of each chapter, in whole-film indices */
+    get chapterHeads(): number[];
+    /** where we are in the WHOLE film, not the current cut */
+    get absoluteIndex(): number;
+    get beat(): Beat;
+    /**
+     * CAPTIONS. `?subs` seeds them on; CC toggles them.
+     *
+     * They are the narration, printed. That makes them two things at once
+     * and both are wanted: an accessibility track for anyone who cannot or
+     * would rather not hear the voice, and — before any voice exists — the
+     * only reliable way to find out that a line is two seconds too long for
+     * the shot it is sitting on.
+     */
+    private subsOn;
+    get subs(): boolean;
+    private cc;
+    get grade(): string;
+    get chapter(): Chapter;
+    get embed(): boolean;
+    /** `?debug` puts the build stamp in the corner — see `@build` */
+    get debug(): boolean;
+    get build(): string;
+    get srcdoc(): string | undefined;
+    get src(): string;
+    get photoSrc(): string;
+    /** a photograph that failed to load is no photograph — drop the plate */
+    private lost;
+    private lostStamp;
+    get hasPhoto(): boolean;
+    private missing;
+    /** a fresh name per lap: an edited score replays, a restarted one fights */
+    get filmName(): string;
+    /**
+     * HOW MUCH HAND, in seconds — see `@settle`.
+     *
+     * The default is a QUARTER OF THE GAP BETWEEN WAYPOINTS, because that
+     * is the only number that means the same thing to two different films.
+     * A window is smoothing relative to the spacing of the kinks it
+     * smooths: a quarter takes the curvature step off every pose change
+     * and is far too little to stop the lens visiting the poses. Both
+     * films that ship here spend two seconds a waypoint, so both get half
+     * a second; a score that cuts four times as fast gets a quarter of
+     * that without being asked, and half a second imposed on it would have
+     * flattened its shots.
+     *
+     * Capped at half a second so a very slow film does not drift, and
+     * floored at nothing: `@settle={{0}}` gives the raw spline.
+     */
+    get settle(): number;
+    /**
+     * The pose the score OPENS on, declared to the region — without it the
+     * first spline segment travels in from the library's default rig, a
+     * two-second bounce every cold boot wore before its first real frame.
+     */
+    get openPose(): {
+        dolly: number;
+        look: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        pitch: number;
+        x: number;
+        y: number;
+        yaw: number;
+    };
+    get filmSeconds(): number;
+    /**
+     * THE WHOLE FILM IS ONE CAMERA STEP.
+     *
+     * Every beat contributes `ticks` waypoints: a moving beat is sampled from
+     * its head pose to its tail, a holding beat repeats its pose, and the
+     * spline runs through the lot on one clock. So the shot list is a path
+     * rather than a playlist, the camera crosses each mark with velocity
+     * instead of arriving at it, and a hold is genuinely still without
+     * anything having stopped.
+     */
+    /**
+     * WHERE A SHOT ENDS — the beat's authored tail, floored so it always
+     * reads as a move, and clamped so it never travels past the pose the
+     * next shot begins on. Shared by the path (which lerps its waypoints
+     * across it) and by the LAUNCH: a cut hands the chaser this shot's own
+     * speed, so the lens is already travelling when the cut lands rather
+     * than easing up from a standstill.
+     */
+    private tailFor;
+    get path(): import("./schedule.ts").Waypoint[];
+    /**
+     * Each beat's entrance, as a delay into the one camera step — offset
+     * one tick, because the pose-in-force seed occupies the spline's first
+     * slot: waypoint k is crossed at (k+1) slots, not k. The old uniform
+     * skew was invisible (camera and cues equally late, a constant the
+     * chaser's own lag swallowed); a SPLICE made it audible — the snap
+     * fired two seconds before the goal stepped, and the chaser spent the
+     * gap dragged back toward the old shot. Cue 0 stays at zero: the boot
+     * and every re-cut apply their head beat by hand, and its immediate
+     * re-fire has always been the first cue's job.
+     */
+    get cues(): import("./schedule.ts").Cue[];
+    /**
+     * THE ATTACHMENTS: every window the score drives another region over.
+     * The plate for every beat, the insert for a beat with a photograph,
+     * the clip for a beat with one — each on the score's own clock, so a
+     * seek stands all of them where playing there would. The regions are
+     * keyed per beat and mounted for their windows; `remove` past a window
+     * leaves them to that; a clip may outlive its beat and holds.
+     */
+    get windows(): {
+        end: "hold" | "remove";
+        length: number;
+        region: string;
+        start: number;
+    }[];
+    /**
+     * THE TRANSPORT — a broadcast bar, not a thermometer. One segment per
+     * chapter, sized by the chapter's actual running time, filled by
+     * WHOLE-film progress (the old bar measured the current cut, so a
+     * skip made it lie), and clickable: the segments are the same re-cut
+     * the menu and the arrows perform.
+     */
+    /**
+     * ONE TIMELINE, NOT TWO.
+     *
+     * The corner carried a strip of chapter segments beside a rule of years:
+     * two timelines of the same film, at two different scales, in two
+     * different shapes, six inches apart. So the chapters are ON the years
+     * now — each one a dot at the year it opens, so the gap between THE SITE
+     * and SILENCE is fifty-four years wide and the gap between the last two
+     * is a decade, which is the fact the film is about. The dots are still
+     * the doors into the chapters.
+     */
+    get transport(): RailMark[];
+    /** the ends of the rule, when it is a clock */
+    get railLabels(): [string, string] | undefined;
+    /** the rail is on unless the film says otherwise */
+    get railOn(): boolean;
+    get railReadout(): string;
+    /**
+     * WHEN EACH CUE LANDS — paced against the voice, not the clock.
+     *
+     * The phrases used to arrive on four fixed delays, which meant a
+     * fourteen-second beat finished its type with five seconds of dead air
+     * and a short one crowded the read. So the cues spread themselves: the
+     * first lands early, the last lands as the measured line is finishing
+     * (`VO_SECS`), and a beat with no recording paces against two thirds of
+     * its own length, which is where a read for it would sit anyway.
+     */
+    /**
+     * THE TRANSITION FIRST, THEN THE TYPE. A setting that arrives while the
+     * seam is still on screen is read against two pictures at once. The
+     * block waits for the incoming join to finish and a breath more, then
+     * enters in its order: kicker, glyph, reading — and the lines after.
+     */
+    get typeAt(): number[];
+    get sayAt(): number[];
+    /**
+     * Thai and Khmer are not kanji: their ascenders, vowel marks and
+     * subscripts stand far outside a CJK-tuned glyph box, so at the kanji
+     * size they collide with the kicker above and the reading below. Tall
+     * scripts take a reduced setting with real leading.
+     */
+    /**
+     * HOW MANY CHARACTERS HAVE TO FIT. A vertical setting is as tall as
+     * its string, and 一国一城令 is five glyphs — at the plate's own size
+     * that column runs off the top of the frame and the film crops its
+     * own title. The count goes to CSS, which sizes the column to the
+     * height available rather than to a number somebody typed once while
+     * looking at a three-glyph word.
+     */
+    get glyphFit(): string;
+    get glyphTone(): string;
+    /** the lineup's current kanji; empty between lineups */
+    get stamp(): string;
+    /**
+     * THE POSTER IS AN EVENING (by default). The film proper opens in the
+     * morning, so the door stands in the last of the light with a long hard
+     * shadow across the empty half of the frame; pressing it turns the day
+     * over. The film may dress its door otherwise (`@poster`).
+     */
+    private dressPoster;
+    private announced;
+    private mount;
+    private trackEls;
+    private dimEl;
+    private plate;
+    private snap;
+    /**
+     * THE WHIP. A 'whip' join does not snap: the goal steps across the
+     * seam (the splice does that) and the chaser races it on a briefly
+     * stiff spring — a fast, smooth tween between the shots that is over
+     * in a third of a second and never reads as a glide. While it runs,
+     * the spring is ~3× its documentary stiffness; then the hand relaxes.
+     */
+    private whipUntil;
+    /**
+     * One critically-damped stage. The page's own chase is the second, which
+     * is the whole cascade argument getting made for free by the fact that the
+     * scene lives in another document.
+     */
+    private chase;
+    /**
+     * THE POSTER TURNS.
+     *
+     * A still frame behind a title is indistinguishable from a JPEG, and
+     * this whole film's argument is that it is not one. So while the door
+     * is up the lens makes a slow circuit of the opening pose — a few
+     * degrees either side, breathing in and out — which says "live 3D"
+     * before a word is read and costs one rAF. It hands over on the
+     * click: the film does not snap away from the poster, it flies from
+     * wherever the circuit had reached.
+     */
+    private poster;
+    private posterRaf?;
+    private posterAt;
+    /** where the poster's circuit had reached when the door was answered */
+    private posterPose?;
+    /**
+     * ONE SETTING AT A TIME, AND THIS TIME IT IS GUARANTEED.
+     *
+     * The hand-off is a leaver and an arriver sharing the corner for half
+     * a second, which is the design. But a leaver whose exit never
+     * completes just stays — and a block from the first beat was still
+     * standing at full strength eight beats later, with two settings of
+     * different chapters overprinting each other. Whatever strands it (a
+     * removal that waits on a cue the outgoing beat never had), the rule
+     * the film states out loud in its own comment is worth enforcing
+     * rather than trusting: any block that is not the current one and has
+     * outstayed the longest hand-off is taken off the glass.
+     */
+    private sweepBlocks;
+    private frame;
+    private tick;
+    /**
+     * TYPE THROWS ITS SHADOW WHERE THE BUILDING THROWS ITS OWN.
+     *
+     * The scene lights itself from a key whose position is a property of the
+     * hour, and the tower's cast shadow lies along the ground at whatever
+     * diagonal that produces. Type set over the frame with a shadow offset
+     * down and right — the default of every drop shadow ever shipped — is
+     * lit by a different sun than everything behind it, and the eye reads
+     * the mismatch long before it can name it. So the key's own screen
+     * position comes back from the scene and the offset is simply the
+     * direction away from it. At night, or with the sun behind the lens,
+     * there is no honest cast shadow and the type wears none.
+     */
+    private follow;
+    /** which of the frame's layers this picture draws itself */
+    private takeGlass;
+    /**
+     * THE WASH, TOLD ON A CHANGE. Two things decide it — the shot's own mode
+     * and the palette's paper — and neither changes often, so the picture is
+     * told when one does and eases the change itself over the same 700 ms
+     * the stylesheet used to.
+     */
+    private pushWash;
+    /** the cloud: into the glass where the picture takes it, onto a CSS plate where it does not */
+    private setCloud;
+    /**
+     * THE FURNITURE WEARS THE SCENE'S PALETTE.
+     *
+     * The page carries four times of day and swings its whole palette between
+     * them, so a scrim and a caption painted in one fixed ochre are correct in
+     * exactly one chapter and wrong in the other four — at noon the film's
+     * warm paper sits on a cool scene like a sticker. The scene already
+     * publishes its ink as CSS variables, so the film simply reads them and
+     * dresses itself the same, once per change rather than once per frame.
+     */
+    private wear;
+    /**
+     * PLANES, MOVING AT THEIR OWN RATES.
+     *
+     * The world layer parallaxes because it is genuinely out in the scene at
+     * different distances. The front layer has no depth to borrow, so it is
+     * given one: over the life of a beat each row drifts and scales on its
+     * own rate, the big glyph fastest and nearest, the small print slowest
+     * and furthest, so the type reads as a set of planes rather than a
+     * sheet. It is the oldest trick in motion graphics and it is here for
+     * the oldest reason — a still caption over a moving picture looks
+     * pasted on, and a caption that moves WITH the picture looks composited
+     * into it.
+     *
+     * It runs on the beat's own clock rather than Motion's, deliberately:
+     * the entrances belong to the score and this belongs to the shot, and
+     * putting the two on one timeline would mean the drift restarting every
+     * time a word did.
+     */
+    private parallax;
+    /**
+     * THE TRACES LIVE IN THE SCENE NOW. They began as SVG projected over
+     * the frame — approximately right and one frame behind the lens on
+     * every move. As tubes in the page's own scene they are exact: they
+     * lie ON the eave because they are geometry at the eave's own
+     * coordinates, the building occludes them honestly, and the draw-on
+     * is the tube's index buffer revealed in path order. Each line in a
+     * set starts a moment after the one before it — a hand annotating,
+     * not a diagram switching on.
+     */
+    /** how much of the follow is in force (eased), and its last aim and zoom */
+    private riseK;
+    private riseAim;
+    private riseZoom;
+    /**
+     * THE LENS FOLLOWS THE WORK. Chris's rule for a building that goes up
+     * in the shot: if a spire is rising, ZOOM OUT; as you push in, follow
+     * the top that is being built. So while the followed campaign is
+     * between its base and its top, the aim rides a little above the
+     * middle of what stands and the zoom is capped to keep base and top
+     * in the frame; when it finishes, the authored pose takes over again,
+     * on a one-pole so the release is a move and not a jump.
+     */
+    private followRise;
+    /** the beat whose lines are being timed, and the local time they became drawable */
+    private traceBeat;
+    private traceFrom;
+    /** whether the beat's lines may be on the glass right now */
+    private traceOk;
+    /**
+     * NO LINE ON A THING STILL GOING UP. A trace or a callout is drawn on a
+     * finished part: the followed campaign must be done (or, with nothing
+     * followed, the built height must have passed the line). The draw-on
+     * is timed from the moment that became true, not from the head.
+     */
+    private traceReady;
+    private traceShape;
+    /** the mark's facing, damped behind the camera's own bearing */
+    private markFace;
+    /**
+     * Place the stage mark: climb to its height with a settle, hold, and
+     * face the camera a beat late.
+     */
+    private stageMark;
+    /**
+     * THE TRACKING LINE — the one piece of the front layer that has to know
+     * where the camera is pointing this frame. The caption stays where the
+     * layout put it and a line reaches from it to the actual point on the
+     * building, redrawn every frame, so the label is attached to the thing
+     * rather than merely near it.
+     */
+    private trackPoint;
+    /**
+     * THE READOUT AND THE MARKER. The numeral is tracked and written only
+     * when the whole year changes, which is a handful of times a run; the
+     * marker's position is a custom property written every frame, because a
+     * dot that steps once a year along a rule is a dot that looks broken.
+     */
+    /**
+     * WHEN THE NUMERAL IS ON. It rises as the voice reaches the year, holds
+     * while the phrase finishes, and is gone well before the cut — a date
+     * that outstays the sentence that said it becomes a watermark.
+     */
+    private stampAt;
+    /** the film's clock readout, from page seconds — nothing without a clock */
+    private showYear;
+    /** everything a beat changes in the world, done once on entry */
+    private applyBeat;
+    /**
+     * THE AIR OF A SHOT: grade, sun, haze, weather. Split out of the beat
+     * so a chapter's sky can begin turning while the lens is still flying
+     * into it — the `air` cue fires at the head of a lead, the beat's own
+     * cue when it lands, and applying it twice is harmless because every
+     * one of these is a set, not a step.
+     */
+    private applyAir;
+    /**
+     * THE HOUR A CUT INHERITS.
+     *
+     * Theme and weather are stated where they CHANGE, so a beat halfway
+     * through the film usually says nothing about either — which is right
+     * for a film played from the top and wrong for one dropped into. A
+     * deep link (or a chapter skip) would open in whatever sky was last
+     * set, which since the front door became an evening meant the
+     * construction chapter got built at dusk. So a cut resolves its own
+     * hour first: walk back to the last beat that named one, and take it.
+     */
+    private settleAir;
+    private shot;
+    private dispatch;
+    /**
+     * PAUSE MEANS EVERYTHING STOPS. The score's run holds where it is (the
+     * lens included), the page's own clock holds (grass, weather, the
+     * build, the day), the audio graph suspends, and the beat clock is
+     * shifted forward by the length of the hold on resume so the hours,
+     * the build and the type pick up exactly where they stood. Tearing the
+     * Sequence down was the old pause, and it re-ran the chapter on play.
+     * An exact film's runs are already standing — its clock is the only
+     * thing that has to hold.
+     */
+    private toggle;
+    /** any re-cut or restart clears a hold: the new run starts rolling */
+    private unhold;
+    /**
+     * SKIP A CHAPTER — by re-cutting, never by seeking.
+     *
+     * `from` moves to a chapter head, which changes the beat list, which
+     * changes the path, the cues and the sequence's name all at once. The
+     * region sees a different score and plays it from its head. Seeking the
+     * existing run would be the obvious alternative and it would be wrong:
+     * the lens is an integrator whose pose depends on where it has been, so
+     * a run dropped into the middle of itself arrives with the wrong
+     * velocity — the same reason `notes/sylva-one-world.md` calls the chaser
+     * seek-unsafe and means it.
+     */
+    private goChapter;
+    private cutTo;
+    /** an uncaught error anywhere becomes a visible line — a film that
+     *  dies silently mid-reel cannot be debugged from a chair */
+    private trip;
+    private prev;
+    private next;
+    private key;
+    /**
+     * THE NARRATION, one file per beat.
+     *
+     * `assets/vo/<id>.mp3`, played on the beat's entrance and stopped
+     * when the beat changes. Per beat rather than one long track because
+     * chapter skip RE-CUTS the film: a single track would have to be sought,
+     * and a sought track against a re-cut score drifts inside a chapter.
+     *
+     * A missing file is silence, not an error. The film ships before the
+     * voice does, and the score has to be right either way. While a line
+     * plays the scene's own music ducks under it, which is the one piece of
+     * mixing that cannot wait for a mix.
+     */
+    private voSrc;
+    /** ask the page to fetch and decode the line after this one, now */
+    private primeNext;
+    /**
+     * A BOUNDARY NEVER CLIPS THE VOICE — and every line has its own
+     * throat. One shared element made politeness impossible: however
+     * gently the old line was being faded, the new line's src swap
+     * guillotined it mid-word. So an interrupted line keeps its OWN
+     * element and fades there (~120ms, fast enough to read as a stop,
+     * slow enough that no waveform is cut mid-cycle) while the new line
+     * starts clean on a fresh one — the game-dialogue barge-in, which is
+     * what a chapter skip actually is. ("Stop at the next word" is the
+     * refinement this is built to take: an analyser watching for the
+     * inter-word trough before the fade — see docs/choreo-splices.md.)
+     */
+    /**
+     * A JOIN, EXHIBITED. Any seam as a pure overlay on whatever is playing —
+     * no beat change, no snap: the transition itself, on the living
+     * picture. What a cutting room's wall plate triggers.
+     */
+    private preview;
+    /** the wrapper the live picture sits in, for rack-defocus */
+    private liveEl?;
+    private liveWrap;
+    /**
+     * THE LIGHT SWEEP: the sun itself flares across the seam — swings
+     * high and past, then settles back onto whatever light the beat
+     * actually asked for. Fire-and-forget; the restore hands the key
+     * back to the beat's own sun (or the hour's).
+     */
+    private lightSweep;
+    /** the scene brought its own score — six of them, one per tower */
+    /** the line for this beat, at the level the session was mixed to */
+    private speak;
+    private hush;
+    private hear;
+    /**
+     * FROM THE TOP means the front door, not the first beat.
+     *
+     * A film restarted straight into its opening shot skips the one piece
+     * of the picture that says what it is — and the poster is a
+     * composition in its own right, with the building turning in the last
+     * of the light. So this clears everything the run has done and puts
+     * the door back up, with the lens seated where it opens.
+     */
+    private restart;
+    /** a choice made at the door before the scene finished loading */
+    private wanted?;
+    /** through the gate — on the click the audio policy was waiting for */
+    private begin;
+    /** the whole film's running time, said the way a poster says it */
+    get runtime(): string;
+    /**
+     * BACK IN FROM THE END CARD — a dissolve, not a flight.
+     *
+     * The film ends three hundred degrees around the building from where
+     * it opened, so tweening the lens home spins it like a globe. The
+     * ending cross-fades into the opening frame instead: the last frame
+     * is held as a still, the camera is PLACED at the opening pose behind
+     * it, and the still fades away.
+     */
+    /**
+     * BACK IN FROM THE END CARD — a hard reset, not a journey.
+     *
+     * The film ends three hundred degrees around the building, with the
+     * tower dissolved, the sky at golden hour, the rain gone and a chapter
+     * numeral on screen. Tweening any of that back to the opening is a
+     * confusing ten seconds in which nothing is either the ending or the
+     * beginning. So the ending is CLEARED: every overlay, the model, the
+     * weather, the world type, the traces and the lens all go back to
+     * their opening state in one frame, and the film starts.
+     */
+    /** the end card's WATCH AGAIN is the front door, not the first beat: the
+     *  choice of sound is made there, every time */
+    private replay;
+    /** the chapter menu. The film keeps running behind it, blurred: a
+     * menu that freezes the picture makes the picture feel like a file, and
+     * this one is meant to feel like a broadcast you are stepping around in */
+    private menu;
+    private toc;
+    /** every chapter, with the beat it starts at and whether we are in it */
+    get contents(): {
+        here: boolean;
+        head: number;
+        n: string;
+        secs: number;
+        shots: number;
+        title: string;
+    }[];
+    private pick;
+}
+//# sourceMappingURL=film.d.ts.map