@altpsyche/maths 0.4.1 → 0.5.0

package/README.md

@@ -22,6 +22,10 @@ svgMarkup(at(figure, 0.5), viewMatrix(figure.extent, 'contain', 640, 360), 640,
 
 <img src="docs/tangent.svg" width="720" alt="A parabola on a labelled grid, the region under it shaded to a point on the curve, the tangent at that point drawn, and the slope written as a number.">
 
+The picture arrives rather than appearing. The grid fades, the axes draw on, their labels come in one
+after another, the curve draws, the dot grows out of the origin, and the dot is pointed at where the
+slope is nothing. Then it walks the curve at one speed and flashes at the top.
+
 ```ts
 import { axes, coordsOf, group, interval, numberPlane, plot, scaleOf, shape } from '@altpsyche/maths';
 
@@ -55,8 +59,24 @@ which is what the number in the corner is.
 
 <img src="docs/tangent-strip.svg" width="960" alt="Four frames of the same figure side by side, the point walking up the curve and the shaded region growing behind it.">
 
-Four times of one figure, side by side. A moving picture in a README needs a GIF and this package
-has no encoder, so the strip shows the motion in a still.
+Four times of one figure, side by side: the picture arrived, the beat at the stationary point, half
+way up, and the top. A moving picture in a README needs a GIF and this package has no encoder, so the
+strip shows the motion in a still.
+
+## The animations
+
+`fadeIn`, `fadeOut`, `fadeTo`, `draw`, `morph`, `moveBy`, `rotate`, `scale`, `growFrom`, `moveAlong`,
+`indicate`, `flash` and `circumscribe`. A `Timeline` plays them in order, plays several `together`, or
+`stagger`s a row so its parts arrive one after another.
+
+A turn and a growth happen about a point the marks decide for themselves, which is the middle of the
+box round them. `boundsOf` is that box, worked out from where each piece of the curve turns back on
+itself rather than from the points the curve is written from.
+
+`moveAlong` carries a mark along a path at one speed, measured by the path's length. Even steps in a
+curve's own parameter are uneven steps along the curve: a step covers more of it where the curve is
+moving fast, which on a quarter circle is a 6.9% difference between the longest step and the shortest
+and on the demo's own walk is 82%.
 
 Both pictures are written by `svgMarkup`, which needs no browser, so `npm run demos` regenerates
 them and a test compares the bytes against the committed files.

package/dist/figure/animation.d.ts

@@ -1,6 +1,6 @@
 import { type Vec2 } from '../values/vec2.js';
 import { type Path } from './path.js';
-import type { Mark } from './mark.js';
+import type { Colour, Mark, Stroke } from './mark.js';
 export type Animation = (marks: readonly Mark[], along: number) => readonly Mark[];
 /** From nothing to whatever opacity the mark already had, so a mark that is
  * half faded by design does not become solid on the way in. */
@@ -27,3 +27,96 @@ export declare function morph(target: string, into: Path): Animation;
 /** A mark's own opacity walked to a value, for a figure that wants a thing dimmed
  * rather than gone. */
 export declare function fadeTo(target: string, opacity: number): Animation;
+export interface AboutOptions {
+    /** The point the change happens about. The middle of the box round the marks
+     * being changed unless a figure names one. */
+    pivot?: Vec2;
+}
+/**
+ * Turned about a point, by an angle in radians.
+ *
+ * A text mark's anchor moves and its words stay upright. A mark carries no
+ * rotation of its own, so turning the words would mean adding one to what both
+ * painters have to do, and a label that stays readable while the thing it names
+ * turns is what a figure wants anyway, which is the same reason a number line
+ * takes a direction rather than being turned on its side.
+ */
+export declare function rotate(target: string, angle: number, options?: AboutOptions): Animation;
+export interface ScaleOptions extends AboutOptions {
+    /** What it is scaled by at the start of the span, which is its own size. */
+    from?: number;
+}
+/** Grown or shrunk about a point, from one factor to another. */
+export declare function scale(target: string, to: number, options?: ScaleOptions): Animation;
+/**
+ * Carried along a path at a steady pace, by length rather than by piece.
+ *
+ * What it moves is the offset from the path's own start, so a mark placed at that
+ * start travels the path and a mark placed elsewhere travels the same shape from
+ * where it stands. That is what `moveBy` does with a straight offset, and it is
+ * what makes this nothing at the beginning of its span like every other change
+ * here.
+ */
+export declare function moveAlong(target: string, path: Path): Animation;
+/**
+ * Grown from nothing at a point, which is a growth starting at no size.
+ *
+ * Left out, the point is the middle of the box round the marks, so a thing grows
+ * out of where it already is. At the end of the span it is the marks themselves
+ * rather than the marks rebuilt through a transform of one, so a growth that has
+ * finished leaves the geometry the author wrote.
+ */
+export declare function growFrom(target: string, from?: Vec2): Animation;
+export interface IndicateOptions extends AboutOptions {
+    /** How big it gets at the middle of the span. */
+    factor?: number;
+    /** Held for the length of the span and then let go. */
+    colour?: Colour;
+}
+/**
+ * Swelled and settled, to point at something without moving it.
+ *
+ * The colour is swapped for the length of the span rather than walked into. A
+ * colour here is any CSS colour written as text, and walking between two of them
+ * needs a reader for every form one can take, which does not exist here yet.
+ */
+export declare function indicate(target: string, options?: IndicateOptions): Animation;
+export interface FlashOptions {
+    stroke: Stroke;
+    /** Where it flashes from. The middle of the box round the marks unless named. */
+    at?: Vec2;
+    rays?: number;
+    /** How far the far end of a ray reaches at the widest, in figure units. Twice
+     * the distance from the middle of the box to its corner unless named, so the
+     * rays sit outside the thing they are pointing at. */
+    reach?: number;
+    /** Where the near end of a ray sits, as a share of the reach. */
+    inner?: number;
+}
+/**
+ * Rays out from a point and gone, for a moment a figure wants a reader to look
+ * at.
+ *
+ * The rays are in the list at every fraction of the span, at nothing at both
+ * ends, rather than appended part way through. A mark that arrives between one
+ * frame and the next turns up in a comparison between two frames as something
+ * that changed, and a figure's marks are compared frame to frame by every gate
+ * here.
+ */
+export declare function flash(target: string, options: FlashOptions): Animation;
+export interface CircumscribeOptions {
+    stroke: Stroke;
+    /** A box round the thing, or the ellipse through the same four sides. */
+    around?: 'box' | 'ellipse';
+    /** How far outside the box it sits, in figure units. */
+    padding?: number;
+}
+/**
+ * A shape drawn round something and then let go.
+ *
+ * The first half of the span draws it on and the second half fades it, so one
+ * span is the whole gesture rather than two a figure has to line up. The shape
+ * is in the list at every fraction, with nothing drawn at the beginning and
+ * nothing showing at the end, for the reason a flash keeps its rays.
+ */
+export declare function circumscribe(target: string, options: CircumscribeOptions): Animation;

package/dist/figure/animation.js

@@ -13,9 +13,13 @@
 import { mat3 } from '../values/mat3.js';
 import { vec2 } from '../values/vec2.js';
 import { lerp } from '../values/scalar.js';
-import { transformPath } from './path.js';
+import { smoothstep } from '../values/ease.js';
+import { circle, line, polygon, transformPath } from './path.js';
 import { trimPath } from './trim.js';
 import { lerpPath } from './morph.js';
+import { pointAlong } from './length.js';
+import { boundsOfMarks, centreOf } from './bounds.js';
+import { interval } from '../values/interval.js';
 /**
  * Which marks an animation touches.
  *
@@ -80,3 +84,227 @@ export function morph(target, into) {
 export function fadeTo(target, opacity) {
     return over(target, (mark, along) => ({ ...mark, opacity: lerp(mark.opacity ?? 1, opacity, along) }));
 }
+/**
+ * A mark carried through a transform, geometry and weight together.
+ *
+ * A transform that scales makes the lines inside it thicker and the words
+ * bigger, the way it makes everything else bigger, which is what `flatten`
+ * already does for a group that scales. Doing less here would leave a shrinking
+ * mark with the stroke it started at.
+ */
+function carried(mark, through) {
+    const scale = mat3.scaleFactor(through);
+    if (mark.kind === 'text') {
+        return { ...mark, at: mat3.transformPoint(through, mark.at), size: mark.size * scale };
+    }
+    return {
+        ...mark,
+        path: transformPath(mark.path, through),
+        stroke: mark.stroke ? { ...mark.stroke, width: mark.stroke.width * scale } : undefined,
+    };
+}
+/**
+ * A change built round a point the marks themselves decide.
+ *
+ * The pivot is read off the marks as they arrive, which is before this change has
+ * moved them, so it is the same point at every time and a turn of a whole circle
+ * lands where it began. Reading it back off the marks after the change would let
+ * it drift, because the box round a turned shape is not the turned box.
+ */
+function about(target, options, step) {
+    return (marks, along) => {
+        const touched = marks.filter((mark) => touches(mark.id, target));
+        if (touched.length === 0)
+            return marks;
+        const box = boundsOfMarks(touched);
+        const pivot = options.pivot ?? (box ? centreOf(box) : vec2(0, 0));
+        const through = step(along, pivot);
+        if (through === null)
+            return marks;
+        return marks.map((mark) => (touches(mark.id, target) ? carried(mark, through) : mark));
+    };
+}
+/** The transform for a change about a point: back to the origin, the change,
+ * then back where it was. */
+function around(pivot, change) {
+    return mat3.multiply(mat3.multiply(mat3.translation(pivot), change), mat3.translation(vec2.scale(pivot, -1)));
+}
+/**
+ * Turned about a point, by an angle in radians.
+ *
+ * A text mark's anchor moves and its words stay upright. A mark carries no
+ * rotation of its own, so turning the words would mean adding one to what both
+ * painters have to do, and a label that stays readable while the thing it names
+ * turns is what a figure wants anyway, which is the same reason a number line
+ * takes a direction rather than being turned on its side.
+ */
+export function rotate(target, angle, options = {}) {
+    return about(target, options, (along, pivot) => {
+        const turned = angle * along;
+        return turned === 0 ? null : around(pivot, mat3.rotation(turned));
+    });
+}
+/** Grown or shrunk about a point, from one factor to another. */
+export function scale(target, to, options = {}) {
+    const start = options.from ?? 1;
+    return about(target, options, (along, pivot) => {
+        const factor = lerp(start, to, along);
+        return factor === 1 ? null : around(pivot, mat3.scaling(vec2(factor, factor)));
+    });
+}
+/**
+ * Carried along a path at a steady pace, by length rather than by piece.
+ *
+ * What it moves is the offset from the path's own start, so a mark placed at that
+ * start travels the path and a mark placed elsewhere travels the same shape from
+ * where it stands. That is what `moveBy` does with a straight offset, and it is
+ * what makes this nothing at the beginning of its span like every other change
+ * here.
+ */
+export function moveAlong(target, path) {
+    const start = pointAlong(path, 0);
+    return (marks, along) => {
+        if (start === null || along === 0)
+            return marks;
+        const reached = pointAlong(path, along);
+        if (reached === null)
+            return marks;
+        const step = mat3.translation(vec2.sub(reached, start));
+        return marks.map((mark) => (touches(mark.id, target) ? carried(mark, step) : mark));
+    };
+}
+/**
+ * Grown from nothing at a point, which is a growth starting at no size.
+ *
+ * Left out, the point is the middle of the box round the marks, so a thing grows
+ * out of where it already is. At the end of the span it is the marks themselves
+ * rather than the marks rebuilt through a transform of one, so a growth that has
+ * finished leaves the geometry the author wrote.
+ */
+export function growFrom(target, from) {
+    return scale(target, 1, { from: 0, pivot: from });
+}
+/**
+ * Out and back over a span, flat at the beginning, the peak and the end.
+ *
+ * Each half is the smoothstep the tracks and the timeline already pace changes
+ * with, so a pulse leaves from rest, turns without a corner, and settles.
+ */
+function thereAndBack(along) {
+    return along < 0.5 ? smoothstep(along * 2) : smoothstep(2 - along * 2);
+}
+/** A mark's own colours replaced, fill and stroke together. */
+function painted(mark, colour) {
+    if (mark.kind === 'text')
+        return { ...mark, fill: { ...mark.fill, colour } };
+    return {
+        ...mark,
+        fill: mark.fill ? { ...mark.fill, colour } : undefined,
+        stroke: mark.stroke ? { ...mark.stroke, colour } : undefined,
+    };
+}
+/**
+ * Swelled and settled, to point at something without moving it.
+ *
+ * The colour is swapped for the length of the span rather than walked into. A
+ * colour here is any CSS colour written as text, and walking between two of them
+ * needs a reader for every form one can take, which does not exist here yet.
+ */
+export function indicate(target, options = {}) {
+    const peak = options.factor ?? 1.2;
+    const swell = about(target, options, (along, pivot) => {
+        const factor = lerp(1, peak, thereAndBack(along));
+        return factor === 1 ? null : around(pivot, mat3.scaling(vec2(factor, factor)));
+    });
+    const colour = options.colour;
+    return (marks, along) => {
+        const swelled = swell(marks, along);
+        if (colour === undefined || along <= 0 || along >= 1)
+            return swelled;
+        if (!swelled.some((mark) => touches(mark.id, target)))
+            return swelled;
+        return swelled.map((mark) => (touches(mark.id, target) ? painted(mark, colour) : mark));
+    };
+}
+/**
+ * Rays out from a point and gone, for a moment a figure wants a reader to look
+ * at.
+ *
+ * The rays are in the list at every fraction of the span, at nothing at both
+ * ends, rather than appended part way through. A mark that arrives between one
+ * frame and the next turns up in a comparison between two frames as something
+ * that changed, and a figure's marks are compared frame to frame by every gate
+ * here.
+ */
+export function flash(target, options) {
+    const count = Math.max(1, Math.round(options.rays ?? 12));
+    const inner = options.inner ?? 0.5;
+    return (marks, along) => {
+        const touched = marks.filter((mark) => touches(mark.id, target));
+        if (touched.length === 0)
+            return marks;
+        const box = boundsOfMarks(touched);
+        if (box === null)
+            return marks;
+        const centre = options.at ?? centreOf(box);
+        const corner = Math.hypot(interval.span(box.x) / 2, interval.span(box.y) / 2);
+        const reach = options.reach ?? corner * 2;
+        const opacity = thereAndBack(along);
+        const rays = [];
+        for (let ray = 0; ray < count; ray++) {
+            const angle = (2 * Math.PI * ray) / count;
+            const direction = vec2(Math.cos(angle), Math.sin(angle));
+            const near = vec2.add(centre, vec2.scale(direction, reach * inner * along));
+            const far = vec2.add(centre, vec2.scale(direction, reach * along));
+            rays.push({
+                kind: 'path',
+                id: `${target}/flash/${ray}`,
+                path: line(near, far),
+                stroke: options.stroke,
+                opacity,
+            });
+        }
+        return [...marks, ...rays];
+    };
+}
+/**
+ * A shape drawn round something and then let go.
+ *
+ * The first half of the span draws it on and the second half fades it, so one
+ * span is the whole gesture rather than two a figure has to line up. The shape
+ * is in the list at every fraction, with nothing drawn at the beginning and
+ * nothing showing at the end, for the reason a flash keeps its rays.
+ */
+export function circumscribe(target, options) {
+    const padding = options.padding ?? 0;
+    return (marks, along) => {
+        const touched = marks.filter((mark) => touches(mark.id, target));
+        if (touched.length === 0)
+            return marks;
+        const box = boundsOfMarks(touched);
+        if (box === null)
+            return marks;
+        const centre = centreOf(box);
+        const across = interval.span(box.x) / 2 + padding;
+        const up = interval.span(box.y) / 2 + padding;
+        const whole = (options.around ?? 'box') === 'ellipse'
+            ? transformPath(circle(vec2(0, 0), 1), mat3.multiply(mat3.translation(centre), mat3.scaling(vec2(across, up))))
+            : polygon([
+                vec2(centre.x - across, centre.y - up),
+                vec2(centre.x + across, centre.y - up),
+                vec2(centre.x + across, centre.y + up),
+                vec2(centre.x - across, centre.y + up),
+            ]);
+        const drawing = along <= 0.5;
+        return [
+            ...marks,
+            {
+                kind: 'path',
+                id: `${target}/circumscribed`,
+                path: drawing ? trimPath(whole, along * 2) : whole,
+                stroke: options.stroke,
+                opacity: drawing ? 1 : 2 - along * 2,
+            },
+        ];
+    };
+}

package/dist/figure/bounds.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The smallest box holding a path, worked out rather than sampled.
+ *
+ * A curve's furthest point is usually not one of the points it is written from,
+ * so the box round the control points is bigger than the box round the curve.
+ * The derivative of a cubic is a quadratic, so where each piece turns back on
+ * itself is the root of a quadratic, and the box is those turns together with
+ * the ends of every piece.
+ */
+import { type Interval } from '../values/interval.js';
+import { type Path } from './path.js';
+import { type Vec2 } from '../values/vec2.js';
+import type { Mark } from './mark.js';
+export interface Bounds {
+    readonly x: Interval;
+    readonly y: Interval;
+}
+/** The box round a path, or nothing where the path holds no points. */
+export declare function boundsOf(path: Path): Bounds | null;
+/**
+ * The box round a list of marks, or nothing where the list is empty.
+ *
+ * A text mark reaches only as far as its own anchor. How wide some text is
+ * depends on which fonts the machine has, so a box that took it in would be a
+ * different box on two machines, and nothing about a figure's layout may turn on
+ * that.
+ */
+export declare function boundsOfMarks(marks: readonly Mark[]): Bounds | null;
+/** The middle of a box, which is what a turn or a growth happens about when a
+ * figure names no other point. */
+export declare function centreOf(bounds: Bounds): Vec2;

package/dist/figure/bounds.js

@@ -0,0 +1,112 @@
+/**
+ * The smallest box holding a path, worked out rather than sampled.
+ *
+ * A curve's furthest point is usually not one of the points it is written from,
+ * so the box round the control points is bigger than the box round the curve.
+ * The derivative of a cubic is a quadratic, so where each piece turns back on
+ * itself is the root of a quadratic, and the box is those turns together with
+ * the ends of every piece.
+ */
+import { interval } from '../values/interval.js';
+import { pointOn } from './path.js';
+import { vec2 } from '../values/vec2.js';
+/** Below this a squared term counts as absent and the derivative is read as a
+ * straight line, which is what a cubic written as a straight segment is. */
+const FLAT = 1e-12;
+/**
+ * Where one piece turns back on itself along one axis, as fractions of its own
+ * length strictly between its two ends.
+ *
+ * The ends are added by the caller, since they belong to the piece rather than
+ * to its turns, and a piece with no turn at all still has them.
+ */
+function turns(from, control1, control2, to) {
+    const square = -from + 3 * control1 - 3 * control2 + to;
+    const linear = 2 * from - 4 * control1 + 2 * control2;
+    const constant = control1 - from;
+    const inside = (at) => (at > 0 && at < 1 ? [at] : []);
+    if (Math.abs(square) < FLAT) {
+        if (Math.abs(linear) < FLAT)
+            return [];
+        return inside(-constant / linear);
+    }
+    const under = linear * linear - 4 * square * constant;
+    if (under < 0)
+        return [];
+    const root = Math.sqrt(under);
+    return [...inside((-linear + root) / (2 * square)), ...inside((-linear - root) / (2 * square))];
+}
+function grown(bounds, value) {
+    if (value < bounds.low)
+        bounds.low = value;
+    if (value > bounds.high)
+        bounds.high = value;
+}
+function reach(into, point) {
+    grown(into.x, point.x);
+    grown(into.y, point.y);
+}
+function pieceReach(into, from, curve) {
+    reach(into, curve.to);
+    for (const at of turns(from.x, curve.control1.x, curve.control2.x, curve.to.x)) {
+        reach(into, pointOn(from, curve, at));
+    }
+    for (const at of turns(from.y, curve.control1.y, curve.control2.y, curve.to.y)) {
+        reach(into, pointOn(from, curve, at));
+    }
+}
+function empty() {
+    return {
+        x: { low: Infinity, high: -Infinity },
+        y: { low: Infinity, high: -Infinity },
+    };
+}
+function settled(box) {
+    if (box.x.low > box.x.high)
+        return null;
+    return { x: interval(box.x.low, box.x.high), y: interval(box.y.low, box.y.high) };
+}
+/** The box round a path, or nothing where the path holds no points. */
+export function boundsOf(path) {
+    const box = empty();
+    for (const subpath of path) {
+        reach(box, subpath.start);
+        let from = subpath.start;
+        for (const curve of subpath.curves) {
+            pieceReach(box, from, curve);
+            from = curve.to;
+        }
+    }
+    return settled(box);
+}
+/**
+ * The box round a list of marks, or nothing where the list is empty.
+ *
+ * A text mark reaches only as far as its own anchor. How wide some text is
+ * depends on which fonts the machine has, so a box that took it in would be a
+ * different box on two machines, and nothing about a figure's layout may turn on
+ * that.
+ */
+export function boundsOfMarks(marks) {
+    const box = empty();
+    for (const mark of marks) {
+        if (mark.kind === 'text') {
+            reach(box, mark.at);
+            continue;
+        }
+        for (const subpath of mark.path) {
+            reach(box, subpath.start);
+            let from = subpath.start;
+            for (const curve of subpath.curves) {
+                pieceReach(box, from, curve);
+                from = curve.to;
+            }
+        }
+    }
+    return settled(box);
+}
+/** The middle of a box, which is what a turn or a growth happens about when a
+ * figure names no other point. */
+export function centreOf(bounds) {
+    return vec2(interval.at(bounds.x, 0.5), interval.at(bounds.y, 0.5));
+}

package/dist/figure/length.d.ts

@@ -0,0 +1,53 @@
+/**
+ * How long a path is, measured piece by piece, and where a length falls inside
+ * one piece.
+ *
+ * A cubic's parameter is not its length: the same step in parameter covers more
+ * of the curve where the curve is moving fast. So anything that walks a path at
+ * a steady pace needs the two related, and this is the table that relates them.
+ *
+ * The table is sampled rather than solved. A cubic's length has no closed form,
+ * so every library that measures one either samples it or integrates it
+ * numerically, and the samples are wanted anyway.
+ */
+import { type Vec2 } from '../values/vec2.js';
+import { type Path } from './path.js';
+export interface Measured {
+    /** The length reached at each sample parameter, starting at nothing and
+     * ending at the whole, so the piece's own parameter can be read back out of a
+     * length. */
+    readonly upTo: readonly number[];
+    readonly total: number;
+}
+export interface Measure {
+    /** Every piece of every subpath, in the order a walk crosses them. */
+    readonly per: readonly (readonly Measured[])[];
+    readonly total: number;
+}
+/** Every piece's length and the whole, which is what a walk by length needs
+ * before it can find which piece a place falls in. */
+export declare function measurePath(path: Path): Measure;
+/**
+ * The parameter a length into one piece.
+ *
+ * Reading the fraction of the length as the parameter is exact only where the
+ * curve moves at one rate, which is a straight line. Walking the table instead
+ * and interpolating inside the one sample the length lands in makes a cut by
+ * length even along a curve as well: measured on a quarter circle, cutting at
+ * twenty even fractions of its length was 4.7e-3 of the whole out at the worst
+ * of them and is 1.4e-4 out now.
+ */
+export declare function parameterAt(measured: Measured, wanted: number): number;
+/** How long a path is, in figure units, across every subpath it holds. It reads
+ * a little short of the truth, by the chord error the sample count above
+ * states. */
+export declare function lengthOf(path: Path): number;
+/**
+ * The point a fraction of the way along a path, measured by length rather than
+ * by piece or by parameter.
+ *
+ * A fraction outside nothing to one is held at the nearer end, so a walk that
+ * overshoots stops at the end of the path rather than carrying on past it. A
+ * path with no points has no such place and hands back nothing.
+ */
+export declare function pointAlong(path: Path, fraction: number): Vec2 | null;

package/dist/figure/length.js

@@ -0,0 +1,117 @@
+/**
+ * How long a path is, measured piece by piece, and where a length falls inside
+ * one piece.
+ *
+ * A cubic's parameter is not its length: the same step in parameter covers more
+ * of the curve where the curve is moving fast. So anything that walks a path at
+ * a steady pace needs the two related, and this is the table that relates them.
+ *
+ * The table is sampled rather than solved. A cubic's length has no closed form,
+ * so every library that measures one either samples it or integrates it
+ * numerically, and the samples are wanted anyway.
+ */
+import { vec2 } from '../values/vec2.js';
+import { pointOn } from './path.js';
+import { clamp } from '../values/scalar.js';
+/**
+ * How many samples measure one piece.
+ *
+ * Sixteen chords read a quarter circle 4 parts in ten thousand short of its true
+ * length, since a chord cuts the corner off the arc it spans. What the count is
+ * chosen for is the evenness of a walk rather than the total, and a share of the
+ * length is a ratio the shortfall largely cancels out of: measured, twenty steps
+ * along a quarter circle vary by 0.36% in size at this count. Doubling it costs
+ * twice the work in every cut and every walk and buys a total four times closer,
+ * which nothing here has asked for.
+ */
+const SAMPLES = 16;
+function measureCurve(from, curve) {
+    const upTo = [0];
+    let total = 0;
+    let previous = from;
+    for (let at = 1; at <= SAMPLES; at++) {
+        const point = pointOn(from, curve, at / SAMPLES);
+        total += vec2.distance(previous, point);
+        upTo.push(total);
+        previous = point;
+    }
+    return { upTo, total };
+}
+/** Every piece's length and the whole, which is what a walk by length needs
+ * before it can find which piece a place falls in. */
+export function measurePath(path) {
+    let total = 0;
+    const per = path.map((subpath) => {
+        let from = subpath.start;
+        return subpath.curves.map((curve) => {
+            const measured = measureCurve(from, curve);
+            from = curve.to;
+            total += measured.total;
+            return measured;
+        });
+    });
+    return { per, total };
+}
+/**
+ * The parameter a length into one piece.
+ *
+ * Reading the fraction of the length as the parameter is exact only where the
+ * curve moves at one rate, which is a straight line. Walking the table instead
+ * and interpolating inside the one sample the length lands in makes a cut by
+ * length even along a curve as well: measured on a quarter circle, cutting at
+ * twenty even fractions of its length was 4.7e-3 of the whole out at the worst
+ * of them and is 1.4e-4 out now.
+ */
+export function parameterAt(measured, wanted) {
+    const { upTo, total } = measured;
+    if (!(total > 0) || wanted <= 0)
+        return 0;
+    if (wanted >= total)
+        return 1;
+    let sample = 1;
+    while (sample < upTo.length - 1 && upTo[sample] < wanted)
+        sample++;
+    const low = upTo[sample - 1];
+    const high = upTo[sample];
+    const within = high > low ? (wanted - low) / (high - low) : 0;
+    return (sample - 1 + within) / SAMPLES;
+}
+/** How long a path is, in figure units, across every subpath it holds. It reads
+ * a little short of the truth, by the chord error the sample count above
+ * states. */
+export function lengthOf(path) {
+    return measurePath(path).total;
+}
+/**
+ * The point a fraction of the way along a path, measured by length rather than
+ * by piece or by parameter.
+ *
+ * A fraction outside nothing to one is held at the nearer end, so a walk that
+ * overshoots stops at the end of the path rather than carrying on past it. A
+ * path with no points has no such place and hands back nothing.
+ */
+export function pointAlong(path, fraction) {
+    if (path.length === 0)
+        return null;
+    const { per, total } = measurePath(path);
+    if (!(total > 0))
+        return path[0].start;
+    const wanted = total * clamp(fraction, 0, 1);
+    let walked = 0;
+    for (let at = 0; at < path.length; at++) {
+        const subpath = path[at];
+        let from = subpath.start;
+        for (let piece = 0; piece < subpath.curves.length; piece++) {
+            const curve = subpath.curves[piece];
+            const measured = per[at][piece];
+            if (walked + measured.total >= wanted)
+                return pointOn(from, curve, parameterAt(measured, wanted - walked));
+            walked += measured.total;
+            from = curve.to;
+        }
+    }
+    // Reached only when the lengths added up a hair short of the whole, so the
+    // place asked for is the far end.
+    const last = path[path.length - 1];
+    return last.curves.length > 0 ? last.curves[last.curves.length - 1].to : last.start;
+}

package/dist/figure/timeline.d.ts

@@ -22,6 +22,12 @@ export interface PlayOptions {
      * animation with the one before it. */
     after?: number;
 }
+export interface StaggerOptions extends PlayOptions {
+    /** Seconds between one change starting and the next. A quarter of each
+     * change's own length unless a figure says otherwise, so a row overlaps rather
+     * than running one at a time. */
+    gap?: number;
+}
 /**
  * The ordered list, built by naming one thing after another.
  *
@@ -37,6 +43,15 @@ export declare class Timeline {
     play(animation: Animation, seconds: number, options?: PlayOptions): Timeline;
     /** Several changes over one span, which is how two things move at once. */
     together(animations: readonly Animation[], seconds: number, options?: PlayOptions): Timeline;
+    /**
+     * A row of changes, each starting a gap after the one before and each running
+     * the same length.
+     *
+     * Written out by hand this is one play a change with a negative wait between
+     * them, and getting that arithmetic right at every entry is what a row of six
+     * things arriving one after another used to cost.
+     */
+    stagger(animations: readonly Animation[], seconds: number, options?: StaggerOptions): Timeline;
     wait(seconds: number): Timeline;
     /**
      * The marks as every span leaves them at a time.

package/dist/figure/timeline.js

@@ -37,6 +37,22 @@ export class Timeline {
         });
         return built;
     }
+    /**
+     * A row of changes, each starting a gap after the one before and each running
+     * the same length.
+     *
+     * Written out by hand this is one play a change with a negative wait between
+     * them, and getting that arithmetic right at every entry is what a row of six
+     * things arriving one after another used to cost.
+     */
+    stagger(animations, seconds, options = {}) {
+        const gap = Math.max(0, options.gap ?? seconds / 4);
+        let built = this;
+        animations.forEach((animation, at) => {
+            built = built.play(animation, seconds, at === 0 ? options : { ...options, after: gap - seconds });
+        });
+        return built;
+    }
     wait(seconds) {
         return new Timeline(this.spans, this.duration + seconds);
     }

package/dist/figure/trim.d.ts

@@ -1,4 +1,4 @@
-import { type Path } from './path.js';
+import type { Path } from './path.js';
 /**
  * The path up to a fraction of its total length.
  *

package/dist/figure/trim.js

@@ -4,14 +4,11 @@
  * The cut is by length rather than by segment, so a path whose segments differ in
  * size is drawn at one steady pace. Parameterising by segment instead is cheaper
  * and reads wrong: a long side would be crossed in the same time as a short one
- * and the pen would visibly speed up and slow down.
+ * and the pen would visibly speed up and slow down. The length inside a segment
+ * is read off that segment's own table for the same reason.
  */
 import { vec2 } from '../values/vec2.js';
-import { pointOn } from './path.js';
-/** How many samples measure one segment. Sixteen holds the length of a quarter
- * circle to better than a part in ten thousand, which is finer than the curve's
- * own error against a true arc. */
-const SAMPLES = 16;
+import { measurePath, parameterAt } from './length.js';
 /**
  * A cubic cut at a fraction of its own parameter, keeping the first piece.
  *
@@ -26,32 +23,6 @@ function splitCubic(from, curve, along) {
     const e = vec2.lerp(b, c, along);
     return { control1: a, control2: d, to: vec2.lerp(d, e, along) };
 }
-/** A segment's length, measured by walking it in straight steps. */
-function segmentLength(from, curve) {
-    let total = 0;
-    let previous = from;
-    for (let at = 1; at <= SAMPLES; at++) {
-        const point = pointOn(from, curve, at / SAMPLES);
-        total += vec2.distance(previous, point);
-        previous = point;
-    }
-    return total;
-}
-/** Every segment's length and the total, which is what a cut by length needs
- * before it can find which segment the cut falls in. */
-function lengths(path) {
-    let total = 0;
-    const per = path.map((subpath) => {
-        let from = subpath.start;
-        return subpath.curves.map((curve) => {
-            const length = segmentLength(from, curve);
-            from = curve.to;
-            total += length;
-            return length;
-        });
-    });
-    return { per, total };
-}
 /**
  * The path up to a fraction of its total length.
  *
@@ -65,7 +36,7 @@ export function trimPath(path, fraction) {
         return path;
     if (fraction <= 0)
         return [];
-    const { per, total } = lengths(path);
+    const { per, total } = measurePath(path);
     if (total === 0)
         return path;
     const wanted = total * fraction;
@@ -78,14 +49,15 @@ export function trimPath(path, fraction) {
         let cut = false;
         for (let piece = 0; piece < subpath.curves.length; piece++) {
             const curve = subpath.curves[piece];
-            const length = per[at][piece];
+            const measured = per[at][piece];
+            const length = measured.total;
             if (walked + length <= wanted || length === 0) {
                 curves.push(curve);
                 walked += length;
                 from = curve.to;
                 continue;
             }
-            curves.push(splitCubic(from, curve, (wanted - walked) / length));
+            curves.push(splitCubic(from, curve, parameterAt(measured, wanted - walked)));
             cut = true;
             break;
         }

package/dist/index.d.ts

@@ -26,6 +26,8 @@ export { pathFromData } from './figure/path-data.js';
 export type { Colour, Fill, Mark, PathMark, Stroke, TextMark } from './figure/mark.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
 export type { Extent, ExtentChoice, Fit } from './figure/extent.js';
+export { boundsOf, boundsOfMarks, centreOf } from './figure/bounds.js';
+export type { Bounds } from './figure/bounds.js';
 export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
 export type { AreaOptions, BarsOptions, PlotOptions, TangentOptions } from './figure/plot.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
@@ -36,10 +38,11 @@ export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
 export type { Tick } from './figure/ticks.js';
 export { flatten, group, shape, text } from './figure/node.js';
 export type { GroupNode, Node, ShapeNode, Style, TextNode, TextOptions } from './figure/node.js';
-export { fadeIn, fadeOut, fadeTo, draw, morph, moveBy } from './figure/animation.js';
-export type { Animation } from './figure/animation.js';
+export { circumscribe, fadeIn, fadeOut, fadeTo, draw, flash, growFrom, indicate, morph, moveAlong, moveBy, rotate, scale } from './figure/animation.js';
+export type { AboutOptions, Animation, CircumscribeOptions, FlashOptions, IndicateOptions, ScaleOptions } from './figure/animation.js';
 export { Timeline } from './figure/timeline.js';
-export type { PlayOptions, Span } from './figure/timeline.js';
+export type { PlayOptions, Span, StaggerOptions } from './figure/timeline.js';
+export { lengthOf, pointAlong } from './figure/length.js';
 export { trimPath } from './figure/trim.js';
 export { alignPaths, lerpPath } from './figure/morph.js';
 export { at, durationOf, loops, sameMarks } from './figure/figure.js';

package/dist/index.js

@@ -17,13 +17,15 @@ export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from
 export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, straight, transformPath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
+export { boundsOf, boundsOfMarks, centreOf } from './figure/bounds.js';
 export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
 export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
 export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
 export { flatten, group, shape, text } from './figure/node.js';
-export { fadeIn, fadeOut, fadeTo, draw, morph, moveBy } from './figure/animation.js';
+export { circumscribe, fadeIn, fadeOut, fadeTo, draw, flash, growFrom, indicate, morph, moveAlong, moveBy, rotate, scale } from './figure/animation.js';
 export { Timeline } from './figure/timeline.js';
+export { lengthOf, pointAlong } from './figure/length.js';
 export { trimPath } from './figure/trim.js';
 export { alignPaths, lerpPath } from './figure/morph.js';
 export { at, durationOf, loops, sameMarks } from './figure/figure.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altpsyche/maths",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "The mathematics AltPsyche's figures are drawn from: vectors, matrices, curves, and a value walked over time.",
   "license": "MIT",
   "author": "Siva",