@pascal-app/viewer 1.0.3 → 1.0.5

package/dist/lib/reveal-pose.d.ts

@@ -0,0 +1,70 @@
+import { Box3, type Object3D, Vector3 } from 'three';
+import type { PlayedStyle } from './reveal-wipe';
+export declare function setRevealPose(object: Object3D, pivot: Vector3, scale: Vector3, lift?: number): void;
+/**
+ * A piece the agent moved shows where it was and travels to where it now is: `left` is the share of
+ * the way still to go (1 at the start, 0 at rest), `hop` a lift in metres along the parent's up.
+ * `from` and `yaw` are its old position and turn in its parent's frame; the root's own transform is
+ * the new one, whenever the renderer writes it.
+ */
+export declare function setGlidePose(object: Object3D, from: Vector3, yaw: number, left: number, hop?: number): void;
+export declare function clearRevealPose(object: Object3D): void;
+export declare function hasRevealPose(object: Object3D): boolean;
+/** The share of a drop spent in the air; the rest is the landing. */
+export declare const DROP_FALL = 0.68;
+export type RevealPoseSample = {
+    lift: number;
+    scale: Vector3;
+};
+export type RevealPoseOptions = {
+    /**
+     * A drop's anticipation: it lifts this share of its height before it falls (0.05 on a 4 m
+     * drop is 20 cm), so the eye is told where it is about to fall from. None by default.
+     */
+    lead?: number;
+    /** A heavier drop lands with a bigger squash and hop; 1 by default. The last piece of a build is heavier. */
+    weight?: number;
+    /**
+     * A rise, a scale or a settle goes past its rest and comes back (GSAP's `back.out` strength,
+     * 1.7 is GSAP's default); 0, the default, is a plain ease out.
+     */
+    overshoot?: number;
+};
+/**
+ * Where a `style` reveal holds its node at `t` in [0, 1]: a lift in metres
+ * along the parent's up and a scale about the style's pivot. At `t >= 1` it
+ * is exactly the rest pose (no lift, unit scale), so nothing settles off by a
+ * rounding error.
+ */
+export declare function revealPoseAt(style: PlayedStyle, t: number, height: number, out?: RevealPoseSample, options?: RevealPoseOptions): RevealPoseSample;
+export type RetractPoseSample = RevealPoseSample & {
+    /** 1 while it is drawn whole; a piece that lifts away fades, and is 0 once gone. */
+    opacity: number;
+};
+export declare const RETRACT_LIFT_MIN = 0.3;
+export declare const RETRACT_LIFT_MAX = 1.5;
+/**
+ * Where a `style` reveal holds its node as it is taken back, `p` in [0, 1] from whole to gone: the
+ * build played in reverse for an undo. Whatever grew shrinks the way it grew (a wall sinks into
+ * the ground, an opening closes through its wall), slowly at first and faster as it goes, which is
+ * what a rewind looks like; whatever fell in lifts away and fades, quick off the mark, as a thing
+ * thrown up does. At `p >= 1` it is gone: its scale at the least and its opacity 0.
+ */
+export declare function retractPoseAt(style: PlayedStyle, p: number, height: number, out?: RetractPoseSample): RetractPoseSample;
+/**
+ * How far into its duration each style has arrived, the frame its contact or its last movement
+ * lands on: a drop's impact, a rise's last centimetre. An assembled node holds still: its parts land.
+ */
+export declare const REVEAL_ARRIVAL: Record<PlayedStyle, number>;
+/** Whether `style` has landed at `t`: a drop's impact, after which it only settles. */
+export declare function revealHasLanded(style: PlayedStyle, t: number): boolean;
+/** The root's drawn bounds in its own frame, ignoring the reveal pose and hidden parts. */
+export declare function revealLocalBounds(root: Object3D, out?: Box3): Box3;
+/**
+ * Where a reveal scales about, in the root's frame: under the origin at the
+ * base of its drawn bounds for `rise` (a wall's frame already starts at its
+ * base), the centre of the bounds for `cut`, and the base of their centre for
+ * the rest.
+ */
+export declare function revealPivot(box: Box3, style: PlayedStyle): Vector3;
+//# sourceMappingURL=reveal-pose.d.ts.map

package/dist/lib/reveal-pose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-pose.d.ts","sourceRoot":"","sources":["../../src/lib/reveal-pose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAsB,KAAK,QAAQ,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAwDhD,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,SAAI,GAAG,IAAI,CAU9F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,SAAI,GACN,IAAI,CAKN;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAOtD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAEvD;AAGD,qEAAqE;AACrE,eAAO,MAAM,SAAS,OAAO,CAAA;AAU7B,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAE/D,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6GAA6G;IAC7G,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,gBAAoD,EACzD,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAgDlB;AAED,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG;IACjD,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAID,eAAO,MAAM,gBAAgB,MAAM,CAAA;AACnC,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAOnC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,iBAAiE,GACrE,iBAAiB,CAmCnB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAQtD,CAAA;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAGtE;AAKD,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,GAAE,IAAiB,GAAG,IAAI,CAgB9E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAMlE"}

package/dist/lib/reveal-pose.js

@@ -0,0 +1,248 @@
+import { Box3, Matrix4, Vector3 } from 'three';
+import { clearRevealWipe } from './reveal-wipe';
+const poses = new WeakMap();
+const step = new Matrix4();
+const glideStep = new Matrix4();
+const glideAround = new Matrix4();
+function updateRevealedMatrix() {
+    ;
+    Object.getPrototypeOf(this).updateMatrix.call(this);
+    const pose = poses.get(this);
+    if (!pose)
+        return;
+    const { pivot, scale, lift, glide } = pose;
+    this.matrix.multiply(step.makeTranslation(pivot.x, pivot.y, pivot.z));
+    this.matrix.multiply(step.makeScale(scale.x, scale.y, scale.z));
+    this.matrix.multiply(step.makeTranslation(-pivot.x, -pivot.y, -pivot.z));
+    if (glide && glide.left > 0) {
+        // Read from the root as it is now, so a renderer that has not yet put it at its new place
+        // leaves it where it was: turned about its own origin by the share left of the way round, then carried.
+        const { position, rotation } = this;
+        let turn = glide.yaw - rotation.y;
+        turn -= Math.round(turn / (2 * Math.PI)) * 2 * Math.PI;
+        glideStep.makeTranslation((glide.from.x - position.x) * glide.left, (glide.from.y - position.y) * glide.left, (glide.from.z - position.z) * glide.left);
+        glideStep.multiply(glideAround.makeTranslation(position.x, position.y, position.z));
+        glideStep.multiply(glideAround.makeRotationY(turn * glide.left));
+        glideStep.multiply(glideAround.makeTranslation(-position.x, -position.y, -position.z));
+        this.matrix.premultiply(glideStep);
+    }
+    // Premultiplied: a fall is in metres along the parent's up, whatever the root's own scale.
+    this.matrix.elements[13] += lift;
+}
+export function setRevealPose(object, pivot, scale, lift = 0) {
+    let pose = poses.get(object);
+    if (!pose) {
+        pose = { pivot: new Vector3(), scale: new Vector3(), lift: 0, glide: null };
+        poses.set(object, pose);
+        object.updateMatrix = updateRevealedMatrix;
+    }
+    pose.pivot.copy(pivot);
+    pose.scale.copy(scale);
+    pose.lift = lift;
+}
+/**
+ * A piece the agent moved shows where it was and travels to where it now is: `left` is the share of
+ * the way still to go (1 at the start, 0 at rest), `hop` a lift in metres along the parent's up.
+ * `from` and `yaw` are its old position and turn in its parent's frame; the root's own transform is
+ * the new one, whenever the renderer writes it.
+ */
+export function setGlidePose(object, from, yaw, left, hop = 0) {
+    if (!poses.has(object))
+        setRevealPose(object, new Vector3(), new Vector3(1, 1, 1));
+    const pose = poses.get(object);
+    pose.glide = { from: (pose.glide?.from ?? new Vector3()).copy(from), yaw, left };
+    pose.lift = hop;
+}
+export function clearRevealPose(object) {
+    // A covering laid in place ends with the pose that held its node.
+    clearRevealWipe(object);
+    if (!poses.delete(object))
+        return;
+    delete object.updateMatrix;
+    if (object.matrixAutoUpdate)
+        object.updateMatrix();
+    object.matrixWorldNeedsUpdate = true;
+}
+export function hasRevealPose(object) {
+    return poses.has(object);
+}
+const MIN_SCALE = 1e-3;
+/** The share of a drop spent in the air; the rest is the landing. */
+export const DROP_FALL = 0.68;
+/** The share of a drop a lead takes: a hair of lift before the fall. */
+const DROP_LEAD = 0.14;
+/** A landing hops back up this share of the fall, at most `DROP_HOP_MAX` metres. */
+const DROP_HOP = 0.012;
+const DROP_HOP_MAX = 0.05;
+const DROP_SQUASH = 0.08;
+const easeOutCubic = (t) => 1 - (1 - t) ** 3;
+/** GSAP's `back.out(s)`: past 1 by a little near the end, exactly 1 at the end. */
+const easeOutBack = (t, s) => 1 + (s + 1) * (t - 1) ** 3 + s * (t - 1) ** 2;
+/**
+ * Where a `style` reveal holds its node at `t` in [0, 1]: a lift in metres
+ * along the parent's up and a scale about the style's pivot. At `t >= 1` it
+ * is exactly the rest pose (no lift, unit scale), so nothing settles off by a
+ * rounding error.
+ */
+export function revealPoseAt(style, t, height, out = { lift: 0, scale: new Vector3() }, options = {}) {
+    out.lift = 0;
+    out.scale.set(1, 1, 1);
+    if (t >= 1 || style === 'assemble' || style === 'cover')
+        return out;
+    const at = Math.max(0, t);
+    const overshoot = Math.max(0, options.overshoot ?? 0);
+    const eased = overshoot > 0 ? easeOutBack(at, overshoot) : easeOutCubic(at);
+    switch (style) {
+        case 'rise':
+            out.scale.y = Math.max(MIN_SCALE, eased);
+            break;
+        case 'scale': {
+            const f = Math.max(MIN_SCALE, eased);
+            out.scale.set(f, f, f);
+            break;
+        }
+        case 'settle':
+            out.lift = height * (1 - eased);
+            break;
+        case 'drop': {
+            const lead = Math.max(0, options.lead ?? 0);
+            const weight = Math.max(0.5, options.weight ?? 1);
+            const fallStart = lead > 0 ? DROP_LEAD : 0;
+            if (at < fallStart) {
+                // A hair of lift, up and back to where it hangs: the fall is about to start.
+                out.lift = height * (1 + lead * Math.sin((Math.PI * at) / fallStart));
+                break;
+            }
+            if (at < DROP_FALL) {
+                // Gravity: slow off the hook, fastest at the impact.
+                const fell = (at - fallStart) / (DROP_FALL - fallStart);
+                out.lift = height * (1 - fell * fell);
+                break;
+            }
+            const u = (at - DROP_FALL) / (1 - DROP_FALL);
+            out.lift = Math.min(DROP_HOP_MAX, height * DROP_HOP) * weight * 4 * u * (1 - u);
+            // The squash at impact, a rebound past rest (follow-through), then still: it is zero, and flat,
+            // exactly at the end.
+            const squash = DROP_SQUASH * weight * (1 - u) ** 1.5 * Math.cos(1.5 * Math.PI * u);
+            out.scale.set(1 + squash / 2, 1 - squash, 1 + squash / 2);
+            break;
+        }
+        case 'cut':
+            // Through the wall only, along its normal (the opening's z): carved out, not popped in.
+            out.scale.z = Math.max(MIN_SCALE, easeOutCubic(at));
+            break;
+    }
+    return out;
+}
+/** A piece that fell in lifts away this share of the height it fell from, at least and at most this many metres. */
+const RETRACT_LIFT_SHARE = 0.5;
+export const RETRACT_LIFT_MIN = 0.3;
+export const RETRACT_LIFT_MAX = 1.5;
+const smoothstep = (low, high, value) => {
+    const x = Math.min(1, Math.max(0, (value - low) / (high - low)));
+    return x * x * (3 - 2 * x);
+};
+/**
+ * Where a `style` reveal holds its node as it is taken back, `p` in [0, 1] from whole to gone: the
+ * build played in reverse for an undo. Whatever grew shrinks the way it grew (a wall sinks into
+ * the ground, an opening closes through its wall), slowly at first and faster as it goes, which is
+ * what a rewind looks like; whatever fell in lifts away and fades, quick off the mark, as a thing
+ * thrown up does. At `p >= 1` it is gone: its scale at the least and its opacity 0.
+ */
+export function retractPoseAt(style, p, height, out = { lift: 0, scale: new Vector3(), opacity: 1 }) {
+    out.lift = 0;
+    out.scale.set(1, 1, 1);
+    out.opacity = 1;
+    const at = Math.min(1, Math.max(0, p));
+    const shrunk = Math.max(MIN_SCALE, 1 - at * at);
+    switch (style) {
+        case 'rise':
+            out.scale.y = shrunk;
+            break;
+        case 'scale':
+            out.scale.set(shrunk, shrunk, shrunk);
+            break;
+        case 'cut':
+            out.scale.z = shrunk;
+            break;
+        case 'cover':
+            // Its covering lifts off row by row (`setRevealWipe`); the bare node goes with the last.
+            if (at >= 1)
+                out.scale.set(MIN_SCALE, MIN_SCALE, MIN_SCALE);
+            break;
+        case 'settle':
+        case 'drop':
+        case 'assemble':
+            out.lift =
+                Math.min(RETRACT_LIFT_MAX, Math.max(RETRACT_LIFT_MIN, height * RETRACT_LIFT_SHARE)) *
+                    easeOutCubic(at);
+            out.opacity = 1 - smoothstep(0.1, 0.8, at);
+            break;
+    }
+    if (at >= 1) {
+        // Gone: what shrank is at its smallest already; what lifted away shrinks away with its last fade.
+        if (out.lift > 0)
+            out.scale.set(MIN_SCALE, MIN_SCALE, MIN_SCALE);
+        out.opacity = 0;
+    }
+    return out;
+}
+/**
+ * How far into its duration each style has arrived, the frame its contact or its last movement
+ * lands on: a drop's impact, a rise's last centimetre. An assembled node holds still: its parts land.
+ */
+export const REVEAL_ARRIVAL = {
+    rise: 1,
+    scale: 1,
+    settle: 1,
+    drop: DROP_FALL,
+    cut: 1,
+    assemble: 0,
+    cover: 1,
+};
+/** Whether `style` has landed at `t`: a drop's impact, after which it only settles. */
+export function revealHasLanded(style, t) {
+    if (style === 'cover')
+        return t >= 1;
+    return style !== 'drop' || t >= DROP_FALL;
+}
+const bounds = new Box3();
+const part = new Box3();
+/** The root's drawn bounds in its own frame, ignoring the reveal pose and hidden parts. */
+export function revealLocalBounds(root, out = new Box3()) {
+    bounds.makeEmpty();
+    const visit = (object, matrix) => {
+        if (object.visible === false)
+            return;
+        const geometry = object.isMesh ? object.geometry : undefined;
+        if (geometry?.getAttribute('position')) {
+            if (!geometry.boundingBox)
+                geometry.computeBoundingBox();
+            if (geometry.boundingBox)
+                bounds.union(part.copy(geometry.boundingBox).applyMatrix4(matrix));
+        }
+        for (const child of object.children) {
+            if (child.matrixAutoUpdate)
+                child.updateMatrix();
+            visit(child, new Matrix4().multiplyMatrices(matrix, child.matrix));
+        }
+    };
+    visit(root, new Matrix4());
+    return out.copy(bounds);
+}
+/**
+ * Where a reveal scales about, in the root's frame: under the origin at the
+ * base of its drawn bounds for `rise` (a wall's frame already starts at its
+ * base), the centre of the bounds for `cut`, and the base of their centre for
+ * the rest.
+ */
+export function revealPivot(box, style) {
+    if (box.isEmpty())
+        return new Vector3();
+    const centre = box.getCenter(new Vector3());
+    if (style === 'rise')
+        return new Vector3(0, box.min.y, 0);
+    if (style === 'cut')
+        return centre;
+    return new Vector3(centre.x, box.min.y, centre.z);
+}

package/dist/lib/reveal-schedule.d.ts

@@ -0,0 +1,208 @@
+import type { RevealPhase, RevealStyle } from '@pascal-app/core';
+import type { CoverRange, PlayedStyle } from './reveal-wipe';
+export declare const REVEAL_PHASE_ORDER: readonly RevealPhase[];
+export type RevealTiming = {
+    /** Between two nodes of one phase on one level. */
+    nodeGapMs: number;
+    /** Between one (phase, level) group and the next. */
+    groupGapMs: number;
+    /** A reveal ends within this however many nodes it has: the gaps shrink, no node is skipped. */
+    capMs: number;
+    /**
+     * How long each style moves its node. `assemble` holds its node still (its parts drop), `cover`
+     * holds it still while its covering is laid, and the heights of the travelling styles are
+     * declared by each kind (`capabilities.reveal.height`).
+     */
+    durationMs: Record<RevealStyle, number>;
+};
+/** The one place to tune the reveal's pace; the heights live in the kinds' declarations. */
+export declare const REVEAL_TIMING: RevealTiming;
+/**
+ * How long `style` moves its node in `table`. Only the Framing level's table has a `cover` time (it
+ * lays a roof's covering where Full drops the roof whole); a plan made on a Full table or the reverse
+ * play of a framing build gives a covering twice what the whole roof takes to come or go.
+ */
+export declare function styleMs(table: Readonly<Record<RevealStyle, number>> & {
+    cover?: number;
+}, style: PlayedStyle): number;
+export type RevealCandidate = {
+    id: string;
+    phase: RevealPhase;
+    style: PlayedStyle;
+    /** Metres above the rest pose for the travelling styles, 0 for the others. */
+    height: number;
+    levelId: string | null;
+    /** The level's storey; nodes outside any level come first. */
+    levelIndex: number;
+    /** Ancestor count, so a host starts before what it hosts. */
+    depth: number;
+    /** Arrival order, the last tie-break: a room's walls arrive along its outline. */
+    seq: number;
+    /** Who wrote it, as the host named it on the commit (`'agent'`); events pass it on. */
+    source?: string | null;
+    /** A drop's anticipation, as a share of its height (see `RevealPoseOptions.lead`). */
+    lead?: number;
+    /**
+     * The room (or wall run) it is built with, for the lazy schedule: rooms of a floor build side
+     * by side, a beat apart. Absent: it belongs to its floor as a whole (a slab under every room).
+     */
+    cluster?: string;
+    /** Where its room comes in its floor's sweep: the lower first. */
+    sweep?: number;
+    /** Its place in its room: a wall's turn around the room's outline. */
+    order?: number;
+    /**
+     * How long a plugin's own presentation plays at its turn before the node itself moves in (a wall's
+     * frame and boards, Bones): the lazy schedule leaves the time, and the node starts after it.
+     */
+    prerollMs?: number;
+};
+export type PlannedReveal = RevealCandidate & {
+    group: string;
+    startMs: number;
+    /** The last piece of the plan to arrive: it lands with a slightly bigger beat. */
+    finale?: boolean;
+};
+export declare function revealGroupKey(candidate: Pick<RevealCandidate, 'phase' | 'levelId'>): string;
+/**
+ * Start times for `candidates`, from `startMs`. Phase after phase; within a phase every floor
+ * plays at once, its nodes in a scattered order (GSAP's stagger from "random") and evenly spaced,
+ * floors interleaved within one gap, so no frame starts a crowd. On a floor, what stands on
+ * something (a book on a shelf) starts after it.
+ */
+export declare function planReveal(candidates: readonly RevealCandidate[], startMs: number, timing?: RevealTiming): PlannedReveal[];
+/**
+ * The lazy, nested schedule (the `framing` level): floors a beat apart, the rooms of a floor a beat
+ * apart, the pieces of a room a beat apart, each with a little jitter, so many small builds progress
+ * side by side instead of one global pulse. A big build takes proportionally longer, up to `capMs`.
+ */
+export type LazyRevealTiming = {
+    /** Between one floor's build and the next one's: floors go up side by side, offset. */
+    floorOffsetMs: number;
+    /** Between one room (or wall run) of a floor and the next, in each phase. */
+    roomOffsetMs: number;
+    /** Between two pieces of one room, by phase: a room's walls go up one after the other. */
+    elementOffsetMs: Record<RevealPhase, number>;
+    /** After a floor's phase has started its last piece, before its next phase starts. */
+    phaseGapMs: number;
+    /** Each start moves by up to this share of its offset, either way (never mechanical). */
+    jitter: number;
+    /** A plan longer than this is pulled together to end by it: a huge build does not take forever. */
+    capMs: number;
+    /** How long each style moves its node at this level; `cover` is the longest a roof's covering takes to lay. */
+    durationMs: Record<PlayedStyle, number>;
+    /**
+     * A covering takes this long for each metre of what it covers, never under `coverMinMs` nor over
+     * `durationMs.cover` (`coverRangeAt`).
+     */
+    coverMsPerM: number;
+    coverMinMs: number;
+    /**
+     * How far a rise, a scale or a settle goes past its rest before it settles (GSAP's `back.out`
+     * strength; 0 is a plain ease out). A rise's is gentler: a wall 2 % past its top, not into the slab over it.
+     */
+    overshoot: Record<'rise' | 'scale' | 'settle', number>;
+    /** Drops and settles fall from at least this high (m), whatever their kind declares. */
+    minHeightM: Partial<Record<PlayedStyle, number>>;
+};
+/**
+ * The Framing level's pace: one factor on its whole timeline, the staging and the motions alike. 1 is
+ * the pace it was built at; 1.75 makes a build that took 20 s take 35 s, and anything smaller or
+ * larger takes proportionally longer. A pace of `p` multiplies every offset, gap, beat, duration and
+ * cap of this level (`LAZY_REVEAL_TIMING`) and of the frame each wall plays before it rises (Bones'
+ * `WALL_BUILD`), so pieces still snap and the build only plays out slower. The Full level reads
+ * `REVEAL_TIMING` and does not move with it.
+ */
+export declare const FRAMING_PACE = 1.75;
+/** The lazy schedule at pace 1; `LAZY_REVEAL_TIMING` is this at `FRAMING_PACE`. */
+export declare const LAZY_REVEAL_BASE_TIMING: LazyRevealTiming;
+/** `timing` played at `pace` times its length: times scale, shares and heights do not. */
+export declare function pacedLazyTiming(timing: LazyRevealTiming, pace: number): LazyRevealTiming;
+/** The one place the lazy schedule and the framing level's motion are read from. */
+export declare const LAZY_REVEAL_TIMING: LazyRevealTiming;
+/**
+ * The person's animation speed: how fast the build animations play, as a multiple of today's.
+ * Higher is faster, so every time of a schedule is divided by it: ×2 plays a build in half the
+ * time, ×0.5 in twice as long. ×1 is every table exactly as shipped (the very same objects).
+ */
+export declare const ANIMATION_SPEEDS: readonly [0.5, 0.75, 1, 1.5, 2];
+export type AnimationSpeed = (typeof ANIMATION_SPEEDS)[number];
+export declare const DEFAULT_ANIMATION_SPEED: AnimationSpeed;
+/** The step nearest to `value`; anything that is not a finite positive number is ×1. */
+export declare function normalizeAnimationSpeed(value: unknown): AnimationSpeed;
+/** `timing` with every time divided by `speed`: durations, gaps and the cap. */
+export declare function pacedRevealTiming(timing: RevealTiming, speed: number): RevealTiming;
+/** `timing` with every time divided by `speed`; the share `speed` of its pace is not a time. */
+export declare function pacedRetractTiming(timing: RetractTiming, speed: number): RetractTiming;
+/** The Full level's schedule at `speed`; at ×1 it is `REVEAL_TIMING` itself. */
+export declare const revealTimingAt: (speed: number) => RevealTiming;
+/** The Framing level's schedule at `speed`; at ×1 it is `LAZY_REVEAL_TIMING` itself. */
+export declare const lazyTimingAt: (speed: number) => LazyRevealTiming;
+/** The reverse play's schedule at `speed`; at ×1 it is `RETRACT_TIMING` itself. */
+export declare const retractTimingAt: (speed: number) => RetractTiming;
+/**
+ * Start times for `candidates` on the lazy, nested schedule, from `startMs`:
+ * - each floor builds its foundation, structure, stairs and openings, a phase after the other, and
+ *   the floors go up side by side, `floorOffsetMs` apart;
+ * - in a phase, the rooms (`cluster`) start `roomOffsetMs` apart in their sweep order, and the
+ *   pieces of a room `elementOffsetMs` apart around it; what belongs to the whole floor comes first;
+ * - roofs come once every floor is up, then the furniture, floor by floor and room by room again;
+ * - a piece with a preroll starts after it (its plugin plays then), and its room's next phase waits.
+ * Every start is jittered. The plan grows with the build (its biggest room, its rooms, its floors),
+ * and is pulled together only past `capMs`. `startMs` of a planned entry is when the node itself
+ * moves; its preroll plays before.
+ */
+export declare function planLazyReveal(candidates: readonly RevealCandidate[], startMs: number, timing?: LazyRevealTiming): PlannedReveal[];
+export type RetractTiming = {
+    /** A reverse plan keeps the build's order, reversed, at this share of its pace. */
+    speed: number;
+    /** Between two pieces of one phase on one level, in a reverse plan with room to spare. */
+    nodeGapMs: number;
+    /** A reverse play ends within this however many pieces it takes back. */
+    capMs: number;
+    /** How long each style takes to go: a rewind is quicker than the build. */
+    durationMs: Record<RevealStyle, number> & {
+        cover?: number;
+    };
+};
+/** The one place to tune the reverse play's pace. */
+export declare const RETRACT_TIMING: RetractTiming;
+export type PlannedRetract = RevealCandidate & {
+    group: string;
+    startMs: number;
+    durationMs: number;
+};
+/**
+ * The reverse play at the Framing level: the rewind's durations at the Framing pace, so a deleted
+ * floor comes apart as slowly as it went up. `capMs` keeps a whole floor's deconstruction in a
+ * bounded time however many pieces it takes back.
+ */
+/** A covering lifts off in this share of the time it took to lay. */
+export declare const COVER_REVERSE_SHARE = 0.6;
+export declare const LAZY_RETRACT_TIMING: RetractTiming;
+/**
+ * How long a roof's covering takes by the size it covers at the Framing level at `speed`: its range
+ * in metres of sweep (`coverDurationMs`); `reverse` for the lifting off of a deletion or an undo.
+ */
+export declare function coverRangeAt(speed: number, reverse?: boolean): CoverRange;
+/** The Framing level's reverse play at `speed`; at ×1 it is `LAZY_RETRACT_TIMING` itself. */
+export declare const lazyRetractTimingAt: (speed: number) => RetractTiming;
+/**
+ * The Framing build played backwards, for a deletion or an undo: the plan of the build (floor by
+ * floor, room by room, piece by piece, `planLazyReveal`) read from its end, so the furniture lifts
+ * out first, then the roof, the openings, the walls and the slabs last, and the floors come apart
+ * from the top down, each room as it went up. Each piece takes its own style's rewind time; a piece
+ * that had a preroll keeps it, after its own going, for the plugin that took it apart (a wall's
+ * boards come off and its studs fly up then). The whole ends within the cap by pulling the starts
+ * closer, never by skipping a piece.
+ */
+export declare function planLazyRetract(candidates: readonly RevealCandidate[], startMs: number, timing?: RetractTiming, build?: LazyRevealTiming): PlannedRetract[];
+/**
+ * The build played backwards, for an undo: the last phase goes first and each goes after the one
+ * built on it (the furniture, the roof, the openings, the walls, the slab), and inside a phase the last
+ * piece to arrive is the first to go, so the plan reads one phase at a time as the build did. It is
+ * quicker; each piece takes its own style's rewind duration; and the whole ends within the cap by
+ * pulling the starts closer, never by skipping a piece.
+ */
+export declare function planRetract(candidates: readonly RevealCandidate[], startMs: number, timing?: RetractTiming, build?: RevealTiming): PlannedRetract[];
+//# sourceMappingURL=reveal-schedule.d.ts.map

package/dist/lib/reveal-schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-schedule.d.ts","sourceRoot":"","sources":["../../src/lib/reveal-schedule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE5D,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAOpD,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;CACxC,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,aAAa,EAAE,YAK3B,CAAA;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACjE,KAAK,EAAE,WAAW,GACjB,MAAM,CAGR;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,WAAW,CAAA;IAClB,KAAK,EAAE,WAAW,CAAA;IAClB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAA;IAClB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAA;IACX,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,MAAM,CAE5F;AAYD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,YAA4B,GACnC,aAAa,EAAE,CAuDjB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAA;IACpB,0FAA0F;IAC1F,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;IAC5C,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAA;IAClB,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,KAAK,EAAE,MAAM,CAAA;IACb,+GAA+G;IAC/G,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;IACvC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO,GAAG,QAAQ,EAAE,MAAM,CAAC,CAAA;IACtD,wFAAwF;IACxF,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAA;CACjD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,OAAO,CAAA;AAEhC,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,EAAE,gBAmBrC,CAAA;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAgBxF;AAED,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,EAAE,gBAGhC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAI,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAU,CAAA;AAC/D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAC9D,eAAO,MAAM,uBAAuB,EAAE,cAAkB,CAAA;AAExD,wFAAwF;AACxF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAMtE;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAOnF;AAED,gGAAgG;AAChG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAOtF;AAQD,gFAAgF;AAChF,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,YACwB,CAAA;AAEvE,wFAAwF;AACxF,eAAO,MAAM,YAAY,UAAW,MAAM,KAAG,gBACsD,CAAA;AAEnG,mFAAmF;AACnF,eAAO,MAAM,eAAe,UAAW,MAAM,KAAG,aAC0B,CAAA;AAS1E;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,gBAAqC,GAC5C,aAAa,EAAE,CAyGjB;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7D,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;GAIG;AACH,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC,eAAO,MAAM,mBAAmB,EAAE,aAQjC,CAAA;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,UAAU,CAQvE;AAED,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,UAAW,MAAM,KAAG,aACgC,CAAA;AAEpF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,aAAmC,EAC3C,KAAK,GAAE,gBAAqC,GAC3C,cAAc,EAAE,CAsBlB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,aAA8B,EACtC,KAAK,GAAE,YAA4B,GAClC,cAAc,EAAE,CA8BlB"}