@altpsyche/maths 0.2.0

package/dist/figure/trim.js

@@ -0,0 +1,100 @@
+/**
+ * Cutting a path short, which is how a shape is drawn on rather than switched on.
+ *
+ * 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.
+ */
+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;
+/**
+ * A cubic cut at a fraction of its own parameter, keeping the first piece.
+ *
+ * De Casteljau: the same repeated interpolation that evaluates the curve gives
+ * the control points of both halves as it goes.
+ */
+function splitCubic(from, curve, along) {
+    const a = vec2.lerp(from, curve.control1, along);
+    const b = vec2.lerp(curve.control1, curve.control2, along);
+    const c = vec2.lerp(curve.control2, curve.to, along);
+    const d = vec2.lerp(a, b, 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.
+ *
+ * A fraction at or past one is the path itself, untouched, so a finished drawing
+ * is the same geometry the author wrote rather than a rebuilt copy of it. A
+ * subpath the cut has not reached is left out entirely, and the one it lands in
+ * ends with a segment split where the cut falls.
+ */
+export function trimPath(path, fraction) {
+    if (fraction >= 1)
+        return path;
+    if (fraction <= 0)
+        return [];
+    const { per, total } = lengths(path);
+    if (total === 0)
+        return path;
+    const wanted = total * fraction;
+    let walked = 0;
+    const kept = [];
+    for (let at = 0; at < path.length; at++) {
+        const subpath = path[at];
+        const curves = [];
+        let from = subpath.start;
+        let cut = false;
+        for (let piece = 0; piece < subpath.curves.length; piece++) {
+            const curve = subpath.curves[piece];
+            const length = per[at][piece];
+            if (walked + length <= wanted || length === 0) {
+                curves.push(curve);
+                walked += length;
+                from = curve.to;
+                continue;
+            }
+            curves.push(splitCubic(from, curve, (wanted - walked) / length));
+            cut = true;
+            break;
+        }
+        // A subpath cut part way through stops being closed, because the join back
+        // to its start is one of the parts that has not been drawn yet.
+        if (curves.length > 0)
+            kept.push({ start: subpath.start, curves, closed: cut ? false : subpath.closed });
+        if (cut)
+            break;
+    }
+    return kept;
+}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The one door. Nothing outside this package reaches a file inside it by path,
+ * which is the same rule the engine is held to, so a caller can never come to
+ * depend on where a file sits.
+ *
+ * There is a line through this package. Values and timing are below it and
+ * change almost never; figures and painters will sit above it and change often.
+ * Nothing below the line may import anything above it.
+ */
+export { clamp, inverseLerp, lerp, remap } from './values/scalar.js';
+export { curveFor, easeIn, easeOut, linear, smoothstep } from './values/ease.js';
+export type { Curve } from './values/ease.js';
+export { vec2 } from './values/vec2.js';
+export type { Vec2 } from './values/vec2.js';
+export { vec3 } from './values/vec3.js';
+export type { Vec3 } from './values/vec3.js';
+export { mat3 } from './values/mat3.js';
+export type { Mat3 } from './values/mat3.js';
+export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
+export type { Key, Track, TrackValue, Tracks } from './timing/track.js';
+export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, straight, transformPath } from './figure/path.js';
+export type { Cubic, Path, Subpath } from './figure/path.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 { 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 { Timeline } from './figure/timeline.js';
+export type { PlayOptions, Span } from './figure/timeline.js';
+export { trimPath } from './figure/trim.js';
+export { alignPaths, lerpPath } from './figure/morph.js';
+export { at, durationOf, loops, sameMarks } from './figure/figure.js';
+export type { Figure, Values } from './figure/figure.js';
+export { pathData, paintSvg, svgElements, svgMarkup } from './paint/svg.js';
+export type { ElementMaker, PaintNode, PaintTarget, SvgElement } from './paint/svg.js';
+export { paintCanvas } from './paint/canvas.js';
+export type { CanvasLike } from './paint/canvas.js';
+export { arrow, callout, dot } from './figure/annotate.js';
+export type { ArrowOptions, CalloutOptions } from './figure/annotate.js';

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * The one door. Nothing outside this package reaches a file inside it by path,
+ * which is the same rule the engine is held to, so a caller can never come to
+ * depend on where a file sits.
+ *
+ * There is a line through this package. Values and timing are below it and
+ * change almost never; figures and painters will sit above it and change often.
+ * Nothing below the line may import anything above it.
+ */
+export { clamp, inverseLerp, lerp, remap } from './values/scalar.js';
+export { curveFor, easeIn, easeOut, linear, smoothstep } from './values/ease.js';
+export { vec2 } from './values/vec2.js';
+export { vec3 } from './values/vec3.js';
+export { mat3 } from './values/mat3.js';
+export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
+export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, straight, transformPath } from './figure/path.js';
+export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
+export { flatten, group, shape, text } from './figure/node.js';
+export { fadeIn, fadeOut, fadeTo, draw, morph, moveBy } from './figure/animation.js';
+export { Timeline } from './figure/timeline.js';
+export { trimPath } from './figure/trim.js';
+export { alignPaths, lerpPath } from './figure/morph.js';
+export { at, durationOf, loops, sameMarks } from './figure/figure.js';
+export { pathData, paintSvg, svgElements, svgMarkup } from './paint/svg.js';
+export { paintCanvas } from './paint/canvas.js';
+export { arrow, callout, dot } from './figure/annotate.js';

package/dist/paint/canvas.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Marks painted onto a two-dimensional canvas, which is what a recording is.
+ *
+ * An encoder takes one surface, so a recorded frame cannot be the page's SVG. It
+ * is painted again from the same marks rather than rasterised from the page,
+ * which is why a test holds the two painters to emitting the same geometry and
+ * the same style for every mark.
+ *
+ * The view is baked into the coordinates here exactly as it is in the SVG
+ * painter, rather than set on the context. Setting it would flip the text, since
+ * the view turns the y axis over.
+ */
+import { type Mat3 } from '../values/mat3.js';
+import type { Mark } from '../figure/mark.js';
+/**
+ * Only what a painter uses from a canvas context, named here rather than taken
+ * from the DOM types, so this package declares no browser library and a test can
+ * hand in a stand-in. A real `CanvasRenderingContext2D` satisfies it.
+ *
+ * The two style properties are `unknown` because a real context also accepts a
+ * gradient and a pattern there, and a narrower type here would refuse the very
+ * thing this is meant to be handed.
+ */
+export interface CanvasLike {
+    save(): void;
+    restore(): void;
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): void;
+    closePath(): void;
+    fill(rule?: 'nonzero' | 'evenodd'): void;
+    stroke(): void;
+    fillText(text: string, x: number, y: number): void;
+    setLineDash(segments: number[]): void;
+    globalAlpha: number;
+    fillStyle: unknown;
+    strokeStyle: unknown;
+    lineWidth: number;
+    lineCap: 'butt' | 'round' | 'square';
+    lineJoin: 'miter' | 'round' | 'bevel';
+    lineDashOffset: number;
+    font: string;
+    textAlign: 'start' | 'end' | 'left' | 'right' | 'center';
+    textBaseline: 'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom';
+}
+/**
+ * Every mark painted, in order.
+ *
+ * Each one is wrapped in a save and a restore, so a mark that sets an opacity or
+ * a dash cannot leak it into the mark after it. A frame drawn on a context that
+ * has been used before therefore looks the same as one drawn on a fresh context.
+ */
+export declare function paintCanvas(context: CanvasLike, marks: readonly Mark[], view: Mat3): void;

package/dist/paint/canvas.js

@@ -0,0 +1,76 @@
+/**
+ * Marks painted onto a two-dimensional canvas, which is what a recording is.
+ *
+ * An encoder takes one surface, so a recorded frame cannot be the page's SVG. It
+ * is painted again from the same marks rather than rasterised from the page,
+ * which is why a test holds the two painters to emitting the same geometry and
+ * the same style for every mark.
+ *
+ * The view is baked into the coordinates here exactly as it is in the SVG
+ * painter, rather than set on the context. Setting it would flip the text, since
+ * the view turns the y axis over.
+ */
+import { mat3 } from '../values/mat3.js';
+/** SVG says middle where a canvas says center, and the two mean the same place. */
+const ALIGNMENT = { start: 'start', middle: 'center', end: 'end' };
+function tracePath(context, path, view) {
+    context.beginPath();
+    for (const subpath of path) {
+        const start = mat3.transformPoint(view, subpath.start);
+        context.moveTo(start.x, start.y);
+        for (const curve of subpath.curves) {
+            const c1 = mat3.transformPoint(view, curve.control1);
+            const c2 = mat3.transformPoint(view, curve.control2);
+            const to = mat3.transformPoint(view, curve.to);
+            context.bezierCurveTo(c1.x, c1.y, c2.x, c2.y, to.x, to.y);
+        }
+        if (subpath.closed)
+            context.closePath();
+    }
+}
+function paintPath(context, mark, view, scale) {
+    tracePath(context, mark.path, view);
+    if (mark.fill) {
+        context.fillStyle = mark.fill.colour;
+        context.fill(mark.fill.rule ?? 'nonzero');
+    }
+    if (mark.stroke) {
+        context.strokeStyle = mark.stroke.colour;
+        context.lineWidth = mark.stroke.width * scale;
+        context.lineCap = mark.stroke.cap ?? 'butt';
+        context.lineJoin = mark.stroke.join ?? 'miter';
+        // Set every time rather than only when a mark asks for it, because a context
+        // holds the last dash it was given and the next mark would inherit it.
+        context.setLineDash(mark.stroke.dash ? mark.stroke.dash.map((run) => run * scale) : []);
+        context.lineDashOffset = (mark.stroke.dashOffset ?? 0) * scale;
+        context.stroke();
+    }
+}
+function paintText(context, mark, view, scale) {
+    const at = mat3.transformPoint(view, mark.at);
+    const weight = mark.weight === undefined ? '' : `${mark.weight} `;
+    context.font = `${weight}${mark.size * scale}px ${mark.family}`;
+    context.textAlign = ALIGNMENT[mark.align ?? 'start'];
+    context.textBaseline = mark.baseline ?? 'alphabetic';
+    context.fillStyle = mark.fill.colour;
+    context.fillText(mark.text, at.x, at.y);
+}
+/**
+ * Every mark painted, in order.
+ *
+ * Each one is wrapped in a save and a restore, so a mark that sets an opacity or
+ * a dash cannot leak it into the mark after it. A frame drawn on a context that
+ * has been used before therefore looks the same as one drawn on a fresh context.
+ */
+export function paintCanvas(context, marks, view) {
+    const scale = mat3.scaleFactor(view);
+    for (const mark of marks) {
+        context.save();
+        context.globalAlpha = mark.opacity ?? 1;
+        if (mark.kind === 'path')
+            paintPath(context, mark, view, scale);
+        else
+            paintText(context, mark, view, scale);
+        context.restore();
+    }
+}

package/dist/paint/number.d.ts

@@ -0,0 +1 @@
+export declare function short(value: number): string;

package/dist/paint/number.js

@@ -0,0 +1,16 @@
+/**
+ * How a coordinate is written out.
+ *
+ * Rounding is not a nicety here. Both painters have to agree mark for mark, and
+ * two doubles that differ in their last bit would read as a difference where a
+ * reader could never see one. A thousandth of a pixel is finer than anything a
+ * screen or an encoder can hold.
+ */
+const PLACES = 3;
+export function short(value) {
+    // A rounded value that lands on an integer keeps no decimal point, and a
+    // negative zero is written as zero, because otherwise the same coordinate
+    // reached two ways would compare as two strings.
+    const rounded = Number(value.toFixed(PLACES));
+    return Object.is(rounded, -0) ? '0' : String(rounded);
+}

package/dist/paint/svg.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Marks written as SVG, which is what a figure on a page is.
+ *
+ * SVG is the painter for the page and not for a recording, and the reasons are
+ * things this project has already paid for. A screenshot sweep paints its mask
+ * over a whole canvas and is blind inside it, where SVG is in the document and
+ * the sweep reads the real thing. Text is text, so a screen reader gets it. CSS
+ * custom properties reach it, so a figure follows a theme with nothing watching.
+ * And the markup can be written without a browser, so a still frame ships inside
+ * a page before any script runs.
+ *
+ * The view is baked into the coordinates rather than put on a wrapping group. A
+ * group transform would be shorter markup and it flips text: the view turns the
+ * y axis over, and a mirrored transform mirrors the letters with it.
+ */
+import { type Mat3 } from '../values/mat3.js';
+import type { Mark } from '../figure/mark.js';
+import type { Path } from '../figure/path.js';
+/** One element, described rather than built, so the same description can be
+ * written as text or made in a document and the two cannot drift. */
+export interface SvgElement {
+    tag: 'path' | 'text';
+    attributes: Record<string, string>;
+    text?: string;
+}
+/** The `d` attribute: a move to the start, a cubic per segment, and a close
+ * where the subpath joins back. */
+export declare function pathData(path: Path, view: Mat3): string;
+/** Every mark described as an element, in the order they are drawn. */
+export declare function svgElements(marks: readonly Mark[], view: Mat3): SvgElement[];
+/**
+ * A whole `<svg>` as text, for a page that has not run any script yet.
+ *
+ * It carries no width or height of its own and only a view box, so the element
+ * around it decides how big it is and the picture stays where it was put.
+ */
+export declare function svgMarkup(marks: readonly Mark[], view: Mat3, width: number, height: number): string;
+/**
+ * Only what a painter needs from a document, named here rather than taken from
+ * the DOM types.
+ *
+ * A real `SVGElement` and a real `Document` both satisfy these already, and
+ * writing them out means this package declares no browser library at all: it can
+ * be checked and tested without one, and a caller can hand in a stand-in.
+ */
+export interface PaintNode {
+    setAttribute(name: string, value: string): void;
+    textContent: string | null;
+}
+export interface PaintTarget {
+    replaceChildren(...nodes: PaintNode[]): void;
+}
+export interface ElementMaker {
+    createElementNS(namespace: string, tag: string): PaintNode;
+}
+/**
+ * The marks put into an element that is already on the page.
+ *
+ * Every child is replaced rather than matched up and patched. A figure rebuilds
+ * its geometry every frame, so almost every attribute would be rewritten anyway,
+ * and matching them up first would cost more than it saved while adding a way for
+ * two frames to disagree.
+ */
+export declare function paintSvg(into: PaintTarget, marks: readonly Mark[], view: Mat3, maker: ElementMaker): void;

package/dist/paint/svg.js

@@ -0,0 +1,127 @@
+/**
+ * Marks written as SVG, which is what a figure on a page is.
+ *
+ * SVG is the painter for the page and not for a recording, and the reasons are
+ * things this project has already paid for. A screenshot sweep paints its mask
+ * over a whole canvas and is blind inside it, where SVG is in the document and
+ * the sweep reads the real thing. Text is text, so a screen reader gets it. CSS
+ * custom properties reach it, so a figure follows a theme with nothing watching.
+ * And the markup can be written without a browser, so a still frame ships inside
+ * a page before any script runs.
+ *
+ * The view is baked into the coordinates rather than put on a wrapping group. A
+ * group transform would be shorter markup and it flips text: the view turns the
+ * y axis over, and a mirrored transform mirrors the letters with it.
+ */
+import { mat3 } from '../values/mat3.js';
+import { short } from './number.js';
+/** The `d` attribute: a move to the start, a cubic per segment, and a close
+ * where the subpath joins back. */
+export function pathData(path, view) {
+    const parts = [];
+    for (const subpath of path) {
+        const start = mat3.transformPoint(view, subpath.start);
+        parts.push(`M${short(start.x)} ${short(start.y)}`);
+        for (const curve of subpath.curves) {
+            const c1 = mat3.transformPoint(view, curve.control1);
+            const c2 = mat3.transformPoint(view, curve.control2);
+            const to = mat3.transformPoint(view, curve.to);
+            parts.push(`C${short(c1.x)} ${short(c1.y)} ${short(c2.x)} ${short(c2.y)} ${short(to.x)} ${short(to.y)}`);
+        }
+        if (subpath.closed)
+            parts.push('Z');
+    }
+    return parts.join('');
+}
+function pathElement(mark, view, scale) {
+    const attributes = {
+        'data-mark': mark.id,
+        d: pathData(mark.path, view),
+        fill: mark.fill ? mark.fill.colour : 'none',
+    };
+    if (mark.fill?.rule === 'evenodd')
+        attributes['fill-rule'] = 'evenodd';
+    if (mark.stroke) {
+        attributes.stroke = mark.stroke.colour;
+        attributes['stroke-width'] = short(mark.stroke.width * scale);
+        if (mark.stroke.cap)
+            attributes['stroke-linecap'] = mark.stroke.cap;
+        if (mark.stroke.join)
+            attributes['stroke-linejoin'] = mark.stroke.join;
+        if (mark.stroke.dash)
+            attributes['stroke-dasharray'] = mark.stroke.dash.map((run) => short(run * scale)).join(' ');
+        if (mark.stroke.dashOffset !== undefined)
+            attributes['stroke-dashoffset'] = short(mark.stroke.dashOffset * scale);
+    }
+    if (mark.opacity !== undefined && mark.opacity !== 1)
+        attributes.opacity = short(mark.opacity);
+    return { tag: 'path', attributes };
+}
+function textElement(mark, view, scale) {
+    const at = mat3.transformPoint(view, mark.at);
+    const attributes = {
+        'data-mark': mark.id,
+        x: short(at.x),
+        y: short(at.y),
+        'font-family': mark.family,
+        'font-size': short(mark.size * scale),
+        fill: mark.fill.colour,
+    };
+    if (mark.weight !== undefined)
+        attributes['font-weight'] = String(mark.weight);
+    if (mark.align)
+        attributes['text-anchor'] = mark.align;
+    if (mark.baseline)
+        attributes['dominant-baseline'] = mark.baseline;
+    if (mark.opacity !== undefined && mark.opacity !== 1)
+        attributes.opacity = short(mark.opacity);
+    return { tag: 'text', attributes, text: mark.text };
+}
+/** Every mark described as an element, in the order they are drawn. */
+export function svgElements(marks, view) {
+    const scale = mat3.scaleFactor(view);
+    return marks.map((mark) => (mark.kind === 'path' ? pathElement(mark, view, scale) : textElement(mark, view, scale)));
+}
+/** The five characters that would otherwise close a tag or open an entity. */
+function escaped(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/**
+ * A whole `<svg>` as text, for a page that has not run any script yet.
+ *
+ * It carries no width or height of its own and only a view box, so the element
+ * around it decides how big it is and the picture stays where it was put.
+ */
+export function svgMarkup(marks, view, width, height) {
+    const body = svgElements(marks, view)
+        .map((element) => {
+        const attributes = Object.entries(element.attributes)
+            .map(([name, value]) => `${name}="${escaped(value)}"`)
+            .join(' ');
+        if (element.text === undefined)
+            return `<${element.tag} ${attributes}/>`;
+        return `<${element.tag} ${attributes}>${escaped(element.text)}</${element.tag}>`;
+    })
+        .join('');
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${short(width)} ${short(height)}">${body}</svg>`;
+}
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+/**
+ * The marks put into an element that is already on the page.
+ *
+ * Every child is replaced rather than matched up and patched. A figure rebuilds
+ * its geometry every frame, so almost every attribute would be rewritten anyway,
+ * and matching them up first would cost more than it saved while adding a way for
+ * two frames to disagree.
+ */
+export function paintSvg(into, marks, view, maker) {
+    const elements = svgElements(marks, view);
+    into.replaceChildren(...elements.map((element) => {
+        const node = maker.createElementNS(SVG_NAMESPACE, element.tag);
+        for (const [name, value] of Object.entries(element.attributes))
+            node.setAttribute(name, value);
+        if (element.text !== undefined)
+            node.textContent = element.text;
+        return node;
+    }));
+}

package/dist/timing/track.d.ts

@@ -0,0 +1,37 @@
+/** What a key can hold. A boolean is here because a control can be a switch,
+ * and a list because a control can be a vector or a colour. */
+export type TrackValue = number | readonly number[] | boolean;
+export interface Key {
+    /** Seconds into the clip. A key past the clip's end is never reached. */
+    time: number;
+    value: TrackValue;
+    /** Whether the curve is flat here, which eases the segments either side. */
+    smooth?: boolean;
+}
+/** One value's keys, in the order the sampler reads them, which is the order
+ * `withKey` keeps them in. */
+export type Track = readonly Key[];
+/** Every track by name, which is whatever the caller keys: a uniform, or a
+ * property of a mark. */
+export type Tracks = Record<string, Track>;
+/** Two keys at the same instant are one key, so a time this close counts as the
+ * same time and setting a key twice replaces rather than stacks. Half a frame at
+ * sixty a second. */
+export declare const SAME_TIME: number;
+/**
+ * What a track is worth at a time, or null where it has no keys.
+ *
+ * Outside the keys the nearest one holds, so a track never invents a value
+ * before its first key or carries on past its last.
+ */
+export declare function sampleTrack(track: Track, seconds: number): TrackValue | null;
+/** Every track's value at a time, leaving out a track with no keys. */
+export declare function sampleTracks(tracks: Tracks, seconds: number): Record<string, TrackValue>;
+/** The track with one key set, replacing the key at that time where there is
+ * one, and in the order the sampler reads. */
+export declare function withKey(track: Track, key: Key): Track;
+/** The track with the key at that time taken out. */
+export declare function withoutKey(track: Track, seconds: number): Track;
+/** The key sitting at a time, which is what a control reads to draw its button
+ * as set rather than empty. */
+export declare function keyAt(track: Track, seconds: number): Key | undefined;

package/dist/timing/track.js

@@ -0,0 +1,85 @@
+/**
+ * A value over the length of a clip, read at a time.
+ *
+ * Something sets a value at one moment and another value later, and everything
+ * that draws asks this file what the value is at a given second. A picture on
+ * screen and a picture being recorded used to be two answers to that question in
+ * two places, which is how a preview and a recording drift apart.
+ *
+ * A key is flat where it is marked smooth, so two keys give four curves. That is
+ * the whole of the shape, and the rest of this file is holding the keys in the
+ * order the sampler reads them.
+ */
+import { curveFor } from '../values/ease.js';
+/** Two keys at the same instant are one key, so a time this close counts as the
+ * same time and setting a key twice replaces rather than stacks. Half a frame at
+ * sixty a second. */
+export const SAME_TIME = 1 / 120;
+/**
+ * The value part way between two keys.
+ *
+ * A pair this cannot walk between holds the earlier value until the later key's
+ * own time: a boolean has no half, and two lists of different lengths have no
+ * component to pair up.
+ */
+function walked(from, to, along) {
+    if (typeof from === 'number' && typeof to === 'number')
+        return from + (to - from) * along;
+    if (Array.isArray(from) && Array.isArray(to) && from.length === to.length) {
+        return from.map((part, at) => part + (to[at] - part) * along);
+    }
+    return from;
+}
+/**
+ * What a track is worth at a time, or null where it has no keys.
+ *
+ * Outside the keys the nearest one holds, so a track never invents a value
+ * before its first key or carries on past its last.
+ */
+export function sampleTrack(track, seconds) {
+    if (track.length === 0)
+        return null;
+    const first = track[0];
+    if (seconds <= first.time)
+        return first.value;
+    const last = track[track.length - 1];
+    if (seconds >= last.time)
+        return last.value;
+    for (let at = 0; at < track.length - 1; at++) {
+        const from = track[at];
+        const to = track[at + 1];
+        if (seconds > to.time)
+            continue;
+        const span = to.time - from.time;
+        if (span <= 0)
+            return to.value;
+        const along = curveFor(from.smooth === true, to.smooth === true)((seconds - from.time) / span);
+        return walked(from.value, to.value, along);
+    }
+    return last.value;
+}
+/** Every track's value at a time, leaving out a track with no keys. */
+export function sampleTracks(tracks, seconds) {
+    const values = {};
+    for (const [name, track] of Object.entries(tracks)) {
+        const value = sampleTrack(track, seconds);
+        if (value !== null)
+            values[name] = value;
+    }
+    return values;
+}
+/** The track with one key set, replacing the key at that time where there is
+ * one, and in the order the sampler reads. */
+export function withKey(track, key) {
+    const kept = track.filter((held) => Math.abs(held.time - key.time) > SAME_TIME);
+    return [...kept, key].sort((one, two) => one.time - two.time);
+}
+/** The track with the key at that time taken out. */
+export function withoutKey(track, seconds) {
+    return track.filter((held) => Math.abs(held.time - seconds) > SAME_TIME);
+}
+/** The key sitting at a time, which is what a control reads to draw its button
+ * as set rather than empty. */
+export function keyAt(track, seconds) {
+    return track.find((held) => Math.abs(held.time - seconds) <= SAME_TIME);
+}

package/dist/values/ease.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The four curves a value can travel along between two moments.
+ *
+ * They are the whole of the shape a track can hold. A key is either flat where
+ * it sits or it is not, and two keys give four pairings: straight through,
+ * still at the start, still at the end, and still at both.
+ *
+ * Every one of them takes and returns zero to one, so a caller decides what the
+ * value at each end is and this decides only the pace between them.
+ */
+/** A curve maps how far through a span the clock is onto how far through the
+ * change the value is. */
+export type Curve = (along: number) => number;
+/** No easing at all: the value moves at one rate the whole way. */
+export declare const linear: Curve;
+/** Quadratic ease in: flat at the start, so the value leaves from rest and
+ * arrives at speed. */
+export declare const easeIn: Curve;
+/** Quadratic ease out: flat at the end, so the value leaves at speed and
+ * settles rather than stopping dead. */
+export declare const easeOut: Curve;
+/** Smoothstep: the cubic that is flat at both ends, Ken Perlin. */
+export declare const smoothstep: Curve;
+/**
+ * The curve for a span whose ends are flat or not.
+ *
+ * This is the only place the four are chosen between, so a track and a figure's
+ * timeline pace a change the same way rather than each deciding for itself.
+ */
+export declare function curveFor(fromFlat: boolean, toFlat: boolean): Curve;