versioncam 0.1.3 → 0.2.0

package/dist/core/camera-track.js

@@ -0,0 +1,230 @@
+import { interpolateRect } from "./camera.js";
+import { minjerk } from "./easing.js";
+import { followCentres } from "./follow.js";
+import { frameAt, timeAt } from "./timeline.js";
+/**
+ * Turn a clip's camera writes into the keys the renderer interpolates.
+ *
+ * Every write starts from where the camera is, moving or not, and blends
+ * from there to where it is going:
+ *
+ *     camera(t) = interpolateRect(before(t), destination(t), minjerk(u))
+ *
+ * where `before` is the camera as it would have gone on without this write,
+ * and `u` runs from 0 to 1 over the write's duration. Min-jerk has no slope
+ * at either end, so the camera's velocity is continuous where a blend starts
+ * and where it ends: entering a follow from a keyed zoom, leaving it for a
+ * reset, or a zoom written while another is still under way. That last one
+ * used to wait for the move before it to finish and then run short, because
+ * each glide set off from the previous glide's target.
+ *
+ * A clip that never follows and never writes a move while another is under
+ * way gets exactly the keys it always got: a hold where each write starts and
+ * a min-jerk key where it ends. Every other clip gets the camera sampled at
+ * each frame (the `"linear"` keys), since a blend between two moving framings
+ * is no longer a glide between two keys.
+ */
+export function cameraTrack(writes, context) {
+    const { viewport } = context;
+    const full = { x: 0, y: 0, w: viewport.width, h: viewport.height };
+    const opening = { t: 0, rect: full, ease: "hold" };
+    const effective = effectiveWrites(writes);
+    if (glidesOnly(effective))
+        return glideKeys(effective, opening);
+    return sampledKeys(effective, context, full);
+}
+/**
+ * Whether every write is a framing that starts once the one before it has
+ * arrived: the only case the old keys describe exactly.
+ */
+function glidesOnly(writes) {
+    let arrived = 0;
+    for (const write of writes) {
+        if (write.kind !== "frame" || write.t < arrived)
+            return false;
+        // The same expression the key's time is computed with below, so the
+        // comparison is between the same two doubles the keys will hold.
+        arrived = write.t + write.durationMs / 1000;
+    }
+    return true;
+}
+/**
+ * The keys the session wrote before it could follow: hold the current
+ * framing until the write, then glide. Kept to the byte, so no recording of
+ * a clip that only zooms changes.
+ */
+function glideKeys(writes, opening) {
+    const keys = [opening];
+    for (const write of writes) {
+        const last = keys[keys.length - 1];
+        if (last.t < write.t) {
+            keys.push({ t: write.t, rect: last.rect, ease: "hold" });
+        }
+        keys.push({
+            t: write.t + write.durationMs / 1000,
+            rect: write.rect,
+            ease: "minjerk",
+        });
+    }
+    return keys;
+}
+/**
+ * The writes that take effect.
+ *
+ * A release with no follow to release is nothing to do. A write replaces an
+ * earlier one at the same instant that was still to take time: two moves
+ * written together are one intention stated twice, and blending the first
+ * under the second would bend the camera towards a framing no frame was
+ * meant to show. A cut (duration 0) at the same instant is kept, since it has
+ * already happened by the time the next write starts from it.
+ */
+function effectiveWrites(writes) {
+    const effective = [];
+    for (const write of writes) {
+        const last = effective[effective.length - 1];
+        if (write.kind === "release") {
+            if (last?.kind === "follow")
+                effective.push(write);
+            continue;
+        }
+        while (effective.length > 0) {
+            const previous = effective[effective.length - 1];
+            if (previous.kind === "release" ||
+                previous.t !== write.t ||
+                previous.durationMs <= 0) {
+                break;
+            }
+            effective.pop();
+        }
+        effective.push(write);
+    }
+    return effective;
+}
+/** The first frame whose time is at or after `t`. */
+function firstFrameFrom(t, fps) {
+    let frame = Math.max(0, Math.ceil(t * fps - 1e-9));
+    while (timeAt(frame, fps) < t)
+        frame += 1;
+    while (frame > 0 && timeAt(frame - 1, fps) >= t)
+        frame -= 1;
+    return frame;
+}
+/** To a thousandth of a pixel: far below anything a frame can show. */
+const round = (value) => Math.round(value * 1000) / 1000;
+/**
+ * A sample, rounded, so a camera at rest compares equal to itself from one
+ * frame to the next and its run of samples collapses to two.
+ *
+ * Rounding may not carry an edge that was inside the page outside it: a
+ * frame at the page's right edge is `x + w = width` exactly, and rounding
+ * each half up would put a thousandth of a pixel of nothing in the picture.
+ */
+function roundRect(rect, viewport) {
+    const w = round(rect.w);
+    const h = round(rect.h);
+    return {
+        x: roundInside(rect.x, rect.w, w, viewport.width),
+        y: roundInside(rect.y, rect.h, h, viewport.height),
+        w,
+        h,
+    };
+}
+/**
+ * One edge's position, rounded, and kept inside `[0, limit]` if it was
+ * inside to begin with, give or take the last bit of a double: a frame
+ * centred as far right as it goes is `x + w = width` only up to the float
+ * arithmetic that centred it. A rectangle a clip asked for outside the page
+ * (`camera.to` accepts one) is left where it was asked for.
+ */
+function roundInside(start, size, rounded, limit) {
+    const slack = 1e-6;
+    const at = round(start);
+    if (start < -slack || start + size > limit + slack)
+        return at;
+    if (at < 0)
+        return 0;
+    if (at + rounded > limit)
+        return Math.floor((limit - rounded) * 1000) / 1000;
+    return at;
+}
+function sameRect(a, b) {
+    return a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h;
+}
+function sampledKeys(effective, context, full) {
+    const { fps, viewport } = context;
+    const lastFrame = context.durationFrames - 1;
+    // Sampled through the last frame and then on, past it, until every write
+    // has arrived: a move still running when the clip ends leaves keys after
+    // the end, as a glide's key after the end always has, and that is what
+    // `review` warns about.
+    let endFrame = lastFrame;
+    for (const write of effective) {
+        if (write.kind === "release")
+            continue;
+        endFrame = Math.max(endFrame, frameAt(write.t + write.durationMs / 1000, fps));
+    }
+    const movers = [];
+    effective.forEach((write, index) => {
+        if (write.kind === "release")
+            return;
+        const duration = write.durationMs / 1000;
+        if (write.kind === "frame") {
+            const rect = write.rect;
+            movers.push({ t: write.t, duration, destination: () => rect });
+            return;
+        }
+        // A follow reads the cursor until the next write of any kind, release
+        // included.
+        const next = effective[index + 1];
+        const firstFrame = firstFrameFrom(write.t, fps);
+        const centres = followCentres({
+            cursor: context.cursor,
+            cursorStart: context.cursorStart,
+            viewport,
+            fps,
+            spec: write.spec,
+            firstFrame,
+            lastFrame: endFrame,
+            until: next ? next.t : Number.POSITIVE_INFINITY,
+        });
+        const w = viewport.width / write.spec.scale;
+        const h = viewport.height / write.spec.scale;
+        movers.push({
+            t: write.t,
+            duration,
+            destination: (frame) => {
+                const [cx, cy] = centres[frame - firstFrame];
+                return { x: cx - w / 2, y: cy - h / 2, w, h };
+            },
+        });
+    });
+    // The camera at a frame: the latest write that has started, blended with
+    // the camera as it was going before it, for as long as the blend lasts.
+    const cameraAt = (index, frame, t) => {
+        if (index < 0)
+            return full;
+        const mover = movers[index];
+        const destination = mover.destination(frame);
+        const u = mover.duration > 0 ? (t - mover.t) / mover.duration : 1;
+        if (u >= 1)
+            return destination;
+        return interpolateRect(cameraAt(index - 1, frame, t), destination, minjerk(u));
+    };
+    const keys = [];
+    let latest = -1;
+    for (let frame = 0; frame <= endFrame; frame += 1) {
+        const t = timeAt(frame, fps);
+        while (latest + 1 < movers.length && movers[latest + 1].t <= t) {
+            latest += 1;
+        }
+        const rect = roundRect(cameraAt(latest, frame, t), viewport);
+        keys.push({ t, rect, ease: frame === 0 ? "hold" : "linear" });
+    }
+    // Where the camera is still, only the two ends of the stillness matter:
+    // between two equal samples, every sample is the same.
+    return keys.filter((key, i) => i === 0 ||
+        i === keys.length - 1 ||
+        !sameRect(keys[i - 1].rect, key.rect) ||
+        !sameRect(key.rect, keys[i + 1].rect));
+}
+//# sourceMappingURL=camera-track.js.map

package/dist/core/camera-track.js.map

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

package/dist/core/camera.d.ts

@@ -22,9 +22,22 @@ export declare function clampRect(rect: Rect, viewport: Viewport): Rect;
 export declare function zoomRect(target: Rect, viewport: Viewport, options?: ZoomOptions): Rect;
 /** The magnification a camera rectangle represents. */
 export declare function scaleOf(rect: Rect, viewport: Viewport): number;
+/**
+ * Interpolate one camera framing towards another.
+ *
+ * The size moves geometrically and the centre linearly. Interpolating width
+ * linearly is the usual reason a zoom feels wrong: going from 1440 wide to 780
+ * wide, the first half of the move changes the magnification by 1.22x and the
+ * second half by 1.51x, so a zoom that is mathematically even reads as rushing
+ * into the target and then crawling. In log space each equal step multiplies
+ * the scale by the same factor, which is what the eye actually reads as
+ * constant speed.
+ */
+export declare function interpolateRect(a: Rect, b: Rect, u: number): Rect;
 /**
  * Where the camera is at time `t`. A key's `ease` describes how the camera
  * reaches it from the previous key: `minjerk` glides, `hold` stays put and
- * then cuts.
+ * then cuts, `linear` is the next sample of a path the recording computed
+ * frame by frame, a follow or a blend.
  */
 export declare function evalCamera(keys: CameraKey[], t: number): Rect;

package/dist/core/camera.js

@@ -56,7 +56,7 @@ export function scaleOf(rect, viewport) {
  * the scale by the same factor, which is what the eye actually reads as
  * constant speed.
  */
-function interpolateRect(a, b, u) {
+export function interpolateRect(a, b, u) {
     const cxA = a.x + a.w / 2;
     const cyA = a.y + a.h / 2;
     const cxB = b.x + b.w / 2;
@@ -67,10 +67,24 @@ function interpolateRect(a, b, u) {
     const cy = lerp(cyA, cyB, u);
     return { x: cx - w / 2, y: cy - h / 2, w, h };
 }
+/**
+ * Straight between two samples of a path, for keys a frame apart. The
+ * renderer asks only for frame times, where this lands on a sample exactly;
+ * between them, what `review` asks for is off by less than a frame's motion.
+ */
+function lerpRect(a, b, u) {
+    return {
+        x: lerp(a.x, b.x, u),
+        y: lerp(a.y, b.y, u),
+        w: lerp(a.w, b.w, u),
+        h: lerp(a.h, b.h, u),
+    };
+}
 /**
  * Where the camera is at time `t`. A key's `ease` describes how the camera
  * reaches it from the previous key: `minjerk` glides, `hold` stays put and
- * then cuts.
+ * then cuts, `linear` is the next sample of a path the recording computed
+ * frame by frame, a follow or a blend.
  */
 export function evalCamera(keys, t) {
     if (keys.length === 0) {
@@ -87,6 +101,8 @@ export function evalCamera(keys, t) {
             return prev.rect;
         const span = next.t - prev.t;
         const u = span <= 0 ? 1 : (t - prev.t) / span;
+        if (next.ease === "linear")
+            return lerpRect(prev.rect, next.rect, u);
         return interpolateRect(prev.rect, next.rect, minjerk(u));
     }
     return keys[keys.length - 1].rect;

package/dist/core/camera.js.map

@@ -1 +1 @@
-{"version":3,"file":"camera.js","sourceRoot":"","sources":["../../src/core/camera.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"camera.js","sourceRoot":"","sources":["../../src/core/camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAgBnD,MAAM,WAAW,GAAG,IAAI,CAAC;AACzB,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B,MAAM,UAAU,SAAS,CAAC,IAAU,EAAE,QAAkB;IACtD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO;QACL,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC;QACvC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QACxC,CAAC;QACD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,MAAY,EACZ,QAAkB,EAClB,UAAuB,EAAE;IAEzB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC;IACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACvD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;IAEhD,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;IAExC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;IAEjC,yEAAyE;IACzE,wCAAwC;IACxC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM;QAAE,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;;QAC9B,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IAEpB,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC;IAC3C,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;QACjB,CAAC,GAAG,QAAQ,CAAC;QACb,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC;QACnB,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IACtB,CAAC;IAED,OAAO,SAAS,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC/E,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,OAAO,CAAC,IAAU,EAAE,QAAkB;IACpD,OAAO,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,CAAO,EAAE,CAAO,EAAE,CAAS;IACzD,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAE1B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC7B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAE7B,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,CAAO,EAAE,CAAO,EAAE,CAAS;IAC3C,OAAO;QACL,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;KACrB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAiB,EAAE,CAAS;IACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAExC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;YAAE,SAAS;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;QAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACrE,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACpC,CAAC"}

package/dist/core/follow.d.ts

@@ -0,0 +1,129 @@
+import type { Viewport } from "./camera.js";
+import type { CursorTrack, Vec2 } from "./timeline.js";
+/**
+ * A camera that follows the cursor.
+ *
+ * The framing at each frame is a fixed size, `viewport / scale`, centred as
+ * near the cursor as three things allow:
+ *
+ *  1. **A dead zone.** The camera keeps a window centre that moves only when
+ *     the cursor pushes past the window's edge, the way a platform game's
+ *     camera follows its character. A cursor moving to the next field of a
+ *     form stays inside the window, so the camera does not answer it: a
+ *     camera that answered every movement would be the zooming in and out
+ *     this mode exists to stop, only smaller.
+ *  2. **The page.** The window centre is clamped so the frame never leaves
+ *     the captured viewport, which has nothing beyond its edge to show.
+ *  3. **A critically damped spring, run forward and then backward** over the
+ *     window's path.
+ *
+ * Why a spring run both ways, rather than once: a spring that only runs
+ * forward trails its target by twice its time constant times the target's
+ * speed. At 1.35× on a 1440-wide page, a spring soft enough to look smooth
+ * trailed a cursor crossing the page by enough to put the cursor at the
+ * frame's edge, and past it. The recording knows the whole cursor path
+ * before anything is drawn, so the camera may use the path's future as well
+ * as its past, and run backward the spring's lag cancels its own lag. What it
+ * costs is a little anticipation: the camera sets off a moment before the
+ * cursor does, which is what a camera operator who knew the script would do.
+ *
+ * The spring's impulse response is never negative, and neither is the
+ * reversed one, so every camera position is a weighted average of window
+ * positions. Three properties follow from that alone, with no clamping
+ * afterwards to break them: the camera never overshoots, because it never
+ * goes beyond where the window has been; it stays inside the page, because
+ * an average of positions inside an interval is inside it; and it moves
+ * smoothly, because a critically damped spring's velocity and acceleration
+ * are continuous however sharply its target turns.
+ */
+export type FollowSpec = {
+    /** Magnification, exactly: the frame is `viewport / scale` the whole time. */
+    scale: number;
+    /**
+     * The share of the frame, around its centre, the cursor can move within
+     * without moving the camera: `0.3` is a box 30% of the frame's width by
+     * 30% of its height.
+     */
+    deadZone: number;
+    /**
+     * How long the camera takes over a move the cursor made at once, from 3%
+     * to 97% of the way, in milliseconds. That span is eight of the spring's
+     * time constants, so this is eight times the time constant.
+     */
+    smoothingMs: number;
+};
+/**
+ * One step of a critically damped spring, `y'' + 2ωy' + ω²y = ω²u`, from
+ * position `y` and velocity `v`, with the target held at `u` for `dt`.
+ *
+ * Exact for a target held still over the step, rather than an Euler step's
+ * approximation, so the path depends on the frame rate only through where the
+ * cursor is sampled: a draft at 15 frames a second follows the same curve as
+ * a recording at 60.
+ */
+export declare function springStep(y: number, v: number, u: number, omega: number, dt: number): [number, number];
+/**
+ * A spring run forward and then backward: the same curve with no lag.
+ *
+ * Holding each sample over the step that ends on it leads the input by half
+ * a step on the way forward, and the backward pass trails it by the same
+ * half step, so the two cancel as well.
+ */
+export declare function zeroPhaseSpring(input: readonly number[], omega: number, dt: number): number[];
+export type FollowPathInput = {
+    cursor: CursorTrack;
+    /** Where the cursor is when the track is empty: its resting place in frame 0. */
+    cursorStart: Vec2;
+    viewport: Viewport;
+    fps: number;
+    spec: FollowSpec;
+    /** The first frame the follow is asked for: the first at or after its write. */
+    firstFrame: number;
+    /** The last frame anything will ask for. */
+    lastFrame: number;
+    /**
+     * When the follow stops reading the cursor, in seconds: the next camera
+     * write. From then on it treats the cursor as still where it was, so the
+     * camera comes to rest on the framing it was heading for instead of
+     * chasing a cursor the clip has stopped following.
+     */
+    until: number;
+};
+/**
+ * The centre of the follow's frame at every frame from `firstFrame` to
+ * `lastFrame`, in viewport pixels. The frame itself is `viewport / scale`,
+ * centred there.
+ *
+ * A pure function of its input: the same cursor track and the same numbers
+ * make the same path, to the bit, which is what lets a recording that follows
+ * the cursor be compared byte for byte with the next one.
+ */
+export declare function followCentres(input: FollowPathInput): Vec2[];
+export type FollowOptions = {
+    /** Magnification, exactly. */
+    scale?: number;
+    /** The share of the frame the cursor can move within without moving the camera. */
+    deadZone?: number;
+    /** How softly the camera follows, in milliseconds. */
+    smoothing?: number;
+    /** How long the camera takes to get from where it was into the follow. */
+    duration?: number;
+};
+export type FollowDefaults = {
+    followZoom: number;
+    followDeadZone: number;
+    followSmoothingMs: number;
+    zoomDurationMs: number;
+};
+/**
+ * A follow's options, with the config's defaults filled in and each one
+ * checked where the clip wrote it.
+ *
+ * Checked here rather than when the path is computed, because by then the
+ * clip has run to the end: a scale of 0.8 found in `finish()` would fail the
+ * recording without naming the line that asked for it.
+ */
+export declare function resolveFollow(options: FollowOptions, defaults: FollowDefaults): {
+    spec: FollowSpec;
+    durationMs: number;
+};

package/dist/core/follow.js

@@ -0,0 +1,151 @@
+import { clamp } from "./easing.js";
+import { evalCursor } from "./cursor.js";
+/** Time constants in `smoothingMs`: the span of a jump's response, 3% to 97%. */
+const TIME_CONSTANTS_PER_SMOOTHING = 8;
+/**
+ * Time constants of input held still before the backward pass starts.
+ *
+ * The backward pass has to start from rest, and a spring coming to rest never
+ * quite arrives: after thirty time constants the remainder is under a
+ * billionth of the distance it had to go, which on any page is far below a
+ * thousandth of a pixel.
+ */
+const SETTLED_AFTER = 30;
+/**
+ * One step of a critically damped spring, `y'' + 2ωy' + ω²y = ω²u`, from
+ * position `y` and velocity `v`, with the target held at `u` for `dt`.
+ *
+ * Exact for a target held still over the step, rather than an Euler step's
+ * approximation, so the path depends on the frame rate only through where the
+ * cursor is sampled: a draft at 15 frames a second follows the same curve as
+ * a recording at 60.
+ */
+export function springStep(y, v, u, omega, dt) {
+    const e = y - u;
+    const k = v + omega * e;
+    const decay = Math.exp(-omega * dt);
+    return [u + (e + k * dt) * decay, (v - omega * k * dt) * decay];
+}
+/** A spring over a whole sequence, starting at rest on its first value. */
+function spring(input, omega, dt) {
+    const out = new Array(input.length);
+    let y = input[0];
+    let v = 0;
+    for (let i = 0; i < input.length; i += 1) {
+        if (i > 0)
+            [y, v] = springStep(y, v, input[i], omega, dt);
+        out[i] = y;
+    }
+    return out;
+}
+/**
+ * A spring run forward and then backward: the same curve with no lag.
+ *
+ * Holding each sample over the step that ends on it leads the input by half
+ * a step on the way forward, and the backward pass trails it by the same
+ * half step, so the two cancel as well.
+ */
+export function zeroPhaseSpring(input, omega, dt) {
+    if (input.length === 0)
+        return [];
+    const forward = spring(input, omega, dt);
+    return spring(forward.reverse(), omega, dt).reverse();
+}
+/**
+ * The centre of the follow's frame at every frame from `firstFrame` to
+ * `lastFrame`, in viewport pixels. The frame itself is `viewport / scale`,
+ * centred there.
+ *
+ * A pure function of its input: the same cursor track and the same numbers
+ * make the same path, to the bit, which is what lets a recording that follows
+ * the cursor be compared byte for byte with the next one.
+ */
+export function followCentres(input) {
+    const { viewport, fps, spec, firstFrame, lastFrame } = input;
+    if (lastFrame < firstFrame)
+        return [];
+    if (!(spec.smoothingMs > 0)) {
+        throw new RangeError(`A follow's smoothing has to be more than 0ms, not ${spec.smoothingMs}.`);
+    }
+    const frameW = viewport.width / spec.scale;
+    const frameH = viewport.height / spec.scale;
+    // Half the dead zone each side of the window's centre.
+    const slackX = (spec.deadZone * frameW) / 2;
+    const slackY = (spec.deadZone * frameH) / 2;
+    const dt = 1 / fps;
+    const timeConstant = spec.smoothingMs / 1000 / TIME_CONSTANTS_PER_SMOOTHING;
+    const omega = 1 / timeConstant;
+    const cursorAt = (t) => input.cursor.length === 0
+        ? input.cursorStart
+        : evalCursor(input.cursor, Math.min(t, input.until));
+    // Past the last frame anything asks for, the path goes on until the window
+    // has been still for long enough that the backward pass can start from
+    // rest. The window is still once the cursor is: after the follow stops
+    // reading it, or after the track's last step, whichever is first.
+    const trackEnd = input.cursor.length === 0 ? 0 : input.cursor[input.cursor.length - 1].t1;
+    const stillFrom = Math.ceil(Math.min(input.until, trackEnd) * fps);
+    const farFrame = Math.max(lastFrame, stillFrom) +
+        Math.ceil(SETTLED_AFTER * timeConstant * fps);
+    const windowX = [];
+    const windowY = [];
+    let x = 0;
+    let y = 0;
+    for (let frame = firstFrame; frame <= farFrame; frame += 1) {
+        const [px, py] = cursorAt(frame / fps);
+        if (frame === firstFrame) {
+            // A follow starts centred on the cursor, as near as the page allows.
+            // The dead zone is for what the cursor does next; starting at its edge
+            // would frame the cursor off-centre for no reason anyone could see.
+            x = px;
+            y = py;
+        }
+        else {
+            x = clamp(x, px - slackX, px + slackX);
+            y = clamp(y, py - slackY, py + slackY);
+        }
+        x = clamp(x, frameW / 2, viewport.width - frameW / 2);
+        y = clamp(y, frameH / 2, viewport.height - frameH / 2);
+        windowX.push(x);
+        windowY.push(y);
+    }
+    const smoothX = zeroPhaseSpring(windowX, omega, dt);
+    const smoothY = zeroPhaseSpring(windowY, omega, dt);
+    const centres = [];
+    for (let i = 0; i <= lastFrame - firstFrame; i += 1) {
+        centres.push([smoothX[i], smoothY[i]]);
+    }
+    return centres;
+}
+/**
+ * A follow's options, with the config's defaults filled in and each one
+ * checked where the clip wrote it.
+ *
+ * Checked here rather than when the path is computed, because by then the
+ * clip has run to the end: a scale of 0.8 found in `finish()` would fail the
+ * recording without naming the line that asked for it.
+ */
+export function resolveFollow(options, defaults) {
+    const scale = options.scale ?? defaults.followZoom;
+    const deadZone = options.deadZone ?? defaults.followDeadZone;
+    const smoothingMs = options.smoothing ?? defaults.followSmoothingMs;
+    const durationMs = options.duration ?? defaults.zoomDurationMs;
+    if (!Number.isFinite(scale) || scale < 1) {
+        throw new RangeError(`camera.follow: scale is ${scale}. It is a magnification, at least 1: ` +
+            "1.35 shows the page at 1.35 times its size.");
+    }
+    if (!Number.isFinite(deadZone) || deadZone < 0 || deadZone >= 1) {
+        throw new RangeError(`camera.follow: deadZone is ${deadZone}. It is a share of the frame, ` +
+            "from 0 (answer every movement) to below 1: 0.3 lets the cursor " +
+            "move across the middle 30% without moving the camera.");
+    }
+    if (!Number.isFinite(smoothingMs) || smoothingMs <= 0) {
+        throw new RangeError(`camera.follow: smoothing is ${smoothingMs}. It is in milliseconds, ` +
+            "and more than 0: larger follows more softly.");
+    }
+    if (!Number.isFinite(durationMs) || durationMs < 0) {
+        throw new RangeError(`camera.follow: duration is ${durationMs}. It is in milliseconds, ` +
+            "0 or more: 0 cuts straight into the follow.");
+    }
+    return { spec: { scale, deadZone, smoothingMs }, durationMs };
+}
+//# sourceMappingURL=follow.js.map

package/dist/core/follow.js.map

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

package/dist/core/motion-defaults.d.ts

@@ -45,6 +45,35 @@ export declare const MOTION: {
     readonly maxZoom: 1.65;
     /** Padding around a zoom target, as a fraction of its size. */
     readonly zoomPad: 0.12;
+    /**
+     * How far in a camera that follows the cursor goes. Gentler than a zoom's
+     * 1.5, because a zoom frames one thing and stops, while a follow keeps the
+     * cursor in frame as it travels and needs more of the page around it to
+     * say where it is going. A website review that found clips zooming in and
+     * out too much settled on this: in a little, once, and pan.
+     */
+    readonly followZoom: 1.35;
+    /**
+     * The share of a following camera's frame, around its centre, that the
+     * cursor can move within without the camera answering. At 1.35× on a page
+     * 1440 wide that is 160 pixels either side and 100 up or down: a move to
+     * the next field of a form stays inside it, a move across the page does
+     * not. Much smaller and the camera fidgets with every small movement.
+     */
+    readonly followDeadZone: 0.3;
+    /**
+     * How softly a following camera moves: the time it would take over a move
+     * the cursor made at once, 3% to 97% of the way. The camera runs over the
+     * cursor's whole path, so it has no lag to trade against; larger is
+     * smoother, and sets off earlier before each move the cursor makes. At
+     * 600, with the dead zone above, it sets off within about a tenth of a
+     * second of the cursor and comes to rest about a fifth of a second after
+     * the cursor stops: close enough to read as following, soft enough that a
+     * pan across the page never lurches. With no dead zone it would lead the
+     * cursor by a quarter of a second, which starts to read as a camera that
+     * moved first.
+     */
+    readonly followSmoothingMs: 600;
     /** How long a highlight stays up if the script does not say. */
     readonly highlightMs: 1800;
     /** Click ripple, in the renderer. */