@altpsyche/maths 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @altpsyche/maths
+
+The mathematics the figures on [altpsyche.dev](https://altpsyche.dev) are drawn from.
+
+A **figure** is a picture that moves and explains itself. Asking one for a time gives back a
+flat list of **marks**, and a **painter** turns marks into something a reader can see.
+
+```ts
+import { Timeline, at, circle, draw, group, shape, svgMarkup, vec2, viewMatrix } from '@altpsyche/maths';
+
+const figure = {
+  extent: { width: 16, height: 9 },
+  still: 1,
+  scene: group('fig', [shape('ring', circle(vec2(0, 0), 3), { stroke: { colour: '#fff', width: 0.05 } })]),
+  timeline: Timeline.empty().play(draw('fig/ring'), 1),
+};
+
+svgMarkup(at(figure, 0.5), viewMatrix(figure.extent, 'contain', 640, 360), 640, 360);
+```
+
+## What it is built on
+
+**A figure at a time is data.** `at(figure, seconds)` is the whole public surface, and it is a
+pure function: ask for four seconds and it gives the picture at four seconds whatever it gave
+before. A page playing forward, a reader dragging a scrub bar backwards and a recorder walking
+a fixed step are three consumers of one answer.
+
+**Everything is a cubic**, a straight line included. That is what lets one shape be walked into
+another point by point, with no case where a line has to become an arc.
+
+**A mark may only ask for what both painters can do**, rather than the union of them. There are
+no filters, no blend modes, no clipping and no gradients, because a figure reaching for
+something only SVG has would look right on a page and lose it without a word in a recording.
+
+**A figure never reads the page.** Colours arrive as a palette the caller hands in.
+
+## The two painters
+
+`svgMarkup` and `paintSvg` write SVG, which is what a figure on a page is: the text is text, CSS
+reaches it, and the markup can be written with no browser at all. `paintCanvas` paints the same
+marks onto a two-dimensional canvas, which is what a recording needs, because an encoder takes
+one surface. A test holds the two to emitting the same geometry and the same style for every
+mark.
+
+## The line through the package
+
+**Values and timing** are below it: vectors, a transform, the four curves a change can travel
+along, and a value walked between keys. That half changes almost never. **Figures and painters**
+are above it. Nothing below the line imports anything above it, and a test says so.
+
+One door, no runtime dependencies. MIT.

package/dist/figure/animation.d.ts

@@ -0,0 +1,29 @@
+import { type Vec2 } from '../values/vec2.js';
+import { type Path } from './path.js';
+import type { Mark } 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. */
+export declare function fadeIn(target: string): Animation;
+export declare function fadeOut(target: string): Animation;
+/** Moved by an offset in figure units, which reaches the geometry rather than
+ * riding alongside it, the same way a group's transform does. */
+export declare function moveBy(target: string, offset: Vec2): Animation;
+/**
+ * Drawn on from one end rather than switched on.
+ *
+ * A text mark has no path to walk along, so it fades instead. That is a choice
+ * rather than an oversight: drawing letters on stroke by stroke needs outlines,
+ * and a text mark is deliberately a string a painter lays out.
+ */
+export declare function draw(target: string): Animation;
+/**
+ * One shape becoming another, point by point.
+ *
+ * The two paths are aligned first, so the one with fewer segments is subdivided
+ * until both hold the same points. A mark with no path is left alone.
+ */
+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;

package/dist/figure/animation.js

@@ -0,0 +1,82 @@
+/**
+ * A change to some of the marks, over a span of time.
+ *
+ * An animation is a function rather than an object with a start and a stop,
+ * because the picture at a time has to be the same whichever direction the clock
+ * arrived from. Playing forward, dragging a scrub bar backwards and walking a
+ * fixed step for a recording all ask the same question and must get the same
+ * answer.
+ *
+ * Each one is given how far through its own span the clock is, already eased, and
+ * hands back the marks as they stand at that fraction.
+ */
+import { mat3 } from '../values/mat3.js';
+import { vec2 } from '../values/vec2.js';
+import { lerp } from '../values/scalar.js';
+import { transformPath } from './path.js';
+import { trimPath } from './trim.js';
+import { lerpPath } from './morph.js';
+/**
+ * Which marks an animation touches.
+ *
+ * A target is an id or the front of one, so naming a group reaches everything
+ * inside it and naming a mark reaches only that mark. A name that matches
+ * nothing changes nothing rather than failing, because a figure being written is
+ * often a figure whose parts do not all exist yet.
+ */
+function touches(id, target) {
+    return id === target || id.startsWith(`${target}/`);
+}
+function over(target, change) {
+    return (marks, along) => marks.map((mark) => (touches(mark.id, target) ? change(mark, along) : 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. */
+export function fadeIn(target) {
+    return over(target, (mark, along) => ({ ...mark, opacity: (mark.opacity ?? 1) * along }));
+}
+export function fadeOut(target) {
+    return over(target, (mark, along) => ({ ...mark, opacity: (mark.opacity ?? 1) * (1 - along) }));
+}
+/** Moved by an offset in figure units, which reaches the geometry rather than
+ * riding alongside it, the same way a group's transform does. */
+export function moveBy(target, offset) {
+    return over(target, (mark, along) => {
+        const step = mat3.translation(vec2.scale(offset, along));
+        if (mark.kind === 'text')
+            return { ...mark, at: mat3.transformPoint(step, mark.at) };
+        return { ...mark, path: transformPath(mark.path, step) };
+    });
+}
+/**
+ * Drawn on from one end rather than switched on.
+ *
+ * A text mark has no path to walk along, so it fades instead. That is a choice
+ * rather than an oversight: drawing letters on stroke by stroke needs outlines,
+ * and a text mark is deliberately a string a painter lays out.
+ */
+export function draw(target) {
+    return over(target, (mark, along) => {
+        if (mark.kind === 'text')
+            return { ...mark, opacity: (mark.opacity ?? 1) * along };
+        return { ...mark, path: trimPath(mark.path, along) };
+    });
+}
+/**
+ * One shape becoming another, point by point.
+ *
+ * The two paths are aligned first, so the one with fewer segments is subdivided
+ * until both hold the same points. A mark with no path is left alone.
+ */
+export function morph(target, into) {
+    return over(target, (mark, along) => {
+        if (mark.kind === 'text')
+            return mark;
+        return { ...mark, path: lerpPath(mark.path, into, along) };
+    });
+}
+/** A mark's own opacity walked to a value, for a figure that wants a thing dimmed
+ * rather than gone. */
+export function fadeTo(target, opacity) {
+    return over(target, (mark, along) => ({ ...mark, opacity: lerp(mark.opacity ?? 1, opacity, along) }));
+}

package/dist/figure/annotate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The shapes an annotation is made of, composed from marks rather than being
+ * marks of their own.
+ *
+ * Each one hands back a group, so an arrow is a shaft and a head with ids of
+ * their own and an animation naming the arrow reaches both. Making an arrow a
+ * single mark instead would mean one path that is stroked along its shaft and
+ * filled at its head, and no mark can be both.
+ */
+import { type Vec2 } from '../values/vec2.js';
+import { type GroupNode, type TextOptions } from './node.js';
+import type { Fill, Stroke } from './mark.js';
+export interface ArrowOptions {
+    stroke: Stroke;
+    /** Filled with the shaft's own colour unless a figure asks for another. */
+    fill?: Fill;
+    /**
+     * How long the head is, in figure units. Four times the shaft's width by
+     * default, which keeps a head in proportion to its line at any size, since
+     * both are in figure units and scale together.
+     */
+    head?: number;
+    /** How wide the head is across its base, against its length. */
+    spread?: number;
+}
+/**
+ * A line with a head at the far end.
+ *
+ * The shaft stops where the head begins rather than running under it, because a
+ * shaft drawn to the point shows through a head that is not fully opaque.
+ */
+export declare function arrow(name: string, from: Vec2, to: Vec2, options: ArrowOptions): GroupNode;
+/** A filled disc, which is what marks a place a line is pointing at. */
+export declare function dot(name: string, at: Vec2, radius: number, fill: Fill): GroupNode;
+export interface CalloutOptions {
+    stroke: Stroke;
+    fill: Fill;
+    size: number;
+    /** The disc left on the thing being named. Nothing is drawn where this is zero,
+     * which is what a callout pointing at a moving thing wants. */
+    marker?: number;
+    align?: TextOptions['align'];
+    baseline?: TextOptions['baseline'];
+    family?: string;
+    weight?: number;
+}
+/**
+ * A word attached to a place: a disc on the place, a line out to where there is
+ * room, and the word at the end of it.
+ *
+ * This is the annotation a figure over a shader is made of. The words sit away
+ * from what they name because a label on top of the picture hides the thing the
+ * reader was told to look at.
+ */
+export declare function callout(name: string, at: Vec2, to: Vec2, content: string, options: CalloutOptions): GroupNode;

package/dist/figure/annotate.js

@@ -0,0 +1,53 @@
+/**
+ * The shapes an annotation is made of, composed from marks rather than being
+ * marks of their own.
+ *
+ * Each one hands back a group, so an arrow is a shaft and a head with ids of
+ * their own and an animation naming the arrow reaches both. Making an arrow a
+ * single mark instead would mean one path that is stroked along its shaft and
+ * filled at its head, and no mark can be both.
+ */
+import { vec2 } from '../values/vec2.js';
+import { circle, line, polygon } from './path.js';
+import { group, shape, text } from './node.js';
+/**
+ * A line with a head at the far end.
+ *
+ * The shaft stops where the head begins rather than running under it, because a
+ * shaft drawn to the point shows through a head that is not fully opaque.
+ */
+export function arrow(name, from, to, options) {
+    const head = options.head ?? options.stroke.width * 4;
+    const spread = options.spread ?? 0.6;
+    const along = vec2.normalize(vec2.sub(to, from));
+    const base = vec2.sub(to, vec2.scale(along, head));
+    const across = vec2.scale(vec2.perpendicular(along), (head * spread) / 2);
+    const fill = options.fill ?? { colour: options.stroke.colour };
+    return group(name, [
+        shape('shaft', line(from, base), { stroke: options.stroke }),
+        shape('head', polygon([to, vec2.add(base, across), vec2.sub(base, across)]), { fill }),
+    ]);
+}
+/** A filled disc, which is what marks a place a line is pointing at. */
+export function dot(name, at, radius, fill) {
+    return group(name, [shape('disc', circle(at, radius), { fill })]);
+}
+/**
+ * A word attached to a place: a disc on the place, a line out to where there is
+ * room, and the word at the end of it.
+ *
+ * This is the annotation a figure over a shader is made of. The words sit away
+ * from what they name because a label on top of the picture hides the thing the
+ * reader was told to look at.
+ */
+export function callout(name, at, to, content, options) {
+    const marker = options.marker ?? options.stroke.width * 2;
+    const style = { fill: options.fill, family: options.family, weight: options.weight };
+    const parts = [
+        shape('leader', line(at, to), { stroke: options.stroke }),
+        text('word', to, content, options.size, { ...style, align: options.align, baseline: options.baseline }),
+    ];
+    if (marker > 0)
+        parts.unshift(shape('marker', circle(at, marker), { fill: options.fill }));
+    return group(name, parts);
+}

package/dist/figure/extent.d.ts

@@ -0,0 +1,62 @@
+/**
+ * How much of the world a figure shows, and how that lands on a surface.
+ *
+ * A figure is measured in its own units and never in pixels, so one figure draws
+ * at 640 across in a chapter and at 2160 by 3840 in a recording with no second
+ * version of the picture and no coordinates rewritten.
+ */
+import { type Mat3 } from '../values/mat3.js';
+import { type Vec2 } from '../values/vec2.js';
+export interface Extent {
+    width: number;
+    height: number;
+}
+/** Whether the extent is held inside the surface, leaving margins where the
+ * shapes differ, or fills it and runs off two edges. */
+export type Fit = 'contain' | 'cover';
+/** An extent that never changes, or one chosen from the shape of the surface it
+ * is about to be drawn on. */
+export type ExtentChoice = Extent | ((aspect: number) => Extent);
+export declare function resolveExtent(choice: ExtentChoice, aspect: number): Extent;
+/**
+ * An extent per shape, for a figure whose composition does not survive being
+ * reframed.
+ *
+ * A wide composition put in a square frame is a different picture rather than a
+ * cropped one, which is why this chooses an extent rather than cutting a wide
+ * frame down. The two thresholds sit between the three shapes anything here is
+ * drawn at, which are sixteen by nine at 1.78, square at 1, and nine by sixteen
+ * at 0.5625.
+ */
+export declare function byAspect(shapes: {
+    wide: Extent;
+    square: Extent;
+    tall: Extent;
+}): (aspect: number) => Extent;
+/**
+ * An extent that follows the shape of whatever it is drawn on.
+ *
+ * This is what a figure drawn over something else uses. The height is fixed and
+ * the width follows the surface, so `contain` fits it exactly and there are no
+ * margins at any shape: a figure over a shader covers the shader, at sixteen by
+ * nine and at nine by sixteen alike.
+ */
+export declare function matchingAspect(height?: number): (aspect: number) => Extent;
+/**
+ * A point given as a fraction of the frame rather than in figure units, with
+ * nothing at the bottom left and one at the top right.
+ *
+ * A mark placed this way is in screen space. That is the only placement that is
+ * safe over a shader, because putting a mark at a place inside the scene a shader
+ * is drawing would need the shader's camera, and nothing can read one.
+ */
+export declare function fractionOf(extent: Extent, across: number, up: number): Vec2;
+/**
+ * The one matrix taking figure units onto a surface, with the extent centred.
+ *
+ * The y axis is flipped, because a figure counts upward the way a graph does and
+ * both painters count downward from the top of the surface. Doing it here rather
+ * than in each painter is what keeps the two from disagreeing about which way up
+ * a picture is.
+ */
+export declare function viewMatrix(extent: Extent, fit: Fit, surfaceWidth: number, surfaceHeight: number): Mat3;

package/dist/figure/extent.js

@@ -0,0 +1,69 @@
+/**
+ * How much of the world a figure shows, and how that lands on a surface.
+ *
+ * A figure is measured in its own units and never in pixels, so one figure draws
+ * at 640 across in a chapter and at 2160 by 3840 in a recording with no second
+ * version of the picture and no coordinates rewritten.
+ */
+import { mat3 } from '../values/mat3.js';
+import { vec2 } from '../values/vec2.js';
+export function resolveExtent(choice, aspect) {
+    return typeof choice === 'function' ? choice(aspect) : choice;
+}
+/**
+ * An extent per shape, for a figure whose composition does not survive being
+ * reframed.
+ *
+ * A wide composition put in a square frame is a different picture rather than a
+ * cropped one, which is why this chooses an extent rather than cutting a wide
+ * frame down. The two thresholds sit between the three shapes anything here is
+ * drawn at, which are sixteen by nine at 1.78, square at 1, and nine by sixteen
+ * at 0.5625.
+ */
+export function byAspect(shapes) {
+    return (aspect) => {
+        if (aspect > 1.15)
+            return shapes.wide;
+        if (aspect < 0.87)
+            return shapes.tall;
+        return shapes.square;
+    };
+}
+/**
+ * An extent that follows the shape of whatever it is drawn on.
+ *
+ * This is what a figure drawn over something else uses. The height is fixed and
+ * the width follows the surface, so `contain` fits it exactly and there are no
+ * margins at any shape: a figure over a shader covers the shader, at sixteen by
+ * nine and at nine by sixteen alike.
+ */
+export function matchingAspect(height = 2) {
+    return (aspect) => ({ width: height * aspect, height });
+}
+/**
+ * A point given as a fraction of the frame rather than in figure units, with
+ * nothing at the bottom left and one at the top right.
+ *
+ * A mark placed this way is in screen space. That is the only placement that is
+ * safe over a shader, because putting a mark at a place inside the scene a shader
+ * is drawing would need the shader's camera, and nothing can read one.
+ */
+export function fractionOf(extent, across, up) {
+    return vec2((across - 0.5) * extent.width, (up - 0.5) * extent.height);
+}
+/**
+ * The one matrix taking figure units onto a surface, with the extent centred.
+ *
+ * The y axis is flipped, because a figure counts upward the way a graph does and
+ * both painters count downward from the top of the surface. Doing it here rather
+ * than in each painter is what keeps the two from disagreeing about which way up
+ * a picture is.
+ */
+export function viewMatrix(extent, fit, surfaceWidth, surfaceHeight) {
+    const byWidth = surfaceWidth / extent.width;
+    const byHeight = surfaceHeight / extent.height;
+    const scale = fit === 'cover' ? Math.max(byWidth, byHeight) : Math.min(byWidth, byHeight);
+    const centre = mat3.translation(vec2(surfaceWidth / 2, surfaceHeight / 2));
+    const flip = mat3.scaling(vec2(scale, -scale));
+    return mat3.multiply(centre, flip);
+}

package/dist/figure/figure.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A picture over time, and the one call that reads it.
+ *
+ * `at` is the whole public surface of a figure. Ask it for four seconds and it
+ * gives the picture at four seconds, whatever it gave before, so a page playing
+ * forward, a reader dragging a scrub bar backwards and a recorder walking a fixed
+ * step are three consumers of one answer rather than three implementations of it.
+ *
+ * Nothing here touches a screen. What comes back is a list of marks in the
+ * figure's own units, and a painter decides what to do with them.
+ */
+import { type TrackValue, type Tracks } from '../timing/track.js';
+import { type Node } from './node.js';
+import { Timeline } from './timeline.js';
+import type { ExtentChoice, Fit } from './extent.js';
+import type { Mark } from './mark.js';
+/** The values a scene is rebuilt from, sampled out of the figure's tracks. This
+ * is what lets geometry follow a number rather than only be moved about: a
+ * radius that is keyed makes a circle that is genuinely a different circle each
+ * frame. */
+export type Values = Record<string, TrackValue>;
+export interface Figure {
+    /** How much of the world the figure shows, in its own units. */
+    extent: ExtentChoice;
+    fit?: Fit;
+    /** The tree, either fixed or rebuilt from the clock and the sampled values. */
+    scene: Node | ((seconds: number, values: Values) => Node);
+    tracks?: Tracks;
+    timeline?: Timeline;
+    /** Overrides the timeline's own length, for a figure that should hold after
+     * its last animation finishes. */
+    duration?: number;
+    /**
+     * The one time a reader who asked for reduced motion is shown.
+     *
+     * Every figure names it, because the last frame is not always the one that
+     * explains the most and a figure stopped at zero often explains nothing.
+     */
+    still: number;
+    /** A figure that ends where it began, which a recording can loop without a
+     * jump. Held by a test rather than taken on trust. */
+    loop?: boolean;
+}
+export declare function durationOf(figure: Figure): number;
+/** The marks a figure shows at a time. */
+export declare function at(figure: Figure, seconds: number): readonly Mark[];
+/** Whether a figure declaring itself a loop actually is one, which is the gate
+ * behind that flag. The comparison is by tolerance rather than exactly, because
+ * the sine and cosine a figure is built from are not specified to the last bit
+ * and differ between engines. */
+export declare function loops(figure: Figure, tolerance?: number): boolean;
+/** Two lists holding the same marks in the same order, to a tolerance. */
+export declare function sameMarks(one: readonly Mark[], two: readonly Mark[], tolerance?: number): boolean;

package/dist/figure/figure.js

@@ -0,0 +1,75 @@
+/**
+ * A picture over time, and the one call that reads it.
+ *
+ * `at` is the whole public surface of a figure. Ask it for four seconds and it
+ * gives the picture at four seconds, whatever it gave before, so a page playing
+ * forward, a reader dragging a scrub bar backwards and a recorder walking a fixed
+ * step are three consumers of one answer rather than three implementations of it.
+ *
+ * Nothing here touches a screen. What comes back is a list of marks in the
+ * figure's own units, and a painter decides what to do with them.
+ */
+import { sampleTracks } from '../timing/track.js';
+import { flatten } from './node.js';
+export function durationOf(figure) {
+    return figure.duration ?? figure.timeline?.duration ?? 0;
+}
+/** The marks a figure shows at a time. */
+export function at(figure, seconds) {
+    const values = figure.tracks ? sampleTracks(figure.tracks, seconds) : {};
+    const tree = typeof figure.scene === 'function' ? figure.scene(seconds, values) : figure.scene;
+    const marks = flatten(tree);
+    return figure.timeline ? figure.timeline.at(marks, seconds) : marks;
+}
+/** Whether a figure declaring itself a loop actually is one, which is the gate
+ * behind that flag. The comparison is by tolerance rather than exactly, because
+ * the sine and cosine a figure is built from are not specified to the last bit
+ * and differ between engines. */
+export function loops(figure, tolerance = 1e-6) {
+    const start = at(figure, 0);
+    const end = at(figure, durationOf(figure));
+    return sameMarks(start, end, tolerance);
+}
+/** Two lists holding the same marks in the same order, to a tolerance. */
+export function sameMarks(one, two, tolerance = 1e-6) {
+    if (one.length !== two.length)
+        return false;
+    return one.every((mark, at) => sameMark(mark, two[at], tolerance));
+}
+function close(a, b, tolerance) {
+    return Math.abs((a ?? 1) - (b ?? 1)) <= tolerance;
+}
+function sameMark(one, two, tolerance) {
+    if (one.kind !== two.kind || one.id !== two.id)
+        return false;
+    if (!close(one.opacity, two.opacity, tolerance))
+        return false;
+    if (one.kind === 'text' && two.kind === 'text') {
+        return (one.text === two.text &&
+            Math.abs(one.at.x - two.at.x) <= tolerance &&
+            Math.abs(one.at.y - two.at.y) <= tolerance &&
+            Math.abs(one.size - two.size) <= tolerance);
+    }
+    if (one.kind !== 'path' || two.kind !== 'path')
+        return false;
+    if (one.path.length !== two.path.length)
+        return false;
+    return one.path.every((subpath, index) => {
+        const other = two.path[index];
+        if (subpath.curves.length !== other.curves.length)
+            return false;
+        if (Math.abs(subpath.start.x - other.start.x) > tolerance)
+            return false;
+        if (Math.abs(subpath.start.y - other.start.y) > tolerance)
+            return false;
+        return subpath.curves.every((curve, piece) => {
+            const twin = other.curves[piece];
+            return (Math.abs(curve.control1.x - twin.control1.x) <= tolerance &&
+                Math.abs(curve.control1.y - twin.control1.y) <= tolerance &&
+                Math.abs(curve.control2.x - twin.control2.x) <= tolerance &&
+                Math.abs(curve.control2.y - twin.control2.y) <= tolerance &&
+                Math.abs(curve.to.x - twin.to.x) <= tolerance &&
+                Math.abs(curve.to.y - twin.to.y) <= tolerance);
+        });
+    });
+}

package/dist/figure/mark.d.ts

@@ -0,0 +1,66 @@
+/**
+ * One drawn item, resolved: its geometry is in the figure's own units with every
+ * transform already applied, and its style is settled rather than inherited.
+ *
+ * What a mark may ask for is the intersection of what an SVG element and a
+ * two-dimensional canvas can both do, rather than the union. A figure reaching
+ * for something only one of them has would look right on the page and lose it
+ * without a word in a recording, which is the worst way to find out. So there
+ * are no filters, no blend modes, no clipping and no gradients here, and adding
+ * one means adding it to both painters in the same change.
+ */
+import type { Vec2 } from '../values/vec2.js';
+import type { Path } from './path.js';
+/** A colour either painter accepts, which is any CSS colour written as text. A
+ * figure is handed these in a palette rather than reading them from a page. */
+export type Colour = string;
+export interface Stroke {
+    colour: Colour;
+    /** In figure units, scaled with everything else, so a line reads the same
+     * weight at every size the figure is drawn at. */
+    width: number;
+    cap?: 'butt' | 'round' | 'square';
+    join?: 'miter' | 'round' | 'bevel';
+    /** Lengths of the drawn and undrawn runs, in figure units. */
+    dash?: readonly number[];
+    dashOffset?: number;
+}
+export interface Fill {
+    colour: Colour;
+    /** How a shape that crosses itself decides what is inside. Both painters
+     * carry both answers under different names. */
+    rule?: 'nonzero' | 'evenodd';
+}
+interface Common {
+    /**
+     * Stable across frames, and built from the names on the way down the tree.
+     *
+     * Hit testing reads the flat list rather than walking the tree again, and
+     * comparing one frame against another needs to know which mark is which, so
+     * an id that changed between frames would make both impossible.
+     */
+    id: string;
+    opacity?: number;
+}
+export interface PathMark extends Common {
+    kind: 'path';
+    path: Path;
+    fill?: Fill;
+    stroke?: Stroke;
+}
+export interface TextMark extends Common {
+    kind: 'text';
+    at: Vec2;
+    text: string;
+    /** In figure units, like a stroke width. */
+    size: number;
+    family: string;
+    weight?: number;
+    /** Which end of the text sits at the anchor point. */
+    align?: 'start' | 'middle' | 'end';
+    /** Where the anchor point sits against the line of text. */
+    baseline?: 'alphabetic' | 'middle' | 'hanging';
+    fill: Fill;
+}
+export type Mark = PathMark | TextMark;
+export {};

package/dist/figure/mark.js

@@ -0,0 +1 @@
+export {};

package/dist/figure/morph.d.ts

@@ -0,0 +1,6 @@
+import type { Path } from './path.js';
+/** The two paths rewritten to the same shape of point list, drawing exactly what
+ * they drew before. */
+export declare function alignPaths(from: Path, to: Path): [Path, Path];
+/** Part way from one path to another, point by point, after aligning them. */
+export declare function lerpPath(from: Path, to: Path, along: number): Path;