@delacour/react-native-charts 0.1.0-alpha.20260925053522

package/src/cartesian/marks/chart-candlestick.tsx

@@ -0,0 +1,148 @@
+import { Path, type SkPath } from "@shopify/react-native-skia";
+import { type ReactElement, useEffect, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import { resolveBand } from "../../core/geometry/band";
+import { buildCandlePaths, candlePoints, SENTIMENTS, type Sentiment } from "../../core/shape/build-candles";
+import { toSkPath } from "../../skia/build-path";
+import { useChartContext } from "../cartesian-chart.context";
+import { categorySpan } from "./chart-bar";
+
+export type ChartCandlestickKeys = {
+	readonly open: string;
+	readonly high: string;
+	readonly low: string;
+	readonly close: string;
+};
+
+export type ChartCandleColors = Readonly<Record<Sentiment, string>>;
+
+export type ChartCandlestickProps = {
+	/** The four series. Each must be one of the chart's `yKeys`. */
+	readonly keys: ChartCandlestickKeys;
+	readonly candleColors: ChartCandleColors;
+	/** The fraction of each step a body fills. Defaults to 0.6. */
+	readonly candleRatio?: number;
+	/** An exact body width, instead of a fraction of the step. */
+	readonly candleWidth?: number;
+	/** Size candles as if the plot held this many, so charts of different lengths match. */
+	readonly candleCount?: number;
+	/** A body thinner than this is expanded so a flat candle stays visible. Defaults to 1. */
+	readonly minBodyHeight?: number;
+	readonly wickStrokeWidth?: number;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+};
+
+/**
+ * Open-high-low-close candles.
+ *
+ * Six `<Path>` nodes: bodies and wicks for each of the three sentiments, and
+ * every candle is present in all six, degenerate where its sentiment does not
+ * apply. A candle that flips therefore morphs from one colour into the other
+ * rather than snapping — see `buildCandlePaths`. Wicks draw first so a body
+ * covers the wick that passes through it, and with **butt** caps, because a
+ * round cap on a zero-length wick is a dot at every non-matching candle.
+ */
+export function ChartCandlestick({
+	keys,
+	candleColors,
+	candleRatio = 0.6,
+	candleWidth,
+	candleCount,
+	minBodyHeight,
+	wickStrokeWidth = 1,
+	opacity,
+	animation,
+}: ChartCandlestickProps): ReactElement {
+	const chart = useChartContext();
+	const { bounds, xPositions, points, orientation } = chart;
+
+	useEffect(() => {
+		if (!__DEV__) return;
+		for (const key of [keys.open, keys.high, keys.low, keys.close]) {
+			if (points[key] === undefined) {
+				console.warn(
+					`[@delacour/react-native-charts] <ChartCandlestick> was given the key "${key}" but the chart has no series ` +
+						"by that name. Every candle key has to be one of the chart's yKeys."
+				);
+			}
+		}
+	}, [keys, points]);
+
+	const paths = useMemo(() => {
+		const band = resolveBand({
+			xPositions,
+			plotWidth: categorySpan(bounds, orientation),
+			innerPadding: 1 - candleRatio,
+			barWidth: candleWidth,
+			barCount: candleCount,
+		});
+		const candles = candlePoints(
+			points[keys.open] ?? [],
+			points[keys.high] ?? [],
+			points[keys.low] ?? [],
+			points[keys.close] ?? [],
+			orientation
+		);
+		const built = buildCandlePaths(candles, {
+			bandwidth: band.bandwidth,
+			minBodyHeight,
+			baseline: orientation === "horizontal" ? bounds.left : bounds.bottom,
+			orientation,
+		});
+		const toSk = (sentiment: Sentiment): { bodies: SkPath; wicks: SkPath } => ({
+			bodies: toSkPath(built[sentiment].bodies),
+			wicks: toSkPath(built[sentiment].wicks),
+		});
+		return { positive: toSk("positive"), negative: toSk("negative"), neutral: toSk("neutral") };
+	}, [xPositions, bounds, points, keys, orientation, candleRatio, candleWidth, candleCount, minBodyHeight]);
+
+	const motion = animation ?? chart.animation;
+
+	return (
+		<>
+			{SENTIMENTS.map((sentiment) => (
+				<CandlePath
+					animation={motion}
+					color={candleColors[sentiment]}
+					key={`${sentiment}-wicks`}
+					opacity={opacity}
+					path={paths[sentiment].wicks}
+					strokeWidth={wickStrokeWidth}
+				/>
+			))}
+			{SENTIMENTS.map((sentiment) => (
+				<CandlePath
+					animation={motion}
+					color={candleColors[sentiment]}
+					key={`${sentiment}-bodies`}
+					opacity={opacity}
+					path={paths[sentiment].bodies}
+				/>
+			))}
+		</>
+	);
+}
+
+ChartCandlestick.displayName = "DelacourCharts.ChartCandlestick";
+
+type CandlePathProps = {
+	readonly path: SkPath;
+	readonly color: string;
+	readonly opacity?: number;
+	readonly animation: ChartAnimation;
+	/** Set for a wick path; a body is filled. */
+	readonly strokeWidth?: number;
+};
+
+/** One of the six paths. A component of its own so each path owns its animation hook. */
+function CandlePath({ path, color, opacity, animation, strokeWidth }: CandlePathProps): ReactElement {
+	const animated = useAnimatedPath(path, animation);
+	if (strokeWidth === undefined) return <Path color={color} opacity={opacity} path={animated} style="fill" />;
+	return (
+		<Path color={color} opacity={opacity} path={animated} strokeCap="butt" strokeWidth={strokeWidth} style="stroke" />
+	);
+}
+
+CandlePath.displayName = "DelacourCharts.ChartCandlestick.Path";

package/src/cartesian/marks/chart-cursor.tsx

@@ -0,0 +1,168 @@
+import { Circle, DashPathEffect, Line } from "@shopify/react-native-skia";
+import type { ReactElement } from "react";
+import { useDerivedValue } from "react-native-reanimated";
+import type { ChartBounds } from "../../core/chart.types";
+import type { ChartScrubSeriesState, ChartScrubState } from "../../gesture/gesture.types";
+import { useChartContext } from "../cartesian-chart.context";
+
+/** Parked off-canvas, so a mark with nothing to point at is not at the origin. */
+const OFFSCREEN = -10_000;
+
+export type ChartCursorDotProps = {
+	/** Which series the dot rides. */
+	readonly yKey: string;
+	readonly color: string;
+	readonly radius?: number;
+	/**
+	 * A ring around the dot, usually the chart's own background.
+	 *
+	 * Without it a dot in the series colour sitting on a line of the same colour
+	 * is a slight thickening and nothing more.
+	 */
+	readonly borderColor?: string;
+	readonly borderWidth?: number;
+	/**
+	 * Sit on the nearest datum rather than gliding along the curve.
+	 *
+	 * On by default, because the readout beside it names a datum. Turn it off
+	 * for a dot that tracks the finger continuously, and expect it to disagree
+	 * with any label showing a measured value.
+	 */
+	readonly snap?: boolean;
+	readonly opacity?: number;
+};
+
+/**
+ * A dot marking where a scrub has reached, on one series.
+ *
+ * The outer component reads the chart and bails when there is no scrub to
+ * follow; the inner one is where the hooks live, so a chart with no scrub
+ * never runs them. Splitting it is what keeps the hook order fixed — a
+ * component that called `useDerivedValue` after a conditional return would
+ * break the moment a chart gained or lost its scrub.
+ *
+ * It reads the series' own `snappedX`/`snappedY`, which the scrub fills in
+ * for either orientation, so the dot lands on the bar's end on a horizontal
+ * chart without this component knowing there is such a thing.
+ */
+export function ChartCursorDot(props: ChartCursorDotProps): ReactElement | null {
+	const { scrub } = useChartContext();
+	const series = scrub?.series[props.yKey];
+	if (!scrub || !series) return null;
+	return <CursorDot {...props} scrub={scrub} series={series} />;
+}
+
+ChartCursorDot.displayName = "DelacourCharts.ChartCursorDot";
+
+function CursorDot({
+	color,
+	radius = 4,
+	borderColor,
+	borderWidth = 2,
+	snap = true,
+	opacity,
+	scrub,
+	series,
+}: ChartCursorDotProps & {
+	readonly scrub: ChartScrubState;
+	readonly series: ChartScrubSeriesState;
+}): ReactElement {
+	const cx = useDerivedValue(() => {
+		const value = snap ? series.snappedX.value : series.x.value;
+		return Number.isFinite(value) ? value : OFFSCREEN;
+	});
+
+	const cy = useDerivedValue(() => {
+		const value = snap ? series.snappedY.value : series.y.value;
+		return Number.isFinite(value) ? value : OFFSCREEN;
+	});
+
+	const alpha = useDerivedValue(() => (scrub.isActive.value ? (opacity ?? 1) : 0));
+
+	return (
+		<>
+			{borderColor === undefined ? null : (
+				<Circle color={borderColor} cx={cx} cy={cy} opacity={alpha} r={radius + borderWidth} />
+			)}
+			<Circle color={color} cx={cx} cy={cy} opacity={alpha} r={radius} />
+		</>
+	);
+}
+
+CursorDot.displayName = "DelacourCharts.ChartCursorDot.Inner";
+
+export type ChartCursorLineProps = {
+	/**
+	 * `x` is a vertical rule; `y` is a horizontal one. Named for the axis the
+	 * line reads against, not for the direction it is drawn in.
+	 *
+	 * Without a `yKey` the rule sits at the touched category — under the
+	 * finger on a vertical chart for `x`, beside it on a horizontal chart for
+	 * `y`. With one, it sits at that series' nearest datum on that axis.
+	 */
+	readonly axis: "x" | "y";
+	/** Which series the rule sits at. Without it the rule follows the category. */
+	readonly yKey?: string;
+	readonly color: string;
+	readonly width?: number;
+	/** Dash on/off lengths. A dashed rule reads as a guide beside solid gridlines. */
+	readonly dash?: readonly [number, number];
+	readonly snap?: boolean;
+	readonly opacity?: number;
+};
+
+/** A crosshair rule spanning the plot at the scrubbed position. */
+export function ChartCursorLine(props: ChartCursorLineProps): ReactElement | null {
+	const { scrub, bounds } = useChartContext();
+	const series = props.yKey === undefined ? undefined : scrub?.series[props.yKey];
+	if (!scrub) return null;
+	if (props.yKey !== undefined && !series) return null;
+	return <CursorLine {...props} bounds={bounds} scrub={scrub} series={series} />;
+}
+
+ChartCursorLine.displayName = "DelacourCharts.ChartCursorLine";
+
+function CursorLine({
+	axis,
+	color,
+	width = 1,
+	dash,
+	snap = true,
+	opacity,
+	bounds,
+	scrub,
+	series,
+}: ChartCursorLineProps & {
+	readonly bounds: ChartBounds;
+	readonly scrub: ChartScrubState;
+	readonly series: ChartScrubSeriesState | undefined;
+}): ReactElement {
+	// Resolved inline rather than through a component-scope worklet helper.
+	// The rule used to call an `at()` worklet from both points' derived values,
+	// and on device it never drew — in this chart and every themed tooltip —
+	// while the dots, which read their shared values directly, did.
+	const position = useDerivedValue(() => {
+		const source = series ?? scrub;
+		const value =
+			axis === "x" ? (snap ? source.snappedX.value : source.x.value) : snap ? source.snappedY.value : source.y.value;
+		return Number.isFinite(value) ? value : OFFSCREEN;
+	});
+
+	const p1 = useDerivedValue(() =>
+		axis === "x" ? { x: position.value, y: bounds.top } : { x: bounds.left, y: position.value }
+	);
+
+	const p2 = useDerivedValue(() =>
+		axis === "x" ? { x: position.value, y: bounds.bottom } : { x: bounds.right, y: position.value }
+	);
+
+	const alpha = useDerivedValue(() => (scrub.isActive.value ? (opacity ?? 1) : 0));
+
+	return (
+		<Line color={color} opacity={alpha} p1={p1} p2={p2} strokeWidth={width} style="stroke">
+			{dash === undefined ? null : <DashPathEffect intervals={[dash[0], dash[1]]} />}
+		</Line>
+	);
+}
+
+CursorLine.displayName = "DelacourCharts.ChartCursorLine.Inner";

package/src/cartesian/marks/chart-grid.tsx

@@ -0,0 +1,46 @@
+import { Path, Skia } from "@shopify/react-native-skia";
+import { type ReactElement, useMemo } from "react";
+import { type GridAxis, gridSegments } from "../../core/geometry/grid-lines";
+import { useChartContext } from "../cartesian-chart.context";
+
+export type ChartGridProps = {
+	/** Which ticks get a rule. Defaults to the y ticks alone. */
+	readonly axis?: GridAxis;
+	readonly color: string;
+	readonly lineWidth?: number;
+	readonly opacity?: number;
+	/** Dash on/off lengths, in points. */
+	readonly dash?: readonly [number, number];
+};
+
+/**
+ * A hairline rule at each tick.
+ *
+ * Every rule is one path rather than one `<Path>` per line: a chart with two
+ * axes and eight ticks each is sixteen Skia nodes for something that is a
+ * single stroke, and the node count is what a Skia tree costs.
+ *
+ * `y` alone by default. Horizontal rules let a reader carry a value across to
+ * the axis, which is what a gridline is for; vertical ones mostly repeat what
+ * the marks already show.
+ */
+export function ChartGrid({ axis = "y", color, lineWidth = 1, opacity, dash }: ChartGridProps): ReactElement {
+	const { xTicks, yTicks, bounds } = useChartContext();
+
+	const path = useMemo(() => {
+		// `Skia.PathBuilder`, not `Skia.Path.Make()` — the mutating methods on
+		// `SkPath` are deprecated in Skia 2.x and warn on every construction.
+		const builder = Skia.PathBuilder.Make();
+		for (const [x1, y1, x2, y2] of gridSegments({ bounds, xTicks, yTicks, axis })) {
+			builder.moveTo(x1, y1);
+			builder.lineTo(x2, y2);
+		}
+		const built = builder.build();
+		if (dash === undefined) return built;
+		return Skia.Path.Dash(built, dash[0], dash[1], 0) ?? built;
+	}, [axis, xTicks, yTicks, bounds, dash]);
+
+	return <Path color={color} opacity={opacity} path={path} strokeWidth={lineWidth} style="stroke" />;
+}
+
+ChartGrid.displayName = "DelacourCharts.ChartGrid";

package/src/cartesian/marks/chart-line.tsx

@@ -0,0 +1,73 @@
+import { Path } from "@shopify/react-native-skia";
+import { type ReactElement, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import type { ChartPoint } from "../../core/chart.types";
+import { buildLinePath } from "../../core/curve/build-line";
+import type { CurveType } from "../../core/curve/curves";
+import { toSkPath } from "../../skia/build-path";
+import { useChartContext } from "../cartesian-chart.context";
+
+export type ChartLineProps = {
+	/** Which series to draw. Read from the chart's context. */
+	readonly yKey?: string;
+	/** The points to draw, when they are not coming from context. */
+	readonly points?: readonly ChartPoint[];
+	readonly color: string;
+	readonly strokeWidth?: number;
+	readonly curve?: CurveType;
+	readonly connectMissingData?: boolean;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+	readonly strokeCap?: "butt" | "round" | "square";
+	readonly strokeJoin?: "bevel" | "miter" | "round";
+};
+
+/**
+ * A stroked line through a series.
+ *
+ * Takes `yKey` or `points`, never needing both: given a key it reads the
+ * chart's context, given points it draws exactly those. One implementation
+ * serves the declarative call site and the render-prop one, so the two can
+ * never drift.
+ *
+ * The default `round` cap and join are not cosmetic. A `butt` cap on a
+ * two-point series leaves the stroke visibly short of its own endpoint, and a
+ * `miter` join spikes at a sharp reversal in volatile data.
+ */
+export function ChartLine({
+	yKey,
+	points,
+	color,
+	strokeWidth = 2,
+	curve,
+	connectMissingData,
+	opacity,
+	animation,
+	strokeCap = "round",
+	strokeJoin = "round",
+}: ChartLineProps): ReactElement {
+	const chart = useChartContext();
+	const series = points ?? (yKey === undefined ? [] : (chart.points[yKey] ?? []));
+
+	const path = useMemo(
+		() => toSkPath(buildLinePath(series, { curve: curve ?? chart.curve, connectMissingData })),
+		[series, curve, chart.curve, connectMissingData]
+	);
+
+	const animated = useAnimatedPath(path, animation ?? chart.animation);
+
+	return (
+		<Path
+			color={color}
+			opacity={opacity}
+			path={animated}
+			strokeCap={strokeCap}
+			strokeJoin={strokeJoin}
+			strokeWidth={strokeWidth}
+			style="stroke"
+		/>
+	);
+}
+
+ChartLine.displayName = "DelacourCharts.ChartLine";

package/src/cartesian/marks/chart-scatter.tsx

@@ -0,0 +1,71 @@
+import { Path } from "@shopify/react-native-skia";
+import { type ReactElement, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import type { ChartPoint } from "../../core/chart.types";
+import { resolveBaseline } from "../../core/shape/build-bars";
+import { buildScatterPath, type ScatterShape } from "../../core/shape/build-scatter";
+import { toSkPath } from "../../skia/build-path";
+import { useChartContext } from "../cartesian-chart.context";
+
+export type ChartScatterProps = {
+	/** Which series to draw. Read from the chart's context. */
+	readonly yKey?: string;
+	/** The points to draw, when they are not coming from context. */
+	readonly points?: readonly ChartPoint[];
+	readonly color: string;
+	/** One radius for every point, or one per point. Defaults to 4. */
+	readonly radius?: number | ((point: ChartPoint, index: number) => number);
+	readonly shape?: ScatterShape;
+	/** Filled discs, or rings. */
+	readonly style?: "fill" | "stroke";
+	readonly strokeWidth?: number;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+};
+
+/**
+ * One shape per datum.
+ *
+ * All the shapes are one `<Path>`, so a hundred points is one Skia node. A
+ * gap is the same shape at radius zero on the baseline, which is what keeps
+ * the series interpolatable when a datum comes and goes.
+ */
+export function ChartScatter({
+	yKey,
+	points,
+	color,
+	radius = 4,
+	shape = "circle",
+	style = "fill",
+	strokeWidth = 1,
+	opacity,
+	animation,
+}: ChartScatterProps): ReactElement {
+	const chart = useChartContext();
+	const series = points ?? (yKey === undefined ? [] : (chart.points[yKey] ?? []));
+	const { orientation } = chart;
+	const baseline = resolveBaseline(
+		orientation === "horizontal" ? chart.xScale : chart.yScale,
+		chart.bounds,
+		orientation
+	);
+
+	const path = useMemo(
+		() => toSkPath(buildScatterPath(series, { radius, shape, baseline, orientation })),
+		[series, radius, shape, baseline, orientation]
+	);
+	const animated = useAnimatedPath(path, animation ?? chart.animation);
+
+	return (
+		<Path
+			color={color}
+			opacity={opacity}
+			path={animated}
+			strokeWidth={style === "stroke" ? strokeWidth : undefined}
+			style={style}
+		/>
+	);
+}
+
+ChartScatter.displayName = "DelacourCharts.ChartScatter";

package/src/core/AGENTS.md

@@ -0,0 +1,77 @@
+# core
+
+Every number this package computes, and nothing that draws.
+
+## The rule
+
+**No runtime import of `react`, `react-native`, `@shopify/react-native-skia`,
+`react-native-reanimated`, `react-native-gesture-handler` or
+`react-native-worklets`.** Type-only imports are fine. `d3-scale` and
+`d3-shape` are fine — they are pure ESM JavaScript that Bun can parse.
+
+`src/purity.test.ts` enforces it. See the package `AGENTS.md` for why the
+failure mode makes a test necessary rather than a convention sufficient.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `chart.types.ts` | `ChartPoint`, `ChartSegment`, `ChartBounds`, `ChartSize`, `ChartRow`, `ChartOrientation` |
+| `scale/scale.types.ts` | `ScaleDescriptor` — a scale as plain numbers |
+| `scale/make-scale.ts` | d3 builds and nices; only the descriptor comes back |
+| `scale/scale.ts` | `scaleValue` / `invertValue` — the two flat worklets |
+| `ticks/linear-ticks.ts` | Linear and log tick values, with the log thinning d3 does not do |
+| `ticks/time-ticks.ts` | Calendar-correct tick values, via `scaleTime` |
+| `ticks/tick-count.ts` | Downsampling, and the shared count that aligns two axes' gridlines |
+| `ticks/build-ticks.ts` | Values plus positions, through the same scale the marks use |
+| `curve/curves.ts` | The d3-shape interpolators, and which of them approximate |
+| `curve/build-line.ts` | Points to an SVG path string |
+| `curve/build-area.ts` | The same, closed against a baseline or a lower edge |
+| `geometry/domain.ts` | Extent, explicit overrides, padding by fraction and by step, zero |
+| `geometry/step.ts` | The smallest gap between x values — what a bar's width and the x padding are stated in |
+| `geometry/band.ts` | A datum's band on a scale with no band of its own, and where a group's bars sit inside it |
+| `geometry/stack.ts` | Series stacked in data space, then scaled; the totals a stacked y domain needs |
+| `geometry/category-domain.ts` | Whether the category domain holds the outermost bars — what `ChartBar` warns about |
+| `geometry/chart-bounds.ts` | Canvas minus padding minus gutters |
+| `geometry/chart-layout.ts` | The two layout passes, and the category/value roles onto the canvas axes |
+| `geometry/x-values.ts` | The numeric-or-index decision, made once for the whole series |
+| `geometry/transform-input-data.ts` | Rows to plotted points, on whichever axes the orientation says |
+| `interaction/path-segments.ts` | SVG path to flat cubic runs, for the UI thread |
+| `interaction/closest-index.ts` | Nearest datum, by binary search |
+| `interaction/y-for-x.ts` | `y` on the drawn curve, by bisection |
+| `animation/morph-strategy.ts` | Which end to pad, and when to resample instead |
+| `animation/resample-points.ts` | Two series brought to one length |
+| `text/axis-gutters.ts` | Measured label widths to the space an axis needs |
+| `text/label-anchor.ts` | Baseline-anchored text placed against a point |
+| `text/bar-label.ts` | A label against a bar's value end, base end or side; `top` follows the value end either way round |
+| `util/read-at.ts` | A list read that yields `NaN` for a gap or a missing index — the scrub's flat worklet |
+| `shape/rect-path.ts` | A rectangle as `M C L C L C L C Z`, every corner a cubic |
+| `shape/build-bars.ts` | Points or segments to bar rects and one path, the baseline held inside the plot |
+| `shape/build-scatter.ts` | A circle, square or star per point, each on a fixed verb sequence |
+| `shape/build-candles.ts` | Candles zipped from four series; six paths, every candle in each |
+| `polar/polar.types.ts` | `PieSliceData`, `PolarLayout`, `InnerRadius` — a slice as plain numbers |
+| `polar/polar-point.ts` | Degrees clockwise from 12 o'clock to a canvas point, done once |
+| `polar/pie-input.ts` | Rows to values and labels, nothing dropped |
+| `polar/resolve-layout.ts` | The largest circle the padded canvas holds, and the hole inside it |
+| `polar/resolve-slices.ts` | Values to angles; sweeps sum to the circle exactly |
+| `polar/build-slice-path.ts` | A slice as eleven verbs, whatever its sweep |
+| `polar/label-position.ts` | A label on the bisector, offset across the annulus |
+| `polar/slice-index-at.ts` | Which slice is under a point — the sixth flat worklet |
+| `polar/slice-opacity.ts` | What one slice draws at while another is selected |
+
+## Design
+
+- **Pure means testable, and testable is the point.** `bun test` cannot render
+  a React Native component, so anything worth asserting has to live here. When
+  a decision looks like it belongs in a `.tsx` because it is only used once —
+  it is only used once *today*. Put it here.
+
+- **Guard the degenerate input at the bottom, not at every call site.** An
+  empty series, a single point, a constant series, a zero-size canvas and a
+  `NaN` in the source data are all real and all reach these functions. Each
+  returns something finite and sensible, which is why nothing upstream has to
+  check first.
+
+- **A `"worklet"` directive is a string, not an import.** It costs a module
+  nothing in purity, which is how the scrub solver and the scale readers stay
+  testable while running on the UI thread.

package/src/core/animation/morph-strategy.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { chooseMorphStrategy } from "./morph-strategy";
+
+describe("chooseMorphStrategy", () => {
+	test("does nothing when the counts already match", () => {
+		expect(chooseMorphStrategy([0, 1, 2], [0, 1, 2])).toBe("none");
+		expect(chooseMorphStrategy([0, 1, 2], [9, 8, 7])).toBe("none");
+	});
+
+	test("pads the end when points were appended — the streaming case", () => {
+		expect(chooseMorphStrategy([0, 1, 2], [0, 1, 2, 3, 4])).toBe("pad-end");
+	});
+
+	test("pads the end when points were dropped from the end", () => {
+		expect(chooseMorphStrategy([0, 1, 2, 3, 4], [0, 1, 2])).toBe("pad-end");
+	});
+
+	test("pads the start when the head was dropped — a rolling window", () => {
+		expect(chooseMorphStrategy([0, 1, 2, 3, 4], [2, 3, 4])).toBe("pad-start");
+	});
+
+	test("pads the start when points were prepended", () => {
+		expect(chooseMorphStrategy([2, 3, 4], [0, 1, 2, 3, 4])).toBe("pad-start");
+	});
+
+	test("resamples when the two series are not versions of each other", () => {
+		expect(chooseMorphStrategy([0, 1, 2], [10, 20, 30, 40])).toBe("resample");
+	});
+
+	test("resamples when either series is empty", () => {
+		expect(chooseMorphStrategy([], [0, 1])).toBe("resample");
+		expect(chooseMorphStrategy([0, 1], [])).toBe("resample");
+	});
+
+	test("tolerates floating-point drift in the x values", () => {
+		expect(chooseMorphStrategy([0, 1, 2], [1e-9, 1 + 1e-9, 2, 3])).toBe("pad-end");
+	});
+});

package/src/core/animation/morph-strategy.ts

@@ -0,0 +1,53 @@
+/**
+ * How two series of different lengths are brought to a common point count.
+ *
+ * Named for which end of the shorter array is padded, not for what changed.
+ */
+export type MorphStrategy = "none" | "pad-end" | "pad-start" | "resample";
+
+/** How closely two x-series must agree to count as the same points. */
+const X_EPSILON = 1e-6;
+
+/**
+ * The strategy that makes a data change read correctly.
+ *
+ * The choice is the whole reason this module exists. Every strategy produces
+ * two arrays of equal length and so a pair of interpolatable paths; only one
+ * of them produces motion that means what the data did.
+ *
+ * - Points appended to the end — the streaming case — pad the previous series
+ *   at its end, so the new tail grows out of where the line stopped instead of
+ *   the whole line sliding left.
+ * - Points dropped from the front — a rolling window — pad the next series at
+ *   its start, so the departing head collapses into the first survivor.
+ * - Anything else resamples both, which is the honest answer when the two
+ *   series are not versions of each other.
+ */
+export function chooseMorphStrategy(previousXs: readonly number[], nextXs: readonly number[]): MorphStrategy {
+	if (previousXs.length === nextXs.length) return "none";
+	if (previousXs.length === 0 || nextXs.length === 0) return "resample";
+
+	const shorter = previousXs.length < nextXs.length ? previousXs : nextXs;
+	const longer = previousXs.length < nextXs.length ? nextXs : previousXs;
+
+	let prefixMatches = true;
+	for (let index = 0; index < shorter.length; index += 1) {
+		if (Math.abs((shorter[index] as number) - (longer[index] as number)) > X_EPSILON) {
+			prefixMatches = false;
+			break;
+		}
+	}
+	if (prefixMatches) return "pad-end";
+
+	const offset = longer.length - shorter.length;
+	let suffixMatches = true;
+	for (let index = 0; index < shorter.length; index += 1) {
+		if (Math.abs((shorter[index] as number) - (longer[index + offset] as number)) > X_EPSILON) {
+			suffixMatches = false;
+			break;
+		}
+	}
+	if (suffixMatches) return "pad-start";
+
+	return "resample";
+}