insomni-plot 0.1.0-alpha.0

package/src/legend.ts

@@ -0,0 +1,422 @@
+import {
+  BLACK,
+  type Color,
+  type FrameRect,
+  type GlyphAtlas,
+  type Group,
+  type Layer,
+  withAlpha,
+} from "insomni";
+import { placeable, stack, type BoxOrigin, type Placeable } from "./layout/box.ts";
+import { emitPointSwatch, type PointBorderStyle, type PointShapeKind } from "./marks.ts";
+
+// ---------------------------------------------------------------------------
+// Swatch specs — one per mark style. Each mark contributes a swatch ctor so
+// the legend matches the mark drawing exactly (e.g. dashed line legend for a
+// dashed line mark).
+// ---------------------------------------------------------------------------
+
+export interface PointSwatchSpec {
+  kind: "point";
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  shape?: PointShapeKind;
+  /** Default `5`. */
+  radius?: number;
+  /** Per-shape border treatment — matches the mark side. Default `"solid"`. */
+  borderStyle?: PointBorderStyle;
+  /** Optional secondary glyph drawn on the same anchor. `null`/undefined = none. */
+  overlayGlyph?: PointShapeKind | null;
+  /** Overlay radius as a fraction of `radius`. Default `0.6`. */
+  overlayScale?: number;
+}
+
+export interface LineSwatchSpec {
+  kind: "line";
+  stroke: Color;
+  strokeWidth?: number;
+  dashPattern?: readonly number[];
+  /** Default `18`. */
+  width?: number;
+}
+
+export interface BarSwatchSpec {
+  kind: "bar";
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /** Default `12`. */
+  size?: number;
+}
+
+export interface AreaSwatchSpec {
+  kind: "area";
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Default `14` (slight rectangle, not a square). */
+  width?: number;
+  /** Default `8`. */
+  height?: number;
+}
+
+export type SwatchSpec = PointSwatchSpec | LineSwatchSpec | BarSwatchSpec | AreaSwatchSpec;
+
+// ---------------------------------------------------------------------------
+// Swatch constructors — call from your mark site so the legend matches.
+// ---------------------------------------------------------------------------
+
+export function pointSwatch(opts: Omit<PointSwatchSpec, "kind">): PointSwatchSpec {
+  return { kind: "point", ...opts };
+}
+
+export function lineSwatch(opts: Omit<LineSwatchSpec, "kind">): LineSwatchSpec {
+  return { kind: "line", ...opts };
+}
+
+export function barSwatch(opts: Omit<BarSwatchSpec, "kind">): BarSwatchSpec {
+  return { kind: "bar", ...opts };
+}
+
+export function areaSwatch(opts: Omit<AreaSwatchSpec, "kind">): AreaSwatchSpec {
+  return { kind: "area", ...opts };
+}
+
+// ---------------------------------------------------------------------------
+// Drawing a swatch (centred at given point, returns occupied width)
+// ---------------------------------------------------------------------------
+
+function swatchWidth(spec: SwatchSpec): number {
+  switch (spec.kind) {
+    case "point":
+      return (spec.radius ?? 5) * 2;
+    case "line":
+      return spec.width ?? 18;
+    case "bar":
+      return spec.size ?? 12;
+    case "area":
+      return spec.width ?? 14;
+  }
+}
+
+function swatchHeight(spec: SwatchSpec): number {
+  switch (spec.kind) {
+    case "point":
+      return (spec.radius ?? 5) * 2;
+    case "line":
+      return Math.max(spec.strokeWidth ?? 2, 2);
+    case "bar":
+      return spec.size ?? 12;
+    case "area":
+      return spec.height ?? 8;
+  }
+}
+
+function drawSwatch(
+  layer: Layer,
+  spec: SwatchSpec,
+  cx: number,
+  cy: number,
+  alpha: number = 1,
+  group?: Group,
+): void {
+  const alphaize = (c: Color) => withAlpha(c, (c.a ?? 1) * alpha);
+  switch (spec.kind) {
+    case "point": {
+      const radius = spec.radius ?? 5;
+      const shape = spec.shape ?? "circle";
+      const fill = alphaize(spec.fill ?? BLACK);
+      const stroke = spec.stroke ? alphaize(spec.stroke) : undefined;
+      emitPointSwatch(layer, {
+        cx,
+        cy,
+        radius,
+        fill,
+        stroke,
+        strokeWidth: spec.strokeWidth,
+        shape,
+        borderStyle: spec.borderStyle,
+        overlayGlyph: spec.overlayGlyph ?? null,
+        overlayScale: spec.overlayScale,
+        group,
+      });
+      return;
+    }
+    case "line": {
+      const width = spec.width ?? 18;
+      const half = width / 2;
+      layer.pushPolyline({
+        points: [
+          { x: cx - half, y: cy },
+          { x: cx + half, y: cy },
+        ],
+        color: alphaize(spec.stroke),
+        width: spec.strokeWidth ?? 2,
+        dashPattern: spec.dashPattern,
+        cap: "round",
+        group,
+      });
+      return;
+    }
+    case "bar": {
+      const size = spec.size ?? 12;
+      layer.pushRect({
+        x: cx - size / 2,
+        y: cy - size / 2,
+        width: size,
+        height: size,
+        fill: spec.fill ? alphaize(spec.fill) : undefined,
+        stroke: spec.stroke ? alphaize(spec.stroke) : undefined,
+        strokeWidth: spec.strokeWidth,
+        cornerRadius: spec.cornerRadius,
+        group,
+      });
+      return;
+    }
+    case "area": {
+      const width = spec.width ?? 14;
+      const height = spec.height ?? 8;
+      layer.pushRect({
+        x: cx - width / 2,
+        y: cy - height / 2,
+        width,
+        height,
+        fill: spec.fill ? alphaize(spec.fill) : undefined,
+        stroke: spec.stroke ? alphaize(spec.stroke) : undefined,
+        strokeWidth: spec.strokeWidth,
+        group,
+      });
+      return;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Legend
+// ---------------------------------------------------------------------------
+
+export interface LegendEntry {
+  label: string;
+  swatch: SwatchSpec;
+  /** Optional hint for interactivity layers to render the entry as "off". */
+  hidden?: boolean;
+}
+
+export type LegendOrientation = "horizontal" | "vertical";
+export type LegendAlign = "start" | "end";
+
+export interface LegendOptions {
+  atlas: GlyphAtlas;
+  orientation?: LegendOrientation;
+  /** Anchor inside the layout box. Default `"start"` (left/top edge of box). */
+  align?: LegendAlign;
+  fontSize?: number;
+  fontStyle?: string;
+  labelColor?: Color;
+  /** Pixel gap between swatch and label. Default `6`. */
+  swatchGap?: number;
+  /** Pixel gap between entries. Default `14` (horizontal) or `4` (vertical). */
+  entryGap?: number;
+  /** Optional title rendered above the entries (left-aligned, bold). */
+  title?: string;
+  titleFontSize?: number;
+  titleColor?: Color;
+  /** Pixel gap between title and entries. Default `4`. */
+  titleGap?: number;
+  /** Alpha for hidden entries. Default `0.2`. */
+  dimAlpha?: number;
+  group?: Group;
+}
+
+export interface LegendBuilder extends Placeable {
+  /** Number of entries (or, for color bars, palette samples). */
+  readonly length: number;
+  /** Total laid-out width and height in layer-space pixels. */
+  measure(): { width: number; height: number };
+  /** Bounding boxes of each entry, relative to the legend's top-left. */
+  getEntryBboxes(): (FrameRect & { label: string })[];
+}
+
+/**
+ * `Guide` is the shared shape every legend-like component (categorical
+ * `legend()`, continuous `colorBar()`, future `sizeGuide()` / `shapeGuide()`)
+ * returns. It's a `Placeable` so the chart layout engine can size and place
+ * it generically. Concrete builders may add extra fields (e.g. `length`).
+ */
+export type Guide = Placeable;
+
+/**
+ * Lay out a row (or column) of swatch + label pairs. Each mark contributes
+ * its own swatch shape via the `*Swatch(...)` helpers, so a dashed line shows
+ * a dashed swatch, a triangle point shows a triangle, etc.
+ *
+ * The legend is positioned by `origin` when added: `origin` is the *top-left*
+ * of the layout box. To right-align, measure first then offset:
+ *
+ * ```ts
+ * const lg = legend(entries, { atlas: a });
+ * const { width } = lg.measure();
+ * lg.addTo(layer, { x: outer.x + outer.width - width, y: outer.y });
+ * ```
+ */
+export function legend(entries: readonly LegendEntry[], options: LegendOptions): LegendBuilder {
+  const orientation = options.orientation ?? "horizontal";
+  const fontSize = options.fontSize ?? 11;
+  const fontStyle = options.fontStyle ?? "normal";
+  const swatchGap = options.swatchGap ?? 6;
+  const entryGap = options.entryGap ?? (orientation === "horizontal" ? 14 : 4);
+  const labelColor = options.labelColor ?? BLACK;
+  const align = options.align ?? "start";
+  const dimAlpha = options.dimAlpha ?? 0.2;
+
+  const measureFontOpts = { fontSize, fontStyle, simple: true };
+
+  // Pre-measure each entry: its swatch box, its label width, and the row height.
+  const measured = entries.map((entry) => {
+    const sw = swatchWidth(entry.swatch);
+    const sh = swatchHeight(entry.swatch);
+    const lw = options.atlas.measureText(entry.label, measureFontOpts).width;
+    return { entry, swatchW: sw, swatchH: sh, labelW: lw };
+  });
+
+  const rowHeight = Math.max(fontSize, ...measured.map((m) => m.swatchH));
+  const entriesWidth =
+    orientation === "horizontal"
+      ? measured.reduce((sum, m) => sum + m.swatchW + swatchGap + m.labelW, 0) +
+        entryGap * Math.max(0, measured.length - 1)
+      : Math.max(0, ...measured.map((m) => m.swatchW + swatchGap + m.labelW));
+  const entriesHeight =
+    orientation === "horizontal"
+      ? rowHeight
+      : measured.length * rowHeight + entryGap * Math.max(0, measured.length - 1);
+
+  const getBodyBboxes = (o: BoxOrigin): (FrameRect & { label: string })[] => {
+    const bboxes: (FrameRect & { label: string })[] = [];
+    if (orientation === "horizontal") {
+      let x = o.x;
+      for (const m of measured) {
+        bboxes.push({
+          label: m.entry.label,
+          x,
+          y: o.y,
+          width: m.swatchW + swatchGap + m.labelW,
+          height: rowHeight,
+        });
+        x += m.swatchW + swatchGap + m.labelW + entryGap;
+      }
+    } else {
+      let y = o.y;
+      for (const m of measured) {
+        bboxes.push({
+          label: m.entry.label,
+          x: o.x,
+          y,
+          width: m.swatchW + swatchGap + m.labelW,
+          height: rowHeight,
+        });
+        y += rowHeight + entryGap;
+      }
+    }
+    return bboxes;
+  };
+
+  const buildBody = (): Placeable =>
+    placeable({ width: entriesWidth, height: entriesHeight }, (layer, o) => {
+      if (orientation === "horizontal") {
+        let x = o.x;
+        const cy = o.y + rowHeight / 2;
+        for (const m of measured) {
+          const entryAlpha = m.entry.hidden ? dimAlpha : 1;
+          drawSwatch(layer, m.entry.swatch, x + m.swatchW / 2, cy, entryAlpha, options.group);
+          layer.pushText({
+            simple: true,
+            text: m.entry.label,
+            x: x + m.swatchW + swatchGap,
+            y: o.y + (rowHeight - fontSize) / 2,
+            fontSize,
+            color: withAlpha(labelColor, (labelColor.a ?? 1) * entryAlpha),
+            align: "left",
+            group: options.group,
+          });
+          x += m.swatchW + swatchGap + m.labelW + entryGap;
+        }
+      } else {
+        let y = o.y;
+        for (const m of measured) {
+          const cy = y + rowHeight / 2;
+          const entryAlpha = m.entry.hidden ? dimAlpha : 1;
+          drawSwatch(layer, m.entry.swatch, o.x + m.swatchW / 2, cy, entryAlpha, options.group);
+          layer.pushText({
+            simple: true,
+            text: m.entry.label,
+            x: o.x + m.swatchW + swatchGap,
+            y: y + (rowHeight - fontSize) / 2,
+            fontSize,
+            color: withAlpha(labelColor, (labelColor.a ?? 1) * entryAlpha),
+            align: "left",
+            group: options.group,
+          });
+          y += rowHeight + entryGap;
+        }
+      }
+    });
+
+  const buildTitle = (titleText: string): Placeable => {
+    const titleFontSize = options.titleFontSize ?? fontSize;
+    const titleColor = options.titleColor ?? labelColor;
+    const titleWidth = options.atlas.measureText(titleText, {
+      fontSize: titleFontSize,
+      fontStyle,
+      simple: true,
+    }).width;
+    return placeable({ width: titleWidth, height: titleFontSize }, (layer, o) => {
+      layer.pushText({
+        simple: true,
+        text: titleText,
+        x: o.x,
+        y: o.y,
+        fontSize: titleFontSize,
+        color: titleColor,
+        align: "left",
+        group: options.group,
+      });
+    });
+  };
+
+  const body = buildBody();
+
+  // align="start"; outer chart code positions the whole stack. align="end"
+  // (right-anchor) is honored in addTo() below by offsetting origin.x by the
+  // composed width — matching legacy "right-edge as origin" behavior.
+  const titleText = options.title && options.title.length > 0 ? options.title : undefined;
+  let composed: Placeable = body;
+  if (titleText) {
+    composed = stack([buildTitle(titleText), body], {
+      direction: "vertical",
+      align: "start",
+      gap: options.titleGap ?? 4,
+    });
+  }
+
+  const composedSize = composed.measure();
+
+  return {
+    length: entries.length,
+    measure: () => composedSize,
+    getEntryBboxes() {
+      // If there's a title, it's stacked above the body.
+      // stack([titleBox, body]) with align="start" and direction="vertical"
+      // titleBox height = titleFontSize, gap = titleGap
+      const yOffset = titleText ? (options.titleFontSize ?? fontSize) + (options.titleGap ?? 4) : 0;
+      return getBodyBboxes({ x: 0, y: yOffset });
+    },
+    addTo(layer: Layer, origin: BoxOrigin) {
+      // Legacy behavior: align="end" means the caller passed the *right* edge
+      // as origin.x and expects the legend to draw to its left.
+      const x = align === "end" ? origin.x - composedSize.width : origin.x;
+      composed.addTo(layer, { x, y: origin.y });
+    },
+  };
+}

package/src/marks/curve.d.ts

@@ -0,0 +1,43 @@
+import type { Vec2 } from "insomni";
+/**
+ * Built-in interpolation modes between successive points:
+ * - `"linear"` — straight line (default).
+ * - `"step"` — horizontal then vertical at midpoint.
+ * - `"step-before"` — vertical then horizontal (value changes immediately).
+ * - `"step-after"` — horizontal then vertical (value held until next x).
+ * - `"monotone-x"` — Fritsch–Carlson monotone cubic. Smooth, no overshoot.
+ *   Safe default for noisy series.
+ * - `"basis"` — uniform B-spline. Very smooth; clipped at endpoints.
+ * - `"catmull-rom"` — Catmull–Rom spline with tension 0.5 — passes through every point.
+ * - `"cardinal"` — Cardinal spline with tension 0.5 — looser, rounder curves.
+ *
+ * You can also pass a `CustomCurve` function for full control. See `defineCurve`.
+ */
+export type LineCurvePreset = "linear" | "step" | "step-before" | "step-after" | "monotone-x" | "basis" | "catmull-rom" | "cardinal";
+/**
+ * Custom resampler. Receives the raw points and a sample-density hint
+ * (passed via `lineMark({ curveSamples })`), returns the polyline to draw.
+ * Endpoints should generally pass through `points[0]` and `points.at(-1)`.
+ */
+export type CustomCurve = (points: Vec2[], samples: number) => Vec2[];
+export type LineCurve = LineCurvePreset | CustomCurve;
+/**
+ * Wrap a resampler function so it has a stable identity for use as a curve
+ * preset. The returned value is callable like a `CustomCurve` and may be
+ * passed wherever `LineCurve` is expected.
+ *
+ * ```ts
+ * const wobble = defineCurve((points, samples) => {
+ *   // …emit your own polyline…
+ * });
+ * lineMark(data, { curve: wobble });
+ * ```
+ */
+export declare function defineCurve(resample: CustomCurve): CustomCurve;
+/**
+ * Build a Catmull–Rom-family curve at a given tension.
+ * `tension = 0.5` is classic Catmull–Rom; `0` is a tighter spline; `1` is
+ * very loose. Useful for hand-drawn looking line charts.
+ */
+export declare function cardinalCurve(tension?: number): CustomCurve;
+export declare function resamplePoints(points: Vec2[], curve: LineCurve, samples: number): Vec2[];

package/src/marks/curve.ts

@@ -0,0 +1,244 @@
+import type { Vec2 } from "insomni";
+
+/**
+ * Built-in interpolation modes between successive points:
+ * - `"linear"` — straight line (default).
+ * - `"step"` — horizontal then vertical at midpoint.
+ * - `"step-before"` — vertical then horizontal (value changes immediately).
+ * - `"step-after"` — horizontal then vertical (value held until next x).
+ * - `"monotone-x"` — Fritsch–Carlson monotone cubic. Smooth, no overshoot.
+ *   Safe default for noisy series.
+ * - `"basis"` — uniform B-spline. Very smooth; clipped at endpoints.
+ * - `"catmull-rom"` — Catmull–Rom spline with tension 0.5 — passes through every point.
+ * - `"cardinal"` — Cardinal spline with tension 0.5 — looser, rounder curves.
+ *
+ * You can also pass a `CustomCurve` function for full control. See `defineCurve`.
+ */
+export type LineCurvePreset =
+  | "linear"
+  | "step"
+  | "step-before"
+  | "step-after"
+  | "monotone-x"
+  | "basis"
+  | "catmull-rom"
+  | "cardinal";
+
+/**
+ * Custom resampler. Receives the raw points and a sample-density hint
+ * (passed via `lineMark({ curveSamples })`), returns the polyline to draw.
+ * Endpoints should generally pass through `points[0]` and `points.at(-1)`.
+ */
+export type CustomCurve = (points: Vec2[], samples: number) => Vec2[];
+
+export type LineCurve = LineCurvePreset | CustomCurve;
+
+/**
+ * Wrap a resampler function so it has a stable identity for use as a curve
+ * preset. The returned value is callable like a `CustomCurve` and may be
+ * passed wherever `LineCurve` is expected.
+ *
+ * ```ts
+ * const wobble = defineCurve((points, samples) => {
+ *   // …emit your own polyline…
+ * });
+ * lineMark(data, { curve: wobble });
+ * ```
+ */
+export function defineCurve(resample: CustomCurve): CustomCurve {
+  return resample;
+}
+
+/**
+ * Build a Catmull–Rom-family curve at a given tension.
+ * `tension = 0.5` is classic Catmull–Rom; `0` is a tighter spline; `1` is
+ * very loose. Useful for hand-drawn looking line charts.
+ */
+export function cardinalCurve(tension = 0.5): CustomCurve {
+  return (points, samples) => cardinalResample(points, samples, tension);
+}
+
+export function resamplePoints(points: Vec2[], curve: LineCurve, samples: number): Vec2[] {
+  if (points.length < 2) return points;
+
+  if (typeof curve === "function") {
+    return curve(points, samples);
+  }
+
+  switch (curve) {
+    case "linear":
+      return points;
+
+    case "step": {
+      const out: Vec2[] = [points[0]!];
+      for (let i = 1; i < points.length; i++) {
+        const a = points[i - 1]!;
+        const b = points[i]!;
+        const midX = (a.x + b.x) / 2;
+        out.push({ x: midX, y: a.y });
+        out.push({ x: midX, y: b.y });
+        out.push(b);
+      }
+      return out;
+    }
+
+    case "step-before": {
+      const out: Vec2[] = [points[0]!];
+      for (let i = 1; i < points.length; i++) {
+        const a = points[i - 1]!;
+        const b = points[i]!;
+        out.push({ x: a.x, y: b.y });
+        out.push(b);
+      }
+      return out;
+    }
+
+    case "step-after": {
+      const out: Vec2[] = [points[0]!];
+      for (let i = 1; i < points.length; i++) {
+        const a = points[i - 1]!;
+        const b = points[i]!;
+        out.push({ x: b.x, y: a.y });
+        out.push(b);
+      }
+      return out;
+    }
+
+    case "monotone-x":
+      return monotoneCubicResample(points, samples);
+
+    case "basis":
+      return basisSplineResample(points, samples);
+
+    case "catmull-rom":
+      return cardinalResample(points, samples, 0.5);
+
+    case "cardinal":
+      return cardinalResample(points, samples, 0.5);
+  }
+}
+
+// Fritsch–Carlson monotone cubic: compute slopes that don't overshoot.
+function monotoneCubicResample(points: Vec2[], samples: number): Vec2[] {
+  const n = points.length;
+  const dx: number[] = Array.from({ length: n - 1 });
+  const dy: number[] = Array.from({ length: n - 1 });
+  const m: number[] = Array.from({ length: n - 1 });
+  for (let i = 0; i < n - 1; i++) {
+    dx[i] = points[i + 1]!.x - points[i]!.x;
+    dy[i] = points[i + 1]!.y - points[i]!.y;
+    m[i] = dx[i] === 0 ? 0 : dy[i]! / dx[i]!;
+  }
+
+  // Slopes at each point.
+  const t: number[] = Array.from({ length: n });
+  t[0] = m[0]!;
+  t[n - 1] = m[n - 2]!;
+  for (let i = 1; i < n - 1; i++) {
+    if (m[i - 1]! * m[i]! <= 0) {
+      t[i] = 0;
+    } else {
+      t[i] = (m[i - 1]! + m[i]!) / 2;
+    }
+  }
+  // Limit to keep monotonic.
+  for (let i = 0; i < n - 1; i++) {
+    if (m[i] === 0) {
+      t[i] = 0;
+      t[i + 1] = 0;
+    } else {
+      const a = t[i]! / m[i]!;
+      const b = t[i + 1]! / m[i]!;
+      const h = a * a + b * b;
+      if (h > 9) {
+        const s = (3 / Math.sqrt(h)) * m[i]!;
+        t[i] = s * a;
+        t[i + 1] = s * b;
+      }
+    }
+  }
+
+  // Sample each segment.
+  const out: Vec2[] = [points[0]!];
+  for (let i = 0; i < n - 1; i++) {
+    const x0 = points[i]!.x;
+    const x1 = points[i + 1]!.x;
+    const y0 = points[i]!.y;
+    const y1 = points[i + 1]!.y;
+    const h = x1 - x0;
+    if (h === 0) {
+      out.push(points[i + 1]!);
+      continue;
+    }
+    for (let s = 1; s <= samples; s++) {
+      const u = s / samples;
+      const u2 = u * u;
+      const u3 = u2 * u;
+      const h00 = 2 * u3 - 3 * u2 + 1;
+      const h10 = u3 - 2 * u2 + u;
+      const h01 = -2 * u3 + 3 * u2;
+      const h11 = u3 - u2;
+      const y = h00 * y0 + h10 * h * t[i]! + h01 * y1 + h11 * h * t[i + 1]!;
+      const x = x0 + u * h;
+      out.push({ x, y });
+    }
+  }
+  return out;
+}
+
+// Uniform B-spline (cubic), sampled. Endpoints are anchored by triplicating.
+function basisSplineResample(points: Vec2[], samples: number): Vec2[] {
+  const n = points.length;
+  if (n < 2) return points;
+  // Triplicate endpoints to clamp.
+  const ext: Vec2[] = [points[0]!, points[0]!, ...points, points[n - 1]!, points[n - 1]!];
+  const out: Vec2[] = [];
+  for (let i = 1; i < ext.length - 2; i++) {
+    const p0 = ext[i - 1]!;
+    const p1 = ext[i]!;
+    const p2 = ext[i + 1]!;
+    const p3 = ext[i + 2]!;
+    for (let s = 0; s <= samples; s++) {
+      const u = s / samples;
+      const u2 = u * u;
+      const u3 = u2 * u;
+      const b0 = (1 - 3 * u + 3 * u2 - u3) / 6;
+      const b1 = (4 - 6 * u2 + 3 * u3) / 6;
+      const b2 = (1 + 3 * u + 3 * u2 - 3 * u3) / 6;
+      const b3 = u3 / 6;
+      const x = b0 * p0.x + b1 * p1.x + b2 * p2.x + b3 * p3.x;
+      const y = b0 * p0.y + b1 * p1.y + b2 * p2.y + b3 * p3.y;
+      out.push({ x, y });
+    }
+  }
+  return out;
+}
+
+// Cardinal/Catmull–Rom spline. Tension 0.5 is the classic CR formulation.
+// Endpoints are duplicated so the curve passes through `points[0]` / `points.at(-1)`.
+function cardinalResample(points: Vec2[], samples: number, tension: number): Vec2[] {
+  const n = points.length;
+  if (n < 2) return points;
+  const c = 1 - tension;
+  const out: Vec2[] = [points[0]!];
+  for (let i = 0; i < n - 1; i++) {
+    const p0 = points[i - 1] ?? points[i]!;
+    const p1 = points[i]!;
+    const p2 = points[i + 1]!;
+    const p3 = points[i + 2] ?? points[i + 1]!;
+    for (let s = 1; s <= samples; s++) {
+      const t = s / samples;
+      const t2 = t * t;
+      const t3 = t2 * t;
+      // Cardinal basis.
+      const b0 = -c * t + 2 * c * t2 - c * t3;
+      const b1 = 1 + (c - 3) * t2 + (2 - c) * t3;
+      const b2 = c * t + (3 - 2 * c) * t2 + (c - 2) * t3;
+      const b3 = -c * t2 + c * t3;
+      const x = b0 * p0.x + b1 * p1.x + b2 * p2.x + b3 * p3.x;
+      const y = b0 * p0.y + b1 * p1.y + b2 * p2.y + b3 * p3.y;
+      out.push({ x, y });
+    }
+  }
+  return out;
+}