@motionscript/charts 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/line-chart/line-chart.ts

@@ -1,929 +1,961 @@
-import {
-  command,
-  node,
-  Node2D,
-  Rect,
-  easeOut,
-  property,
-  type Command,
-  type CommandArgs,
-  type DataRecord,
-  type EasingFunction,
-  type NodeConfig,
-  type Node2DProps,
-  type Vector2,
-} from "@motionscript/sdk"
-
-import { ChartBorder } from "../kit/chart-border"
-import { ChartCanvas } from "../kit/chart-canvas"
-import { ChartLegend } from "../kit/chart-legend"
-import { VerticalAxis } from "../kit/vertical-axis"
-import {
-  SPOTLIGHT_DIM,
-  formatMarker,
-  lerpAxisDomain,
-  markerValues,
-  resolveAxisDomain,
-  resolveSeriesFill,
-  resolveSeriesStroke,
-  type AxisDomainConfig,
-  type Range,
-} from "../kit/shared"
-import { ChartLine } from "./chart-line"
-import { ChartRegion } from "./chart-region"
-import { HorizontalAxis } from "./horizontal-axis"
-import {
-  DEFAULT_CHART_THEME,
-  lerpChartTheme,
-  resolveChartTheme,
-  resolveRegionBox,
-  resolveYScale,
-  seriesPoints,
-  type ChartConfig,
-  type ChartTheme,
-  type LineSeries,
-  type PlotRegion,
-  type RegionBox,
-} from "./shared"
-import { resolveXScale, type XScale } from "./x-scale"
-import { asCommand, formatNumber, hold, sequence as sequenceOf, together } from "@motionscript/sdk/component"
-
-export interface LineChartProps extends Node2DProps {
-  /** One row per sample — a plain record of field name to value. */
-  data: DataRecord[]
-  /**
-   * Key into each row for its x value, shared by every series. Named `xField`
-   * rather than `x` because every node already has an `x` — its position.
-   */
-  xField: string
-  /** One polyline per entry: which field it plots, its legend `label`, its `fill`. */
-  series: LineSeries[]
-  /** X-axis data domain: caption, scale range, and tick placement. */
-  xAxis?: AxisDomainConfig
-  /** Y-axis data domain: caption, scale range, and tick placement. */
-  yAxis?: AxisDomainConfig
-  /**
-   * A slice of the plot to spotlight, in **data units**. Dashed rules mark the
-   * bounded edges and every series fades outside the box — see
-   * {@link LineChart.spotlightRegion}, which animates the same thing. `null`
-   * (the default) is no region.
-   */
-  region?: PlotRegion | null
-  /**
-   * The chart's visual theme — series palette, axis text/grid/gutters, plot
-   * panel paint, and legend styling. Every branch is optional and deep-merged
-   * onto {@link DEFAULT_CHART_THEME}, so pass only what you want to override.
-   */
-  theme?: ChartTheme
-  /** Whether the legend row below the plot is drawn at all. */
-  showLegend?: boolean
-}
-
-/**
- * Headroom above the plot, in px.
- *
- * Two jobs, and the second is why it is real padding on the composition rather
- * than a number the point-mapping math imagines: a series peaking at `yMax`
- * isn't flush to the top edge, **and** the top y-marker — which is centred on
- * that top grid line — has somewhere to be. Without it the marker's upper half
- * is drawn above the chart's own box, outside the rectangle the editor draws
- * around the node.
- */
-const TOP_HEADROOM = 24
-
-/**
- * The argument every per-series command takes: an index into `series`. Its own
- * kind rather than `number` so a host can offer the series by name.
- */
-const SERIES_ARG = { key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }
-
-/** How far the legend starts below its slot when it enters, in px. */
-const LEGEND_SLIDE = 20
-
-/**
- * The two signals the region call-out is made of, as a props type for the
- * commands that move them.
- *
- * Written out rather than reusing `LineChartProps` because the pair is what
- * those commands actually touch, and because `regionReveal` is a signal of the
- * chart's own rather than part of its authored props.
- */
-type RegionState = { region: PlotRegion | null; regionReveal: number }
-
-/** The axis domains {@link LineChart.zoomTo} and {@link LineChart.resetZoom} move. */
-type AxisState = { xAxis: AxisDomainConfig; yAxis: AxisDomainConfig }
-
-/** Both axes' domains with their ranges and ticks resolved. */
-type Domains = { x: AxisDomainConfig; y: AxisDomainConfig }
-
-/**
- * How {@link LineChart.enter} divides its duration between its three beats: the
- * axes arriving, the lines tracing, and the legend coming up. Shares of the
- * whole, so they must sum to 1 — the entrance takes exactly the time it was
- * given (see the note on `enter`).
- */
-const AXES_SHARE = 0.35
-const LINES_SHARE = 0.5
-const LEGEND_SHARE = 0.15
-
-/**
- * A multi-series line chart, composed from five independent parts rather than
- * one monolithic draw:
- *
- * - {@link ChartCanvas} — the plot panel with a two-way grid, under everything.
- * - {@link VerticalAxis} / {@link HorizontalAxis} — columns/rows of real text
- *   markers that stagger in, each carrying its own axis caption.
- * - {@link ChartRegion} — the optional call-out marking a spotlit slice of the
- *   plot: dashed rules on its bounded edges, and every series faded outside it.
- * - {@link ChartLine} (one per series) — the traced polylines over the canvas.
- * - {@link ChartLegend} — a row of entries below the chart, one per series.
- *
- * The parts are laid out from this node's `layoutBounds`: a left gutter for the
- * vertical axis, a bottom gutter for the horizontal axis, the plot filling
- * what's left, and the legend row beneath the whole chart. Every child's
- * position/size is bound reactively, so the chart re-flows if its box changes,
- * and the series lines read the same resolved scales as the axes, so points land
- * exactly on their markers.
- *
- * **Resting state is the finished chart.** Unlike the standalone component this
- * was ported from, nothing is built hidden: the studio paints a node's Initial
- * state on a paused canvas, and a chart that only appeared once a command had
- * run would be edited blind. {@link enter} arms every part back to its
- * pre-entrance state before animating, so the entrance itself is unchanged.
- *
- * Past the entrance, three things move the chart around:
- * {@link showSeries}/{@link hideSeries}/{@link spotlightSeries} pick out a
- * *series*, {@link spotlightRegion} marks a *slice of the plot* without changing
- * the scale, and {@link zoomTo} rescales the axes so a slice fills the plot. The
- * last two take the same {@link PlotRegion} and compose — a spotlit region
- * resolves against the live scales, so it travels with a zoom.
- */
-@node({
-  key: "lineChart",
-  parentKey: "node",
-  forkable: true,
-  layout: {
-    children: "freeform",
-    defaultWidthMode: "fixed",
-    defaultHeightMode: "fixed",
-    acceptsChildren: true,
-  },
-  seed: {
-    width: 760,
-    height: 460,
-  },
-})
-export class LineChart extends Node2D<LineChartProps> {
-  @property({ default: () => [] as DataRecord[], kind: "dataset" }) declare data: DataRecord[]
-  @property({ default: "" }) declare xField: string
-  @property({ default: () => [] as LineSeries[], kind: "series" }) declare series: LineSeries[]
-  /**
-   * X/Y-axis data domain (label/range/ticks), tweenable and mappable like
-   * `theme`: the mapper merges a partial input onto the previous resolved
-   * domain (leaving `range`/`ticks` `undefined` — the auto-derive signal — on
-   * first resolution), and the tween interpolates them numerically, so
-   * `chart.to({ yAxis: { range: [0, 10] } }, 1)` smoothly rescales the plotted
-   * lines. Like `theme`, the axis *label* text is captured once at construction.
-   */
-  @property({
-    default: {},
-    mapper: resolveAxisDomain,
-    tween: lerpAxisDomain,
-  })
-  declare xAxis: AxisDomainConfig
-  @property({
-    default: {},
-    mapper: resolveAxisDomain,
-    tween: lerpAxisDomain,
-  })
-  declare yAxis: AxisDomainConfig
-  /**
-   * The chart's visual theme, tweenable and mappable like a `stroke`/`fill`
-   * prop: the mapper merges the author's partial input onto the previous
-   * resolved theme (or {@link DEFAULT_CHART_THEME} the first time) and resolves
-   * every leaf; the tween interpolates two resolved themes leaf-by-leaf, so
-   * `chart.to({ theme: next }, 1)` animates smoothly.
-   */
-  @property({
-    default: DEFAULT_CHART_THEME,
-    mapper: resolveChartTheme,
-    tween: lerpChartTheme,
-  })
-  declare theme: ChartTheme
-  /**
-   * The spotlit slice of the plot in data units, or `null` for none. Held as a
-   * plain reactive value rather than a tweened one: the box itself snaps, and
-   * the *animation* is {@link regionReveal} drawing the rules on and the lines
-   * dimming outside it.
-   */
-  @property({ default: null }) declare region: PlotRegion | null
-  /**
-   * How far the {@link region} call-out is drawn in, `[0, 1]` — the single
-   * signal behind both halves of the effect: the rules grow out and the wash
-   * fades up as it climbs, while every line's out-of-region stretch fades from
-   * full down to the theme's `region.dimOpacity`. At 0 a chart with a `region`
-   * set looks exactly like one without.
-   */
-  @property({ default: 0 }) declare regionReveal: number
-  /**
-   * Read once, in the constructor, like `series`: the legend is a part the
-   * chart builds or doesn't, so a change reaches it by rebuilding the node.
-   */
-  @property({ default: true, animatable: false }) declare showLegend: boolean
-
-  // ---- Part handles (built in the constructor) --------------------------
-  private vAxis: VerticalAxis
-  private hAxis: HorizontalAxis
-  /** The plot panel — the box the grid, the lines and the region all share. */
-  private plotRect: Rect
-  private legend: ChartLegend | null = null
-  private lines: ChartLine[] = []
-
-  /**
-   * `this.theme` read back through its *resolved* shape: the property's declared
-   * type is the loose author-facing {@link ChartTheme} (so a partial theme is
-   * accepted), but the mapper always stores the fully-resolved
-   * {@link ChartConfig} at runtime — the same loose-declared/resolved-stored
-   * idiom as a shape's `fill`/`stroke`.
-   */
-  private get resolvedTheme(): ChartConfig {
-    return this.theme as unknown as ChartConfig
-  }
-
-  // ---- Derived scales ---------------------------------------------------
-
-  /** Fallback marker count when neither axis's ticks are given. */
-  private static readonly DEFAULT_MARKERS = 5
-
-  /**
-   * What the x column *is* — a number, an instant, or a place in the file — and
-   * with it how each row is positioned, ticked and captioned. See `x-scale.ts`.
-   */
-  private get xColumn(): XScale {
-    return resolveXScale(this.data, this.xField, this.xAxis.format)
-  }
-
-  private get xScale(): Range {
-    return this.xAxis.range ?? this.xColumn.extent
-  }
-
-  private get yScale(): Range {
-    // Auto-ranging steps into one fewer segment than the intended marker count
-    // — the explicit ticks' count when given, else the default — so the tidy
-    // bounds still frame the ticks the axis draws.
-    const divisions =
-      (this.yAxis.ticks?.length ?? LineChart.DEFAULT_MARKERS) - 1
-    return resolveYScale(this.data, this.series, this.yAxis.range, divisions)
-  }
-
-  /** The vertical axis ticks: the explicit ones, else five across the scale. */
-  private get resolvedYMarkers(): number[] {
-    return (
-      this.yAxis.ticks ??
-      markerValues(this.yScale, LineChart.DEFAULT_MARKERS - 1)
-    )
-  }
-
-  /**
-   * The horizontal axis ticks: the explicit ones, else five across the scale.
-   *
-   * Asked of the column rather than spaced evenly, because only a numeric column
-   * has round numbers between its samples. On a month column, five evenly spaced
-   * values land two-thirds of the way through four different months; the ticks
-   * a reader wants are Jan/Apr/Jul/Oct/Dec, which are rows.
-   */
-  private get resolvedXMarkers(): number[] {
-    return (
-      this.xAxis.ticks ??
-      this.xColumn.ticks(this.xScale, LineChart.DEFAULT_MARKERS - 1)
-    )
-  }
-
-  // ---- Plot geometry ------------------------------------------------------
-
-  /**
-   * The plot panel's size, **as laid out**.
-   *
-   * This used to be computed: six constants estimating what the axis gutters and
-   * the legend row would take, subtracted from the node's box. The estimate was
-   * never the layout — the vertical axis is `width: "hug"`, so its real width is
-   * whatever its widest marker needs — and everything downstream inherited the
-   * gap. The grid is drawn by {@link ChartCanvas} across its *own* allocation,
-   * while the lines were mapped across the estimate, so a series sat a few
-   * percent off the grid line it was supposed to touch, silently and by an
-   * amount that changed with the theme.
-   *
-   * Asking the panel is exact by construction and cannot drift: the lines, the
-   * region rules and the grid all resolve against one box, and it is the box
-   * they are drawn in. Zero until the first layout pass, like any other
-   * `layoutBounds` read — the bindings that call this re-run on the next frame.
-   */
-  private plotSize(): { width: number; height: number } {
-    const { width, height } = this.plotRect.layoutBounds
-    return { width, height }
-  }
-
-  /**
-   * Map one series' data points into the plot's **centred** pixel space (origin
-   * at the plot centre, y-up) — the local frame of the clip/line box that fills
-   * the plot. x runs `[-w/2, +w/2]`, y runs `[-h/2, +h/2]`.
-   */
-  private seriesPixels(index: number): Vector2[] {
-    const s = this.series[index]
-    if (!s) return []
-    const points = seriesPoints(this.data, this.xColumn, s)
-    if (points.length === 0) return []
-    const { width: w, height: h } = this.plotSize()
-    const [xMin, xMax] = this.xScale
-    const [yMin, yMax] = this.yScale
-    // Plot centre is the origin; map the data fraction to [-half, +half].
-    const xToPx = (x: number) =>
-      xMax <= xMin ? 0 : ((x - xMin) / (xMax - xMin) - 0.5) * w
-    const yToPx = (y: number) =>
-      yMax <= yMin ? 0 : ((y - yMin) / (yMax - yMin) - 0.5) * h
-    // `seriesPoints` already sorted them along x.
-    return points.map(([x, y]) => ({ x: xToPx(x), y: yToPx(y) }))
-  }
-
-  /**
-   * {@link region} mapped into the plot's **centred** pixel space — the same
-   * frame {@link seriesPixels} returns, so the region's rules and each line's
-   * clip resolve against one box from one place. Reads the live scales, so it
-   * re-maps when `xAxis`/`yAxis` tween.
-   */
-  /**
-   * Whether a call-out is authored at all — the question {@link enter} and
-   * {@link spotlightRegion} branch on.
-   *
-   * Deliberately **not** `hasRegion(this.regionBox())`, which they used to ask.
-   * That resolves the region into pixels, so it answers "and has the chart been
-   * laid out yet" as well, and comes back false for a perfectly real region on a
-   * chart that has not been measured. A generator never noticed, because it only
-   * ever ran mid-playback; a command is *built* before the first layout pass, and
-   * would have quietly dropped the region beat every time.
-   *
-   * What is left once the pixels are taken out is the same test
-   * {@link resolveRegionBox} applies before it maps anything: a region bounding
-   * *neither* axis is not a call-out, so `{}` counts as none exactly as `null`
-   * does.
-   */
-  private hasCallout(): boolean {
-    const region = this.region
-    return region != null && (region.x !== undefined || region.y !== undefined)
-  }
-
-  private regionBox(): RegionBox {
-    const { width: w, height: h } = this.plotSize()
-    // The region lives in the plot's own centred frame, the same one
-    // seriesPixels maps its points into.
-    return resolveRegionBox(
-      this.region,
-      { left: -w / 2, right: w / 2, bottom: -h / 2, top: h / 2 },
-      this.xScale,
-      this.yScale
-    )
-  }
-
-  // ---- Build ------------------------------------------------------------
-
-  constructor(props?: NodeConfig<LineChart, LineChartProps>) {
-    super(props)
-
-    // The whole chart is composed from plain props/`data` — no context needed,
-    // so the parts are built here (super() applied the props above).
-    //
-    // Every theme/axis-derived prop below that a *leaf* drawing part reads live
-    // in `renderSelf` every frame — the canvas's fill/grid/extent, the border's
-    // stroke, each line's stroke/points — is passed as a closure, not a one-time
-    // snapshot, so `chart.to({ theme })` and `chart.to({ yAxis: { range } })`
-    // genuinely animate the panel, grid, border, and plotted lines. The two axes
-    // compose their child text nodes *once* (the marker count is fixed at
-    // construction) but bind each marker's caption and position to the live
-    // range/ticks, so a rescale re-labels and re-places the row as it tweens.
-    const enabled = this.series.map((s) => s.enabled ?? true)
-    const showLegend = this.showLegend !== false
-
-    this.vAxis = new VerticalAxis({
-      // Bound, not snapshotted — this is the half of a rescale the axis owns.
-      // The marker *count* is still read once (it fixes how many text nodes get
-      // built), which is why `zoomTo` keeps the count constant.
-      range: () => this.yScale,
-      markers: () => this.resolvedYMarkers,
-      axis: () => this.resolvedTheme.yAxis,
-      label: this.yAxis.label ?? "",
-      width: "hug",
-      height: "fill",
-    })
-    // The y axis is always numbers, so its format is simply the pattern.
-    this.vAxis.labelFor = (value) =>
-      this.yAxis.format === undefined
-        ? formatMarker(value)
-        : formatNumber(value, this.yAxis.format)
-
-    this.hAxis = new HorizontalAxis({
-      range: () => this.xScale,
-      markers: () => this.resolvedXMarkers,
-      axis: () => this.resolvedTheme.xAxis,
-      label: this.xAxis.label ?? "",
-      width: "fill",
-      height: "hug",
-    })
-    // A tick on a month or category column is captioned with the cell it came
-    // out of — `Jan`, not the instant it parsed to. Assigned rather than passed:
-    // see the note on the field.
-    this.hAxis.labelFor = (value) => this.xColumn.label(value)
-
-    this.lines = this.series.map(
-      (s, i) =>
-        new ChartLine({
-          points: () => this.seriesPixels(i),
-          stroke: () => resolveSeriesStroke(this.resolvedTheme.seriesStyles, s, i),
-          enabled: enabled[i],
-          // Each line clips itself against the same box the rules are drawn
-          // from, so the dim/bright boundary can't drift from the dashes.
-          spotlight: () => this.regionBox(),
-          // Ramped by the same reveal that draws the rules, so at reveal 0 the
-          // line is uniform and the region invisible — one signal, both halves.
-          dimOpacity: () =>
-            1 - (1 - this.resolvedTheme.region.dimOpacity) * this.regionReveal,
-        })
-    )
-
-    if (showLegend) {
-      this.legend = new ChartLegend({
-        series: this.series,
-        // The kit's legend paints a swatch, not a line, so the chart hands it
-        // the *colour* each stroke resolves to rather than the stroke itself —
-        // which is also what lets a bar chart's fill palette drive the same row.
-        swatches: () =>
-          this.series.map((s, i) =>
-            resolveSeriesFill(this.resolvedTheme.seriesStyles, s, i)
-          ),
-        legend: () => this.resolvedTheme.legend,
-      })
-    }
-
-    this.plotRect = new Rect({
-      clip: true,
-      children: [
-        new ChartCanvas({
-          fill: () => this.resolvedTheme.plotArea.fill,
-          shadow: () => this.resolvedTheme.plotArea.shadow,
-          xGridStroke: () => this.resolvedTheme.xAxis.lineStyle,
-          yGridStroke: () => this.resolvedTheme.yAxis.lineStyle,
-          // A grid line under every axis marker; the canvas maps the marker
-          // values through the extents and skips the edges.
-          xMarkers: () => this.resolvedXMarkers,
-          yMarkers: () => this.resolvedYMarkers,
-          xExtent: () => this.xScale,
-          yExtent: () => this.yScale,
-        }),
-        // Region wash + dashed rules: over the grid, under the lines, so a
-        // spotlit stretch of a series isn't tinted by the highlight meant to
-        // pick it out.
-        new ChartRegion({
-          box: () => this.regionBox(),
-          stroke: () => this.resolvedTheme.region.stroke,
-          fill: () => this.resolvedTheme.region.fill,
-          reveal: () => this.regionReveal,
-        }),
-        ...this.lines,
-        new ChartBorder({
-          stroke: () => this.resolvedTheme.plotArea.stroke,
-        }),
-      ],
-    })
-
-    // Invisible twin of the vertical axis, reserving the same left gutter under
-    // the plot so the horizontal axis starts at the plot's left edge rather than
-    // the chart's.
-    const gutterSpacer = new VerticalAxis({
-      opacity: 0,
-      range: () => this.yScale,
-      markers: () => this.resolvedYMarkers,
-      axis: () => this.resolvedTheme.yAxis,
-      label: this.yAxis.label ?? "",
-      width: "hug",
-      height: 0,
-    })
-
-    const below: Node2D[] = [this.hAxis]
-    if (this.legend) below.push(this.legend)
-
-    this.add(
-      new Rect({ flow: "vertical",
-        width: "fill",
-        height: "fill",
-        // See {@link TOP_HEADROOM}: the plot's top grid line is the one place a
-        // marker would otherwise be drawn outside the chart's own box.
-        padding: { top: TOP_HEADROOM },
-        children: [
-          new Rect({ flow: "horizontal",
-            height: "fill",
-            width: "fill",
-            children: [this.vAxis, this.plotRect],
-          }),
-          new Rect({ flow: "horizontal",
-            width: "fill",
-            children: [
-              gutterSpacer,
-              new Rect({ flow: "vertical", width: "fill", gap: 20, children: below }),
-            ],
-          }),
-        ],
-      })
-    )
-  }
-
-  // ---- Orchestrated entrance --------------------------------------------
-
-  /**
-   * Prime every part at its pre-entrance state — axis markers shifted and
-   * transparent, lines untraced, legend dropped and transparent.
-   *
-   * Called by {@link enter} before its first frame so nothing flashes ahead of
-   * its beat. Idempotent, and public so a scene can hide a chart ahead of time
-   * without starting the entrance.
-   */
-  arm(): void {
-    this.vAxis.arm()
-    this.hAxis.arm()
-    for (const line of this.lines) line.set({ progress: 0 })
-    this.legend?.set({ opacity: 0, y: -LEGEND_SLIDE })
-  }
-
-  /**
-   * Animate the whole chart in: the two axes stagger their markers in (vertical
-   * bottom-to-top, horizontal left-to-right), the series lines trace
-   * left-to-right, and the legend fades up last.
-   *
-   * `duration` is the **whole** entrance. The phases below are shares of it, not
-   * multiples — a command that declares 1.4 seconds has to take 1.4 seconds,
-   * because that is the slot the timeline lays out for it, the length its
-   * parallel siblings are timed against, and its contribution to the scene's own
-   * duration. (The component this was ported from scaled every phase *off* the
-   * line trace and let the total fall where it may, which came out around 3×.)
-   *
-   * A chart authored with a `region` lands its call-out last, over lines that
-   * have already traced — the same order a scene would get by calling
-   * {@link spotlightRegion} right after this — and that beat comes out of the
-   * same budget.
-   */
-  @command()
-  enter(
-    args: CommandArgs<Record<string, never>> & { duration: number }
-  ): Command<Record<string, never>> {
-    const duration = args.duration
-    const easing = args.easing ?? easeOut()
-    this.arm()
-
-    const revealing = this.hasCallout() && this.regionReveal === 0
-    // The region call-out, when there is one, takes the last quarter.
-    const body = revealing ? duration * 0.75 : duration
-
-    // The same three phases, in the same order and with the same shares — placed
-    // at their offsets rather than sequenced by a generator, so the whole
-    // entrance can be asked what it looks like at a time. Each part writes to its
-    // own node (the axes, the lines, the legend), which is why these compose as
-    // steppers rather than as merged props.
-    const axes = together(
-      this.vAxis.enter({ data: { slide: 24 }, duration: body * AXES_SHARE, easing }),
-      this.hAxis.enter({ data: { slide: 24 }, duration: body * AXES_SHARE, easing })
-    )
-    const lines = together(
-      ...this.lines.map((line) => line.enter({ duration: body * LINES_SHARE, easing }))
-    )
-    const legend = this.legend
-      ? [this.legend.to({ data: { opacity: 1, y: 0 }, duration: body * LEGEND_SHARE, easing })]
-      : []
-
-    const phases = sequenceOf(axes, lines, ...legend)
-
-    return asCommand(
-      revealing
-        ? sequenceOf(
-          phases,
-          // Typed to what it writes rather than to `LineChartProps`: `regionReveal`
-          // is a signal of the chart's own, not part of its authored props.
-          this.command<{ regionReveal: number }>(
-            (t) => ({ regionReveal: t }),
-            duration * 0.25,
-            easing
-          )
-        )
-        : phases,
-      duration
-    )
-  }
-
-  // ---- Region spotlight --------------------------------------------------
-
-  /**
-   * Spotlight a rectangular slice of the plot given in **data units**: dashed
-   * rules draw themselves onto each bounded edge while every series fades
-   * outside the box and stays full inside it.
-   *
-   * Either axis alone is a band — `{ x: [80, 100] }` picks out the last fifth
-   * across all series, `{ y: [8, 10] }` a value band across the whole width —
-   * and both together a box. The unbounded axis spans the plot and draws no
-   * rule, since there's no data bound there to mark.
-   *
-   * Calling it while another region is already up cross-fades: the old call-out
-   * retracts, then the new one draws in, each over half `duration`.
-   *
-   * Both the call-out's shape and its draw-on are plain signals — `region` and
-   * {@link regionReveal} — so the whole thing is a function of `t`, including
-   * the swap: which region is up is a step at the halfway point rather than an
-   * effect that has to have happened.
-   */
-  @command({
-    args: [
-      // One argument, two controls: the method takes a `PlotRegion`, so the x
-      // and y spans a host draws are declared inside it.
-      {
-        key: "region", kind: "region", properties: {
-          x: { kind: "range", default: true, defaultMin: 0, defaultMax: 100 },
-          y: { kind: "range", default: false, defaultMin: 0, defaultMax: 100 },
-        },
-      },
-    ],
-  })
-  spotlightRegion(
-    args: CommandArgs<{ region: PlotRegion }> & { duration?: number }
-  ): Command<RegionState> {
-    const region = LineChart.regionArg(args.data)
-    const duration = args.duration ?? 0.5
-    const easing = args.easing ?? easeOut()
-    const from = this.regionReveal
-    const previous = this.region
-
-    // A region bounding neither axis is no call-out: spotlighting it is a clear.
-    if (region.x === undefined && region.y === undefined) {
-      return this.clearRegion({ duration, easing })
-    }
-
-    // Nothing up yet: the region is set from the first frame and just draws on.
-    if (from <= 0 || !this.hasCallout()) {
-      return this.command<RegionState>(
-        (t) => ({ region, regionReveal: from + (1 - from) * t }),
-        duration,
-        easing
-      )
-    }
-
-    // Something already up: retract it first so the rules don't jump across the
-    // plot mid-draw. Each half eases on its own — which is why the easing is
-    // applied here rather than handed to `animate`, whose easing would shape the
-    // pair as one curve and leave both halves crawling past the seam.
-    return this.command<RegionState>(
-      (t) =>
-        t < 0.5
-          ? { region: previous, regionReveal: from * (1 - easing(t * 2)) }
-          : { region, regionReveal: easing(t * 2 - 1) },
-      duration
-    )
-  }
-
-  /**
-   * Drop the region call-out — the rules retract, the wash fades, and every
-   * series comes back to full across its whole length. A no-op when nothing is
-   * spotlit.
-   */
-  @command()
-  clearRegion(
-    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
-  ): Command<RegionState> {
-    const duration = args.duration ?? 0.5
-    const easing = args.easing ?? easeOut()
-    const from = this.regionReveal
-
-    if (from === 0) {
-      // Nothing to retract, but the call still takes its slot: in the studio a
-      // command's duration is what the timeline lays out and what parallel
-      // siblings are timed against, so a no-op that took no frames would pull
-      // everything after it forward. Same reason for `zoomTo`/`resetZoom` below.
-      return this.command<RegionState>(
-        () => ({ region: null, regionReveal: 0 }),
-        duration
-      )
-    }
-
-    // `region` is left alone until the retraction lands — cleared at `t === 1`
-    // rather than up front, or there would be nothing left to retract.
-    return this.command<RegionState>(
-      (t) => (t >= 1 ? { region: null, regionReveal: 0 } : { regionReveal: from * (1 - t) }),
-      duration,
-      easing
-    )
-  }
-
-  // ---- Zoom --------------------------------------------------------------
-
-  /**
-   * The domain to come back to, captured the first time {@link zoomTo} runs so a
-   * later {@link resetZoom} restores the chart as authored — including ticks
-   * that were auto-derived rather than given, which the props alone don't
-   * record. Cleared by {@link resetZoom}, so a second zoom captures wherever the
-   * chart genuinely rests then.
-   */
-  private home: Domains | null = null
-
-  /**
-   * The `region` a document handed a command, or `{}`. A command is added
-   * before its arguments are filled in, so an unstated region is ordinary input
-   * rather than a malformed one.
-   */
-  private static regionArg(data: { region?: PlotRegion | null } | undefined): PlotRegion {
-    const region = data?.region
-    return region != null && typeof region === "object" ? region : {}
-  }
-
-  /** A range read as a span, whichever way round the author wrote it. */
-  private static span([a, b]: Range): Range {
-    return a <= b ? [a, b] : [b, a]
-  }
-
-  /**
-   * Rescale an axis to `range`, keeping the tick *count* it already has — the
-   * axis tween interpolates ticks pairwise by index, so a constant count lets
-   * each marker slide from its old value to its new one instead of the row
-   * popping.
-   */
-  private static rescale(range: Range, ticks: number[]): AxisDomainConfig {
-    const span = LineChart.span(range)
-    const count = Math.max(2, ticks.length)
-    return { range: span, ticks: markerValues(span, count - 1) }
-  }
-
-  /**
-   * Zoom the plot to a slice of itself, given in **data units**: the named axes
-   * rescale so that slice fills the plot, the grid and both marker rows
-   * following the new scale, and every series re-tracing itself into the new
-   * frame. All of it tweens, so the move reads as a camera push rather than a
-   * cut.
-   *
-   * An **omitted axis is left as it is** rather than being fitted to what's
-   * visible — so a zoom is exactly what was asked for, and two calls compose
-   * predictably. A spotlit region, if one is up, follows the zoom: it resolves
-   * against the same live scales, so its rules stay on their data bounds.
-   */
-  @command({
-    args: [
-      // One argument, two controls: the method takes a `PlotRegion`, so the x
-      // and y spans a host draws are declared inside it.
-      {
-        key: "region", kind: "region", properties: {
-          x: { kind: "range", default: true, defaultMin: 0, defaultMax: 100 },
-          y: { kind: "range", default: false, defaultMin: 0, defaultMax: 100 },
-        },
-      },
-    ],
-  })
-  zoomTo(
-    args: CommandArgs<{ region: PlotRegion }> & { duration?: number }
-  ): Command<AxisState> {
-    const region = LineChart.regionArg(args.data)
-    const duration = args.duration ?? 0.8
-    const easing = args.easing ?? easeOut()
-    if (!region.x && !region.y) return this.command<AxisState>(() => ({}), duration)
-
-    // Captured *before* the first zoom moves it.
-    const from = this._domains()
-    this.home ??= from
-
-    return this._tweenAxes(
-      from,
-      {
-        ...(region.x && { x: { ...from.x, ...LineChart.rescale(region.x, from.x.ticks!) } }),
-        ...(region.y && { y: { ...from.y, ...LineChart.rescale(region.y, from.y.ticks!) } }),
-      },
-      duration,
-      easing
-    )
-  }
-
-  /**
-   * Pull back out to the domain the chart was authored with — the mirror of
-   * {@link zoomTo}, and a no-op if it was never zoomed.
-   */
-  @command()
-  resetZoom(
-    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
-  ): Command<AxisState> {
-    const duration = args.duration ?? 0.8
-    const easing = args.easing ?? easeOut()
-    const home = this.home
-    if (!home) return this.command<AxisState>(() => ({}), duration)
-
-    // Cleared here rather than once the move lands. Nothing reads `home` while
-    // it runs, and a value has no "after" to clear it in — what matters is that
-    // the *next* `zoomTo` captures wherever the chart genuinely rests by then,
-    // and both this and its capture happen as the command list is walked.
-    this.home = null
-    return this._tweenAxes(this._domains(), home, duration, easing)
-  }
-
-  // ---- Per-series -------------------------------------------------------
-
-  /**
-   * Show series `index`: **trace** its line in left-to-right — the same draw as
-   * {@link enter}, not an opacity fade — in lockstep with its legend entry
-   * growing in.
-   *
-   * `enabled` is set as part of the command's own value rather than before it,
-   * so the line is drawable for every `t` the trace covers and undrawn outside
-   * it — which is what makes arriving here backwards show the same thing as
-   * arriving forwards.
-   */
-  @command({ args: [SERIES_ARG] })
-  showSeries(
-    args: CommandArgs<{ seriesIndex: number }> & { duration?: number }
-  ): Command<Record<string, never>> {
-    const index = args.data?.seriesIndex ?? 0
-    const duration = args.duration ?? 0.35
-    const easing = args.easing ?? easeOut()
-    const line = this.lines[index]
-    if (!line) return asCommand(hold(duration))
-
-    return asCommand(
-      together(
-        line.enterFrom(0, duration, easing),
-        ...(this.legend ? [this.legend.showSeries({ data: { index }, duration, easing })] : [])
-      ),
-      duration
-    )
-  }
-
-  /**
-   * Hide series `index`: **retrace** its line back out (`progress` 1 → 0) as its
-   * legend entry shrinks away — the mirror of {@link showSeries}.
-   */
-  @command({ args: [SERIES_ARG] })
-  hideSeries(
-    args: CommandArgs<{ seriesIndex: number }> & { duration?: number }
-  ): Command<Record<string, never>> {
-    const index = args.data?.seriesIndex ?? 0
-    const duration = args.duration ?? 0.35
-    const easing = args.easing ?? easeOut()
-    const line = this.lines[index]
-    if (!line) return asCommand(hold(duration))
-
-    return asCommand(
-      together(
-        line.enterFrom(1, duration, easing, 0),
-        ...(this.legend ? [this.legend.hideSeries({ data: { index }, duration, easing })] : [])
-      ),
-      duration
-    )
-  }
-
-  /**
-   * Fade out all other series — each line **and its legend entry** — to focus
-   * attention on `index`, which comes back to full. The legend dims in place
-   * (opacity only), so no entry moves and the row doesn't reflow.
-   */
-  @command({ args: [SERIES_ARG] })
-  spotlightSeries(
-    args: CommandArgs<{ seriesIndex: number }> & { duration?: number }
-  ): Command<Record<string, never>> {
-    const index = args.data?.seriesIndex ?? 0
-    const duration = args.duration ?? 0.35
-    const easing = args.easing ?? easeOut()
-    return asCommand(
-      together(
-        ...this.lines.map((line, i) =>
-          line.to({ data: { opacity: i === index ? 1 : SPOTLIGHT_DIM }, duration, easing })
-        ),
-        ...(this.legend
-          ? [this.legend.spotlightSeries({ data: { index }, duration, easing })]
-          : [])
-      ),
-      duration
-    )
-  }
-
-  /** Both axes as drawn, so an auto range or tick row is read back as itself. */
-  private _domains(): Domains {
-    return {
-      x: { ...this.xAxis, range: this.xScale, ticks: this.resolvedXMarkers },
-      y: { ...this.yAxis, range: this.yScale, ticks: this.resolvedYMarkers },
-    }
-  }
-
-  /** From a resolved `from`: the axis tween steps an auto side at the midpoint, which is a cut. */
-  private _tweenAxes(
-    from: Domains,
-    to: Partial<Domains>,
-    duration: number,
-    easing: EasingFunction
-  ): Command<AxisState> {
-    return this.command<AxisState>(
-      (t) => ({
-        ...(to.x && { xAxis: lerpAxisDomain(from.x, to.x, t) }),
-        ...(to.y && { yAxis: lerpAxisDomain(from.y, to.y, t) }),
-      }),
-      duration,
-      easing
-    )
-  }
-}
+import {
+  command,
+  node,
+  Node2D,
+  Rect,
+  easeOut,
+  property,
+  type Command,
+  type CommandArgs,
+  type DataRecord,
+  type EasingFunction,
+  type NodeConfig,
+  type Node2DProps,
+  type Vector2,
+} from "@motionscript/sdk"
+
+import { ChartBorder } from "../kit/chart-border"
+import { ChartCanvas } from "../kit/chart-canvas"
+import { ChartLegend } from "../kit/chart-legend"
+import { VerticalAxis } from "../kit/vertical-axis"
+import {
+  SPOTLIGHT_DIM,
+  formatMarker,
+  axisTweenTarget,
+  lerpAxisDomain,
+  markerStep,
+  markerValues,
+  resolveAxisDomain,
+  resolveSeriesFill,
+  resolveSeriesStroke,
+  type AxisDomainConfig,
+  type Range,
+} from "../kit/shared"
+import { ChartLine } from "./chart-line"
+import { ChartRegion } from "./chart-region"
+import { HorizontalAxis } from "./horizontal-axis"
+import {
+  DEFAULT_CHART_THEME,
+  lerpChartTheme,
+  resolveChartTheme,
+  resolveRegionBox,
+  resolveYScale,
+  seriesPoints,
+  type ChartConfig,
+  type ChartTheme,
+  type LineSeries,
+  type PlotRegion,
+  type RegionBox,
+} from "./shared"
+import { resolveXScale, type XScale } from "./x-scale"
+import { asCommand, formatNumber, hold, sequence as sequenceOf, together } from "@motionscript/sdk/component"
+
+export interface LineChartProps extends Node2DProps {
+  /** One row per sample — a plain record of field name to value. */
+  data: DataRecord[]
+  /**
+   * Key into each row for its x value, shared by every series. Named `xField`
+   * rather than `x` because every node already has an `x` — its position.
+   */
+  xField: string
+  /** One polyline per entry: which field it plots, its legend `label`, its `fill`. */
+  series: LineSeries[]
+  /** X-axis data domain: caption, scale range, and tick placement. */
+  xAxis?: AxisDomainConfig
+  /** Y-axis data domain: caption, scale range, and tick placement. */
+  yAxis?: AxisDomainConfig
+  /**
+   * A slice of the plot to spotlight, in **data units**. Dashed rules mark the
+   * bounded edges and every series fades outside the box — see
+   * {@link LineChart.spotlightRegion}, which animates the same thing. `null`
+   * (the default) is no region.
+   */
+  region?: PlotRegion | null
+  /**
+   * The chart's visual theme — series palette, axis text/grid/gutters, plot
+   * panel paint, and legend styling. Every branch is optional and deep-merged
+   * onto {@link DEFAULT_CHART_THEME}, so pass only what you want to override.
+   */
+  theme?: ChartTheme
+  /** Whether the legend row below the plot is drawn at all. */
+  showLegend?: boolean
+}
+
+/**
+ * Headroom above the plot, in px.
+ *
+ * Two jobs, and the second is why it is real padding on the composition rather
+ * than a number the point-mapping math imagines: a series peaking at `yMax`
+ * isn't flush to the top edge, **and** the top y-marker — which is centred on
+ * that top grid line — has somewhere to be. Without it the marker's upper half
+ * is drawn above the chart's own box, outside the rectangle the editor draws
+ * around the node.
+ */
+const TOP_HEADROOM = 24
+
+/**
+ * The argument every per-series command takes: an index into `series`. Its own
+ * kind rather than `number` so a host can offer the series by name.
+ */
+const SERIES_ARG = { key: "seriesIndex", kind: "series", default: 0, min: 0, step: 1 }
+
+/** How far the legend starts below its slot when it enters, in px. */
+const LEGEND_SLIDE = 20
+
+/**
+ * The two signals the region call-out is made of, as a props type for the
+ * commands that move them.
+ *
+ * Written out rather than reusing `LineChartProps` because the pair is what
+ * those commands actually touch, and because `regionReveal` is a signal of the
+ * chart's own rather than part of its authored props.
+ */
+type RegionState = { region: PlotRegion | null; regionReveal: number }
+
+/** The axis domains {@link LineChart.zoomTo} and {@link LineChart.resetZoom} move. */
+type AxisState = { xAxis: AxisDomainConfig; yAxis: AxisDomainConfig }
+
+/** Both axes' domains with their ranges and ticks resolved. */
+type Domains = { x: AxisDomainConfig; y: AxisDomainConfig }
+
+/**
+ * How {@link LineChart.enter} divides its duration between its three beats: the
+ * axes arriving, the lines tracing, and the legend coming up. Shares of the
+ * whole, so they must sum to 1 — the entrance takes exactly the time it was
+ * given (see the note on `enter`).
+ */
+const AXES_SHARE = 0.35
+const LINES_SHARE = 0.5
+const LEGEND_SHARE = 0.15
+
+/**
+ * A multi-series line chart, composed from five independent parts rather than
+ * one monolithic draw:
+ *
+ * - {@link ChartCanvas} — the plot panel with a two-way grid, under everything.
+ * - {@link VerticalAxis} / {@link HorizontalAxis} — columns/rows of real text
+ *   markers that stagger in, each carrying its own axis caption.
+ * - {@link ChartRegion} — the optional call-out marking a spotlit slice of the
+ *   plot: dashed rules on its bounded edges, and every series faded outside it.
+ * - {@link ChartLine} (one per series) — the traced polylines over the canvas.
+ * - {@link ChartLegend} — a row of entries below the chart, one per series.
+ *
+ * The parts are laid out from this node's `layoutBounds`: a left gutter for the
+ * vertical axis, a bottom gutter for the horizontal axis, the plot filling
+ * what's left, and the legend row beneath the whole chart. Every child's
+ * position/size is bound reactively, so the chart re-flows if its box changes,
+ * and the series lines read the same resolved scales as the axes, so points land
+ * exactly on their markers.
+ *
+ * **Resting state is the finished chart.** Unlike the standalone component this
+ * was ported from, nothing is built hidden: an editor paints a node's Initial
+ * state on a paused canvas, and a chart that only appeared once a command had
+ * run would be edited blind. {@link enter} arms every part back to its
+ * pre-entrance state before animating, so the entrance itself is unchanged.
+ *
+ * Past the entrance, three things move the chart around:
+ * {@link showSeries}/{@link hideSeries}/{@link spotlightSeries} pick out a
+ * *series*, {@link spotlightRegion} marks a *slice of the plot* without changing
+ * the scale, and {@link zoomTo} rescales the axes so a slice fills the plot. The
+ * last two take the same {@link PlotRegion} and compose — a spotlit region
+ * resolves against the live scales, so it travels with a zoom.
+ */
+@node({
+  key: "lineChart",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+    acceptsChildren: true,
+  },
+  seed: {
+    width: 760,
+    height: 460,
+  },
+})
+export class LineChart extends Node2D<LineChartProps> {
+  @property({ default: () => [] as DataRecord[], kind: "dataset" }) declare data: DataRecord[]
+  @property({ default: "" }) declare xField: string
+  @property({ default: () => [] as LineSeries[], kind: "series" }) declare series: LineSeries[]
+  /**
+   * X/Y-axis data domain (label/range/ticks), tweenable and mappable like
+   * `theme`: the mapper merges a partial input onto the previous resolved
+   * domain (leaving `range`/`ticks` `undefined` — the auto-derive signal — on
+   * first resolution), and the tween interpolates them numerically, so
+   * `chart.to({ yAxis: { range: [0, 10] } }, 1)` smoothly rescales the plotted
+   * lines. Like `theme`, the axis *label* text is captured once at construction.
+   */
+  @property({
+    default: {},
+    mapper: resolveAxisDomain,
+    tween: lerpAxisDomain,
+  })
+  declare xAxis: AxisDomainConfig
+  @property({
+    default: {},
+    mapper: resolveAxisDomain,
+    tween: lerpAxisDomain,
+  })
+  declare yAxis: AxisDomainConfig
+  /**
+   * The chart's visual theme, tweenable and mappable like a `stroke`/`fill`
+   * prop: the mapper merges the author's partial input onto the previous
+   * resolved theme (or {@link DEFAULT_CHART_THEME} the first time) and resolves
+   * every leaf; the tween interpolates two resolved themes leaf-by-leaf, so
+   * `chart.to({ theme: next }, 1)` animates smoothly.
+   */
+  @property({
+    default: DEFAULT_CHART_THEME,
+    mapper: resolveChartTheme,
+    tween: lerpChartTheme,
+  })
+  declare theme: ChartTheme
+  /**
+   * The spotlit slice of the plot in data units, or `null` for none. Held as a
+   * plain reactive value rather than a tweened one: the box itself snaps, and
+   * the *animation* is {@link regionReveal} drawing the rules on and the lines
+   * dimming outside it.
+   */
+  @property({ default: null }) declare region: PlotRegion | null
+  /**
+   * How far the {@link region} call-out is drawn in, `[0, 1]` — the single
+   * signal behind both halves of the effect: the rules grow out and the wash
+   * fades up as it climbs, while every line's out-of-region stretch fades from
+   * full down to the theme's `region.dimOpacity`. At 0 a chart with a `region`
+   * set looks exactly like one without.
+   */
+  @property({ default: 0 }) declare regionReveal: number
+  /**
+   * Read once, in the constructor, like `series`: the legend is a part the
+   * chart builds or doesn't, so a change reaches it by rebuilding the node.
+   */
+  @property({ default: true, animatable: false }) declare showLegend: boolean
+
+  // ---- Part handles (built in the constructor) --------------------------
+  private vAxis: VerticalAxis
+  private hAxis: HorizontalAxis
+  /** The plot panel — the box the grid, the lines and the region all share. */
+  private plotRect: Rect
+  private legend: ChartLegend | null = null
+  private lines: ChartLine[] = []
+
+  /**
+   * `this.theme` read back through its *resolved* shape: the property's declared
+   * type is the loose author-facing {@link ChartTheme} (so a partial theme is
+   * accepted), but the mapper always stores the fully-resolved
+   * {@link ChartConfig} at runtime — the same loose-declared/resolved-stored
+   * idiom as a shape's `fill`/`stroke`.
+   */
+  private get resolvedTheme(): ChartConfig {
+    return this.theme as unknown as ChartConfig
+  }
+
+  // ---- Derived scales ---------------------------------------------------
+
+  /** Fallback marker count when neither axis's ticks are given. */
+  private static readonly DEFAULT_MARKERS = 5
+
+  /**
+   * What the x column *is* — a number, an instant, or a place in the file — and
+   * with it how each row is positioned, ticked and captioned. See `x-scale.ts`.
+   */
+  private get xColumn(): XScale {
+    return resolveXScale(this.data, this.xField, this.xAxis.format)
+  }
+
+  private get xScale(): Range {
+    return this.xAxis.range ?? this.xColumn.extent
+  }
+
+  private get yScale(): Range {
+    // Auto-ranging steps into one fewer segment than the intended marker count
+    // — the explicit ticks' count when given, else the default — so the tidy
+    // bounds still frame the ticks the axis draws.
+    const divisions =
+      (this.yAxis.ticks?.length ?? LineChart.DEFAULT_MARKERS) - 1
+    return resolveYScale(this.data, this.series, this.yAxis.range, divisions)
+  }
+
+  /** The vertical axis ticks: the explicit ones, else five across the scale. */
+  private get resolvedYMarkers(): number[] {
+    return (
+      this.yAxis.ticks ??
+      markerValues(this.yScale, LineChart.DEFAULT_MARKERS - 1)
+    )
+  }
+
+  /**
+   * The horizontal axis ticks: the explicit ones, else five across the scale.
+   *
+   * Asked of the column rather than spaced evenly, because only a numeric column
+   * has round numbers between its samples. On a month column, five evenly spaced
+   * values land two-thirds of the way through four different months; the ticks
+   * a reader wants are Jan/Apr/Jul/Oct/Dec, which are rows.
+   */
+  private get resolvedXMarkers(): number[] {
+    return (
+      this.xAxis.ticks ??
+      this.xColumn.ticks(this.xScale, LineChart.DEFAULT_MARKERS - 1)
+    )
+  }
+
+  // ---- Plot geometry ------------------------------------------------------
+
+  /**
+   * The plot panel's size, **as laid out**.
+   *
+   * This used to be computed: six constants estimating what the axis gutters and
+   * the legend row would take, subtracted from the node's box. The estimate was
+   * never the layout — the vertical axis is `width: "hug"`, so its real width is
+   * whatever its widest marker needs — and everything downstream inherited the
+   * gap. The grid is drawn by {@link ChartCanvas} across its *own* allocation,
+   * while the lines were mapped across the estimate, so a series sat a few
+   * percent off the grid line it was supposed to touch, silently and by an
+   * amount that changed with the theme.
+   *
+   * Asking the panel is exact by construction and cannot drift: the lines, the
+   * region rules and the grid all resolve against one box, and it is the box
+   * they are drawn in. Zero until the first layout pass, like any other
+   * `layoutBounds` read — the bindings that call this re-run on the next frame.
+   */
+  private plotSize(): { width: number; height: number } {
+    const { width, height } = this.plotRect.layoutBounds
+    return { width, height }
+  }
+
+  /**
+   * Map one series' data points into the plot's **centred** pixel space (origin
+   * at the plot centre, y-up) — the local frame of the clip/line box that fills
+   * the plot. x runs `[-w/2, +w/2]`, y runs `[-h/2, +h/2]`.
+   */
+  private seriesPixels(index: number): Vector2[] {
+    const s = this.series[index]
+    if (!s) return []
+    const points = seriesPoints(this.data, this.xColumn, s)
+    if (points.length === 0) return []
+    const { width: w, height: h } = this.plotSize()
+    const [xMin, xMax] = this.xScale
+    const [yMin, yMax] = this.yScale
+    // Plot centre is the origin; map the data fraction to [-half, +half].
+    const xToPx = (x: number) =>
+      xMax <= xMin ? 0 : ((x - xMin) / (xMax - xMin) - 0.5) * w
+    const yToPx = (y: number) =>
+      yMax <= yMin ? 0 : ((y - yMin) / (yMax - yMin) - 0.5) * h
+    // `seriesPoints` already sorted them along x.
+    return points.map(([x, y]) => ({ x: xToPx(x), y: yToPx(y) }))
+  }
+
+  /**
+   * {@link region} mapped into the plot's **centred** pixel space — the same
+   * frame {@link seriesPixels} returns, so the region's rules and each line's
+   * clip resolve against one box from one place. Reads the live scales, so it
+   * re-maps when `xAxis`/`yAxis` tween.
+   */
+  /**
+   * Whether a call-out is authored at all — the question {@link enter} and
+   * {@link spotlightRegion} branch on.
+   *
+   * Deliberately **not** `hasRegion(this.regionBox())`, which they used to ask.
+   * That resolves the region into pixels, so it answers "and has the chart been
+   * laid out yet" as well, and comes back false for a perfectly real region on a
+   * chart that has not been measured. A generator never noticed, because it only
+   * ever ran mid-playback; a command is *built* before the first layout pass, and
+   * would have quietly dropped the region beat every time.
+   *
+   * What is left once the pixels are taken out is the same test
+   * {@link resolveRegionBox} applies before it maps anything: a region bounding
+   * *neither* axis is not a call-out, so `{}` counts as none exactly as `null`
+   * does.
+   */
+  private hasCallout(): boolean {
+    const region = this.region
+    return region != null && (region.x !== undefined || region.y !== undefined)
+  }
+
+  private regionBox(): RegionBox {
+    const { width: w, height: h } = this.plotSize()
+    // The region lives in the plot's own centred frame, the same one
+    // seriesPixels maps its points into.
+    return resolveRegionBox(
+      this.region,
+      { left: -w / 2, right: w / 2, bottom: -h / 2, top: h / 2 },
+      this.xScale,
+      this.yScale
+    )
+  }
+
+  // ---- Build ------------------------------------------------------------
+
+  constructor(props?: NodeConfig<LineChart, LineChartProps>) {
+    super(props)
+
+    // The whole chart is composed from plain props/`data` — no context needed,
+    // so the parts are built here (super() applied the props above).
+    //
+    // Every theme/axis-derived prop below that a *leaf* drawing part reads live
+    // in `renderSelf` every frame — the canvas's fill/grid/extent, the border's
+    // stroke, each line's stroke/points — is passed as a closure, not a one-time
+    // snapshot, so `chart.to({ theme })` and `chart.to({ yAxis: { range } })`
+    // genuinely animate the panel, grid, border, and plotted lines. The two axes
+    // compose their child text nodes *once* (the marker count is fixed at
+    // construction) but bind each marker's caption and position to the live
+    // range/ticks, so a rescale re-labels and re-places the row as it tweens.
+    const enabled = this.series.map((s) => s.enabled ?? true)
+    const showLegend = this.showLegend !== false
+
+    this.vAxis = new VerticalAxis({
+      // Bound, not snapshotted — this is the half of a rescale the axis owns.
+      // The marker *count* is still read once (it fixes how many text nodes get
+      // built), which is why `zoomTo` keeps the count constant.
+      range: () => this.yScale,
+      markers: () => this.resolvedYMarkers,
+      axis: () => this.resolvedTheme.yAxis,
+      label: this.yAxis.label ?? "",
+      width: "hug",
+      height: "fill",
+    })
+    // The y axis is always numbers, so its format is simply the pattern.
+    this.vAxis.labelFor = (value) =>
+      this.yAxis.format === undefined
+        ? formatMarker(value, markerStep(this.resolvedYMarkers))
+        : formatNumber(value, this.yAxis.format)
+
+    this.hAxis = new HorizontalAxis({
+      range: () => this.xScale,
+      markers: () => this.resolvedXMarkers,
+      axis: () => this.resolvedTheme.xAxis,
+      label: this.xAxis.label ?? "",
+      width: "fill",
+      height: "hug",
+    })
+    // A tick on a month or category column is captioned with the cell it came
+    // out of — `Jan`, not the instant it parsed to. Assigned rather than passed:
+    // see the note on the field.
+    this.hAxis.labelFor = (value) => this.xColumn.label(value)
+
+    this.lines = this.series.map(
+      (s, i) =>
+        new ChartLine({
+          points: () => this.seriesPixels(i),
+          stroke: () => resolveSeriesStroke(this.resolvedTheme.seriesStyles, s, i),
+          enabled: enabled[i],
+          // Each line clips itself against the same box the rules are drawn
+          // from, so the dim/bright boundary can't drift from the dashes.
+          spotlight: () => this.regionBox(),
+          // Ramped by the same reveal that draws the rules, so at reveal 0 the
+          // line is uniform and the region invisible — one signal, both halves.
+          dimOpacity: () =>
+            1 - (1 - this.resolvedTheme.region.dimOpacity) * this.regionReveal,
+        })
+    )
+
+    if (showLegend) {
+      this.legend = new ChartLegend({
+        series: this.series,
+        // The kit's legend paints a swatch, not a line, so the chart hands it
+        // the *colour* each stroke resolves to rather than the stroke itself —
+        // which is also what lets a bar chart's fill palette drive the same row.
+        swatches: () =>
+          this.series.map((s, i) =>
+            resolveSeriesFill(this.resolvedTheme.seriesStyles, s, i)
+          ),
+        legend: () => this.resolvedTheme.legend,
+      })
+    }
+
+    this.plotRect = new Rect({
+      clip: true,
+      children: [
+        new ChartCanvas({
+          fill: () => this.resolvedTheme.plotArea.fill,
+          shadow: () => this.resolvedTheme.plotArea.shadow,
+          xGridStroke: () => this.resolvedTheme.xAxis.lineStyle,
+          yGridStroke: () => this.resolvedTheme.yAxis.lineStyle,
+          // A grid line under every axis marker; the canvas maps the marker
+          // values through the extents and skips the edges.
+          xMarkers: () => this.resolvedXMarkers,
+          yMarkers: () => this.resolvedYMarkers,
+          xExtent: () => this.xScale,
+          yExtent: () => this.yScale,
+        }),
+        // Region wash + dashed rules: over the grid, under the lines, so a
+        // spotlit stretch of a series isn't tinted by the highlight meant to
+        // pick it out.
+        new ChartRegion({
+          box: () => this.regionBox(),
+          stroke: () => this.resolvedTheme.region.stroke,
+          fill: () => this.resolvedTheme.region.fill,
+          reveal: () => this.regionReveal,
+        }),
+        ...this.lines,
+        new ChartBorder({
+          stroke: () => this.resolvedTheme.plotArea.stroke,
+        }),
+      ],
+    })
+
+    // Invisible twin of the vertical axis, reserving the same left gutter under
+    // the plot so the horizontal axis starts at the plot's left edge rather than
+    // the chart's.
+    const gutterSpacer = new VerticalAxis({
+      opacity: 0,
+      range: () => this.yScale,
+      markers: () => this.resolvedYMarkers,
+      axis: () => this.resolvedTheme.yAxis,
+      label: this.yAxis.label ?? "",
+      width: "hug",
+      height: 0,
+    })
+
+    const below: Node2D[] = [this.hAxis]
+    if (this.legend) below.push(this.legend)
+
+    this.add(
+      new Rect({ flow: "vertical",
+        width: "fill",
+        height: "fill",
+        // See {@link TOP_HEADROOM}: the plot's top grid line is the one place a
+        // marker would otherwise be drawn outside the chart's own box.
+        padding: { top: TOP_HEADROOM },
+        children: [
+          new Rect({ flow: "horizontal",
+            height: "fill",
+            width: "fill",
+            children: [this.vAxis, this.plotRect],
+          }),
+          new Rect({ flow: "horizontal",
+            width: "fill",
+            children: [
+              gutterSpacer,
+              new Rect({ flow: "vertical", width: "fill", gap: 20, children: below }),
+            ],
+          }),
+        ],
+      })
+    )
+  }
+
+  // ---- Orchestrated entrance --------------------------------------------
+
+  /**
+   * Prime every part at its pre-entrance state — axis markers shifted and
+   * transparent, lines untraced, legend dropped and transparent.
+   *
+   * Called by {@link enter} before its first frame so nothing flashes ahead of
+   * its beat. Idempotent, and public so a scene can hide a chart ahead of time
+   * without starting the entrance.
+   */
+  arm(): void {
+    this.vAxis.arm()
+    this.hAxis.arm()
+    for (const line of this.lines) line.set({ progress: 0 })
+    this.legend?.set({ opacity: 0, y: -LEGEND_SLIDE })
+  }
+
+  /**
+   * Animate the whole chart in: the two axes stagger their markers in (vertical
+   * bottom-to-top, horizontal left-to-right), the series lines trace
+   * left-to-right, and the legend fades up last.
+   *
+   * `duration` is the **whole** entrance. The phases below are shares of it, not
+   * multiples — a command that declares 1.4 seconds has to take 1.4 seconds,
+   * because that is the slot the timeline lays out for it, the length its
+   * parallel siblings are timed against, and its contribution to the scene's own
+   * duration. (The component this was ported from scaled every phase *off* the
+   * line trace and let the total fall where it may, which came out around 3×.)
+   *
+   * A chart authored with a `region` lands its call-out last, over lines that
+   * have already traced — the same order a scene would get by calling
+   * {@link spotlightRegion} right after this — and that beat comes out of the
+   * same budget.
+   */
+  @command()
+  enter(
+    args: CommandArgs<Record<string, never>> & { duration: number }
+  ): Command<Record<string, never>> {
+    const duration = args.duration
+    const easing = args.easing ?? easeOut()
+    this.arm()
+
+    const revealing = this.hasCallout() && this.regionReveal === 0
+    // The region call-out, when there is one, takes the last quarter.
+    const body = revealing ? duration * 0.75 : duration
+
+    // The same three phases, in the same order and with the same shares — placed
+    // at their offsets rather than sequenced by a generator, so the whole
+    // entrance can be asked what it looks like at a time. Each part writes to its
+    // own node (the axes, the lines, the legend), which is why these compose as
+    // steppers rather than as merged props.
+    const axes = together(
+      this.vAxis.enter({ data: { slide: 24 }, duration: body * AXES_SHARE, easing }),
+      this.hAxis.enter({ data: { slide: 24 }, duration: body * AXES_SHARE, easing })
+    )
+    //
+    // A beat with nothing to do (a chart without a legend, or without series)
+    // still takes its share: the shares sum to the whole, and the beats after it
+    // land where they were laid out for.
+    const lines = together(
+      hold(body * LINES_SHARE),
+      ...this.lines.map((line) => line.enter({ duration: body * LINES_SHARE, easing }))
+    )
+    const legend = this.legend
+      ? this.legend.to({ data: { opacity: 1, y: 0 }, duration: body * LEGEND_SHARE, easing })
+      : hold(body * LEGEND_SHARE)
+
+    const phases = sequenceOf(axes, lines, legend)
+
+    return asCommand(
+      revealing
+        ? sequenceOf(
+          phases,
+          // Typed to what it writes rather than to `LineChartProps`: `regionReveal`
+          // is a signal of the chart's own, not part of its authored props.
+          this.command<{ regionReveal: number }>(
+            (t) => ({ regionReveal: t }),
+            duration * 0.25,
+            easing
+          )
+        )
+        : phases,
+      duration
+    )
+  }
+
+  // ---- Region spotlight --------------------------------------------------
+
+  /**
+   * Spotlight a rectangular slice of the plot given in **data units**: dashed
+   * rules draw themselves onto each bounded edge while every series fades
+   * outside the box and stays full inside it.
+   *
+   * Either axis alone is a band — `{ x: [80, 100] }` picks out the last fifth
+   * across all series, `{ y: [8, 10] }` a value band across the whole width —
+   * and both together a box. The unbounded axis spans the plot and draws no
+   * rule, since there's no data bound there to mark.
+   *
+   * Calling it while another region is already up cross-fades: the old call-out
+   * retracts, then the new one draws in, each over half `duration`.
+   *
+   * Both the call-out's shape and its draw-on are plain signals — `region` and
+   * {@link regionReveal} — so the whole thing is a function of `t`, including
+   * the swap: which region is up is a step at the halfway point rather than an
+   * effect that has to have happened.
+   */
+  @command({
+    args: [
+      // One argument, two controls: the method takes a `PlotRegion`, so the x
+      // and y spans a host draws are declared inside it.
+      {
+        key: "region", kind: "region", properties: {
+          x: { kind: "range", default: true, defaultMin: 0, defaultMax: 100 },
+          y: { kind: "range", default: false, defaultMin: 0, defaultMax: 100 },
+        },
+      },
+    ],
+  })
+  spotlightRegion(
+    args: CommandArgs<{ region: PlotRegion }> & { duration?: number }
+  ): Command<RegionState> {
+    const region = LineChart.regionArg(args.data)
+    const duration = args.duration ?? 0.5
+    const easing = args.easing ?? easeOut()
+    const from = this.regionReveal
+    const previous = this.region
+
+    // A region bounding neither axis is no call-out: spotlighting it is a clear.
+    if (region.x === undefined && region.y === undefined) {
+      return this.clearRegion({ duration, easing })
+    }
+
+    // Nothing up yet: the region is set from the first frame and just draws on.
+    if (from <= 0 || !this.hasCallout()) {
+      return this.command<RegionState>(
+        (t) => ({ region, regionReveal: from + (1 - from) * t }),
+        duration,
+        easing
+      )
+    }
+
+    // Something already up: retract it first so the rules don't jump across the
+    // plot mid-draw. Each half eases on its own — which is why the easing is
+    // applied here rather than handed to `animate`, whose easing would shape the
+    // pair as one curve and leave both halves crawling past the seam.
+    return this.command<RegionState>(
+      (t) =>
+        t < 0.5
+          ? { region: previous, regionReveal: from * (1 - easing(t * 2)) }
+          : { region, regionReveal: easing(t * 2 - 1) },
+      duration
+    )
+  }
+
+  /**
+   * Drop the region call-out — the rules retract, the wash fades, and every
+   * series comes back to full across its whole length. A no-op when nothing is
+   * spotlit.
+   */
+  @command()
+  clearRegion(
+    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
+  ): Command<RegionState> {
+    const duration = args.duration ?? 0.5
+    const easing = args.easing ?? easeOut()
+    const from = this.regionReveal
+
+    if (from === 0) {
+      // Nothing to retract, but the call still takes its slot: in an editor a
+      // command's duration is what the timeline lays out and what parallel
+      // siblings are timed against, so a no-op that took no frames would pull
+      // everything after it forward. Same reason for `zoomTo`/`resetZoom` below.
+      return this.command<RegionState>(
+        () => ({ region: null, regionReveal: 0 }),
+        duration
+      )
+    }
+
+    // `region` is left alone until the retraction lands — cleared at `t === 1`
+    // rather than up front, or there would be nothing left to retract.
+    return this.command<RegionState>(
+      (t) => (t >= 1 ? { region: null, regionReveal: 0 } : { regionReveal: from * (1 - t) }),
+      duration,
+      easing
+    )
+  }
+
+  // ---- Zoom --------------------------------------------------------------
+
+  /**
+   * The domain to come back to, captured the first time {@link zoomTo} runs so a
+   * later {@link resetZoom} restores the chart as authored — including ticks
+   * that were auto-derived rather than given, which the props alone don't
+   * record. Cleared by {@link resetZoom}, so a second zoom captures wherever the
+   * chart genuinely rests then.
+   */
+  private home: Domains | null = null
+
+  /**
+   * The `region` a document handed a command, or `{}`. A command is added
+   * before its arguments are filled in, so an unstated region is ordinary input
+   * rather than a malformed one.
+   */
+  private static regionArg(data: { region?: PlotRegion | null } | undefined): PlotRegion {
+    const region = data?.region
+    return region != null && typeof region === "object" ? region : {}
+  }
+
+  /** A range read as a span, whichever way round the author wrote it. */
+  private static span([a, b]: Range): Range {
+    return a <= b ? [a, b] : [b, a]
+  }
+
+  /**
+   * Rescale an axis to `range`, keeping the tick *count* it already has — the
+   * axis tween interpolates ticks pairwise by index, so a constant count lets
+   * each marker slide from its old value to its new one instead of the row
+   * popping.
+   */
+  private static rescale(range: Range, ticks: number[]): AxisDomainConfig {
+    const span = LineChart.span(range)
+    const count = Math.max(2, ticks.length)
+    return { range: span, ticks: markerValues(span, count - 1) }
+  }
+
+  /**
+   * Zoom the plot to a slice of itself, given in **data units**: the named axes
+   * rescale so that slice fills the plot, the grid and both marker rows
+   * following the new scale, and every series re-tracing itself into the new
+   * frame. All of it tweens, so the move reads as a camera push rather than a
+   * cut.
+   *
+   * An **omitted axis is left as it is** rather than being fitted to what's
+   * visible — so a zoom is exactly what was asked for, and two calls compose
+   * predictably. A spotlit region, if one is up, follows the zoom: it resolves
+   * against the same live scales, so its rules stay on their data bounds.
+   */
+  @command({
+    args: [
+      // One argument, two controls: the method takes a `PlotRegion`, so the x
+      // and y spans a host draws are declared inside it.
+      {
+        key: "region", kind: "region", properties: {
+          x: { kind: "range", default: true, defaultMin: 0, defaultMax: 100 },
+          y: { kind: "range", default: false, defaultMin: 0, defaultMax: 100 },
+        },
+      },
+    ],
+  })
+  zoomTo(
+    args: CommandArgs<{ region: PlotRegion }> & { duration?: number }
+  ): Command<AxisState> {
+    const region = LineChart.regionArg(args.data)
+    const duration = args.duration ?? 0.8
+    const easing = args.easing ?? easeOut()
+    if (!region.x && !region.y) return this.command<AxisState>(() => ({}), duration)
+
+    // Captured *before* the first zoom moves it.
+    const from = this._domains()
+    this.home ??= from
+
+    return this._tweenAxes(
+      from,
+      {
+        ...(region.x && { x: { ...from.x, ...LineChart.rescale(region.x, from.x.ticks!) } }),
+        ...(region.y && { y: { ...from.y, ...LineChart.rescale(region.y, from.y.ticks!) } }),
+      },
+      duration,
+      easing
+    )
+  }
+
+  /**
+   * Pull back out to the domain the chart was authored with — the mirror of
+   * {@link zoomTo}, and a no-op if it was never zoomed.
+   */
+  @command()
+  resetZoom(
+    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
+  ): Command<AxisState> {
+    const duration = args.duration ?? 0.8
+    const easing = args.easing ?? easeOut()
+    const home = this.home
+    if (!home) return this.command<AxisState>(() => ({}), duration)
+
+    // Cleared here rather than once the move lands. Nothing reads `home` while
+    // it runs, and a value has no "after" to clear it in — what matters is that
+    // the *next* `zoomTo` captures wherever the chart genuinely rests by then,
+    // and both this and its capture happen as the command list is walked.
+    this.home = null
+    return this._tweenAxes(this._domains(), home, duration, easing)
+  }
+
+  // ---- Per-series -------------------------------------------------------
+
+  /**
+   * Show series `index`: **trace** its line in left-to-right — the same draw as
+   * {@link enter}, not an opacity fade — in lockstep with its legend entry
+   * growing in.
+   *
+   * `enabled` is set as part of the command's own value rather than before it,
+   * so the line is drawable for every `t` the trace covers and undrawn outside
+   * it — which is what makes arriving here backwards show the same thing as
+   * arriving forwards.
+   */
+  @command({ args: [SERIES_ARG] })
+  showSeries(
+    args: CommandArgs<{ seriesIndex: number }> & { duration?: number }
+  ): Command<Record<string, never>> {
+    const index = args.data?.seriesIndex ?? 0
+    const duration = args.duration ?? 0.35
+    const easing = args.easing ?? easeOut()
+    const line = this.lines[index]
+    if (!line) return asCommand(hold(duration))
+
+    return asCommand(
+      together(
+        line.enterFrom(0, duration, easing),
+        ...(this.legend ? [this.legend.showSeries({ data: { index }, duration, easing })] : [])
+      ),
+      duration
+    )
+  }
+
+  /**
+   * Hide series `index`: **retrace** its line back out (`progress` 1 → 0) as its
+   * legend entry shrinks away — the mirror of {@link showSeries}.
+   */
+  @command({ args: [SERIES_ARG] })
+  hideSeries(
+    args: CommandArgs<{ seriesIndex: number }> & { duration?: number }
+  ): Command<Record<string, never>> {
+    const index = args.data?.seriesIndex ?? 0
+    const duration = args.duration ?? 0.35
+    const easing = args.easing ?? easeOut()
+    const line = this.lines[index]
+    if (!line) return asCommand(hold(duration))
+
+    return asCommand(
+      together(
+        line.enterFrom(1, duration, easing, 0),
+        ...(this.legend ? [this.legend.hideSeries({ data: { index }, duration, easing })] : [])
+      ),
+      duration
+    )
+  }
+
+  /**
+   * Fade out all other series — each line **and its legend entry** — to focus
+   * attention on `index`, which comes back to full. The legend dims in place
+   * (opacity only), so no entry moves and the row doesn't reflow.
+   */
+  @command({ args: [SERIES_ARG] })
+  spotlightSeries(
+    args: CommandArgs<{ seriesIndex: number }> & { duration?: number }
+  ): Command<Record<string, never>> {
+    const index = args.data?.seriesIndex ?? 0
+    const duration = args.duration ?? 0.35
+    const easing = args.easing ?? easeOut()
+    return asCommand(
+      together(
+        ...this.lines.map((line, i) =>
+          line.to({ data: { opacity: i === index ? 1 : SPOTLIGHT_DIM }, duration, easing })
+        ),
+        ...(this.legend
+          ? [this.legend.spotlightSeries({ data: { index }, duration, easing })]
+          : [])
+      ),
+      duration
+    )
+  }
+
+  /**
+   * Move props to new values; a restated axis `range` or `ticks` tweens from the
+   * domain as drawn, so an auto axis (the default) rescales continuously instead
+   * of cutting at the midpoint of the move.
+   */
+  override to<D extends Partial<LineChartProps> = Partial<LineChartProps>>(
+    args: CommandArgs<D> & { duration: number }
+  ): Command<LineChartProps> {
+    const data = (args.data ?? {}) as Partial<LineChartProps>
+    const drawn = this._domains()
+    const x = axisTweenTarget(drawn.x, data.xAxis)
+    const y = axisTweenTarget(drawn.y, data.yAxis)
+    if (!x && !y) return super.to(args)
+
+    const { xAxis, yAxis, ...rest } = data
+    const axes = this._tweenAxes(drawn, { ...(x && { x }), ...(y && { y }) }, args.duration, args.easing ?? easeOut())
+    // An axis that only restated its caption or format still takes the plain tween.
+    const remaining = { ...rest, ...(!x && xAxis && { xAxis }), ...(!y && yAxis && { yAxis }) }
+    if (Object.keys(remaining).length === 0) return axes as unknown as Command<LineChartProps>
+    return asCommand(
+      together(super.to({ ...args, data: remaining } as typeof args), axes),
+      args.duration
+    ) as unknown as Command<LineChartProps>
+  }
+
+  /** Both axes as drawn, so an auto range or tick row is read back as itself. */
+  private _domains(): Domains {
+    return {
+      x: { ...this.xAxis, range: this.xScale, ticks: this.resolvedXMarkers },
+      y: { ...this.yAxis, range: this.yScale, ticks: this.resolvedYMarkers },
+    }
+  }
+
+  /** From a resolved `from`: the axis tween steps an auto side at the midpoint, which is a cut. */
+  private _tweenAxes(
+    from: Domains,
+    to: Partial<Domains>,
+    duration: number,
+    easing: EasingFunction
+  ): Command<AxisState> {
+    return this.command<AxisState>(
+      (t) => ({
+        ...(to.x && { xAxis: lerpAxisDomain(from.x, to.x, t) }),
+        ...(to.y && { yAxis: lerpAxisDomain(from.y, to.y, t) }),
+      }),
+      duration,
+      easing
+    )
+  }
+}