@motionscript/plot 0.0.0-stage → 0.1.0-alpha.0

package/src/graph2d/curve.ts

@@ -0,0 +1,657 @@
+/**
+ * Turning `y = f(x)` into polylines you can actually hand a rasterizer.
+ *
+ * This is the whole difficulty of a 2D grapher, and it is not the sampling loop
+ * anybody writes first. That loop — walk the pixel columns, evaluate, skip
+ * anything that isn't on screen — fails in four separate ways, and each failure
+ * looks like a *different* bug:
+ *
+ * 1. **Dropping off-view points instead of clipping segments.** If the last
+ *    point you keep is the last one that landed inside the box, the curve stops
+ *    in mid-air an arbitrary distance from the edge. `log(x)` appears to end
+ *    somewhere over the plot rather than plunging out of the bottom of it. The
+ *    fix is to build the segment anyway and clip *it* against the frame, so the
+ *    curve leaves through the edge exactly where it really crosses.
+ *
+ * 2. **Handing the path API astronomical coordinates.** `log(1e-300)` is about
+ *    -690, which at any sane zoom is millions of pixels below the box. Skia's
+ *    scan converter is fixed-point, so a coordinate past roughly ±32k overflows
+ *    and the contour is *silently dropped* — the curve doesn't render wrong, it
+ *    doesn't render at all. Clipping (1) already bounds what reaches the path
+ *    API to the frame plus a hair; {@link COORD_LIMIT} bounds the arithmetic on
+ *    the way there, so no infinity ever reaches the clipper to turn a `t` into a
+ *    `NaN`.
+ *
+ * 3. **Sampling uniformly in x.** Near an asymptote one pixel of x is thousands
+ *    of pixels of y, so a uniform grid gives a visible polygonal kink where the
+ *    curve turns; far from one, the same grid spends hundreds of samples on a
+ *    straight line. {@link sampleCurve} subdivides recursively instead — split
+ *    any segment that is not flat *in screen space*, stop at a quarter pixel —
+ *    so sample density follows curvature and comes out dense near `x = 0` for
+ *    `log` and sparse where it is nearly straight. The flatness test pairs a
+ *    distance check with an **angle** check, because the distance alone reads a
+ *    symmetric wiggle (whose midpoint sits exactly on the chord) as flat.
+ *
+ * 4. **Treating "undefined" and "very large" as the same thing.** `log(-1)` is
+ *    `NaN`: a genuine hole, and the path has to break. `log(1e-300)` is finite
+ *    and enormous: the curve is still there, still continuous, and has to keep
+ *    being drawn until it leaves the frame. Conflating the two is the other half
+ *    of the cut-off in (1). At a defined/undefined edge this bisects to find
+ *    where the domain actually ends, so `sqrt(x)` terminates at the origin
+ *    rather than at whichever sample happened to be last.
+ *
+ * Everything here is pure and works in node-local pixels, so it is testable with
+ * no renderer: the caller supplies the graph→pixel mapping and gets back runs of
+ * points ready to stroke.
+ */
+
+import type { Vector2 } from "@motionscript/core"
+
+/**
+ * The graph→pixel mapping, as four numbers rather than two closures: this is the
+ * hot path (a few thousand projections per curve per frame) and the closures
+ * would be called through a megamorphic call site.
+ *
+ * Pixels are the node's own local space — origin at the node's centre, y **up**,
+ * which is both the space `Graphics` draws in and, conveniently, the orientation
+ * a graph is thought about in.
+ */
+export interface PlaneMap {
+  /** Graph x at the node's horizontal centre. */
+  centerX: number
+  /** Graph y at the node's vertical centre. */
+  centerY: number
+  /** Pixels per graph unit along x. */
+  scaleX: number
+  /** Pixels per graph unit along y. */
+  scaleY: number
+}
+
+/** An axis-aligned rectangle in node-local pixels, y-up. */
+export interface PixelRect {
+  left: number
+  right: number
+  bottom: number
+  top: number
+}
+
+/**
+ * Hard bound on a projected coordinate, in node pixels.
+ *
+ * Not a rendering decision — clipping is what decides what the rasterizer sees.
+ * This exists so the *arithmetic* between projection and clipping stays finite:
+ * `1/x` at 1e-320 projects to something that overflows to `Infinity`, and an
+ * `Infinity` in the clipper's `q / p` produces a `NaN` `t` that quietly discards
+ * the segment — which would put the cut-off of (1) back in through a side door.
+ *
+ * Large enough that no clamped point is ever inside a plausible frame (so the
+ * clamp can't bend a visible part of the curve), small enough to stay far below
+ * the fixed-point limit even after a parent scales the node up.
+ */
+const COORD_LIMIT = 16_000
+
+/** How far a sample may sit from the chord before the segment is split, in px. */
+const TOLERANCE_PX = 0.25
+
+/**
+ * How narrow a segment may get before the subdivision stops, in pixels of x.
+ *
+ * A **pixel** size rather than a recursion depth, and that is the single change
+ * that bounds this module's cost. Leaves tile the frame, so however violent the
+ * function is the whole tree costs at most `2 · width / MIN_SEGMENT_PX`
+ * evaluations — about seven and a half thousand on a 1920-px node, against the
+ * million a depth of ten over five hundred seeds allowed. Half a pixel because
+ * that is where one more halving cannot move a stroked line by as much as its
+ * own antialiasing.
+ */
+const MIN_SEGMENT_PX = 0.5
+
+/**
+ * How far the two halves of a segment may disagree in direction before it is
+ * split, in radians (~2.9°).
+ *
+ * The reason the distance test alone is not enough: a symmetric wiggle puts its
+ * midpoint *exactly* on the chord, so the perpendicular distance is zero and a
+ * distance-only test declares a visible kink flat. Two tests, and a segment has
+ * to pass both.
+ */
+const ANGLE_TOLERANCE = 0.05
+
+/**
+ * Backstop on the recursion depth.
+ *
+ * {@link MIN_SEGMENT_PX} stops the subdivision first at every box size
+ * {@link seedCount} can produce — the deepest is about six levels on an 8000-px
+ * node — so this only ever fires if a seed interval somehow came out enormous.
+ * It is here so the recursion cannot run away on a stack rather than because any
+ * curve needs it.
+ */
+const MAX_DEPTH = 12
+
+/**
+ * Evaluations one curve may spend in one frame.
+ *
+ * The refinement alone cannot reach this — see {@link MIN_SEGMENT_PX} — so what
+ * this really bounds is the boundary bisection, which is logarithmic per domain
+ * edge but unbounded in the *number* of edges: `sqrt(sin(1000x))` has hundreds.
+ * At roughly a tenth of a microsecond for a compiled expression tree this is
+ * about four milliseconds, which is as much of a 60 fps frame as one curve may
+ * have to itself.
+ */
+const MAX_EVALUATIONS = 40_000
+
+/**
+ * Evaluations every curve is guaranteed, however many of them there are: the
+ * seed pass with room for two levels of refinement over all of it.
+ *
+ * A graph carrying twenty curves draws all twenty coarsely rather than the first
+ * three well and the rest not at all.
+ */
+const MIN_EVALUATIONS = 2_048
+
+/**
+ * Evaluations all the curves on one node share in a frame.
+ *
+ * Three at their individual ceiling, or the verification harness's six at twenty
+ * thousand each — about twelve milliseconds in the worst case, which is the
+ * point past which degrading the curves beats dropping the frame.
+ */
+const FRAME_EVALUATIONS = 120_000
+
+/**
+ * How many times a defined/undefined edge is bisected before the curve is cut.
+ *
+ * Generous because the interesting case is not `sqrt(x)`, where the value at the
+ * boundary is finite and a handful of steps land on it. It is `log(x)`, whose
+ * boundary value is unbounded: each halving buys a constant amount of extra
+ * descent, so terminating early leaves the curve stopping *inside* the frame,
+ * which is the exact artefact this module exists to prevent. The loop exits as
+ * soon as the defined side has left the frame, so the full count is only ever
+ * paid on a boundary that stays on screen.
+ */
+const BOUNDARY_STEPS = 60
+
+/** Roughly how far apart the initial uniform samples are laid, in pixels. */
+const SEED_SPACING_PX = 8
+const MIN_SEEDS = 64
+const MAX_SEEDS = 512
+
+/**
+ * Ceiling on the points one curve may emit.
+ *
+ * Adaptive subdivision is self-limiting on anything anybody plots deliberately;
+ * it is not self-limiting on `sin(10000x)`, where every segment genuinely is
+ * curved at every scale and the recursion expands to its full width. This is the
+ * backstop, and going over it degrades the curve to the resolution already
+ * reached rather than dropping it.
+ */
+const MAX_POINTS = 24_000
+
+/** A `y = f(x)` curve, sampled by {@link sampleCurve}. */
+export type CurveFunction = (x: number) => number
+
+/** One evaluation of the curve, projected and classified. */
+interface Sample {
+  /**
+   * Offset from the view's centre, in graph units — the parameter of record.
+   *
+   * The sampler walks `t` and not `x` because `px` is then one multiply,
+   * `t · scaleX`, instead of a round trip out to `centerX` and back:
+   * `x = centerX + t` followed by `(x - centerX) · scaleX` is a literal
+   * add-then-subtract through a number whose ulp can be wider than the whole
+   * visible window. At `centerX = 1e9` and a span of 1e-6 that round trip leaves
+   * eight distinct pixel positions across the screen, and the curve staircases.
+   */
+  t: number
+  /** `centerX + t` — what `f` actually saw, kept for the bisections' float-resolution guards. */
+  x: number
+  /** Graph y — kept raw, so the sign is readable either side of a pole. */
+  y: number
+  /** Node-local pixels, clamped to {@link COORD_LIMIT}. */
+  px: number
+  py: number
+  /**
+   * Whether there is a point here at all: `false` for `NaN` (outside the
+   * function's domain) **and** for `±Infinity` (a pole landed on exactly). Both
+   * break the path; what separates them is where the bisection either side
+   * converges to, which the caller never has to know.
+   */
+  ok: boolean
+}
+
+function blankSample(): Sample {
+  return { t: 0, x: 0, y: 0, px: 0, py: 0, ok: false }
+}
+
+/**
+ * Reused {@link Sample} storage.
+ *
+ * Every evaluation used to be a fresh object. Six curves at sixty frames a
+ * second is millions of short-lived allocations a second, which is a collector
+ * running *through* the animation rather than between takes. The recursion is a
+ * depth-first walk over one seed interval and nothing outlives that interval, so
+ * the arena hands out slots and the seed loop resets the mark — which makes
+ * every allocation after the first frame a field write on an object whose hidden
+ * class never changes.
+ *
+ * Module scope, and therefore not re-entrant. Nothing re-enters: one
+ * {@link sampleCurve} runs to completion before the next begins, and an arena
+ * per call would allocate the thing it exists to avoid.
+ */
+const arena: Sample[] = []
+let arenaMark = 0
+
+function takeSample(): Sample {
+  const slot = arena[arenaMark]
+  if (slot !== undefined) {
+    arenaMark++
+    return slot
+  }
+  const fresh = blankSample()
+  arena.push(fresh)
+  arenaMark++
+  return fresh
+}
+
+/**
+ * A ceiling on curve evaluations, shared by every curve drawn in one frame.
+ *
+ * Shared rather than per curve because what a frame can afford is a property of
+ * the frame: one curve with a pole every three pixels must not be allowed to
+ * cost what six ordinary ones do, and six ordinary ones must not each be held to
+ * a sixth of the budget when five of them are straight lines. A cheap curve
+ * hands its slack to whatever comes after it.
+ */
+export interface SampleBudget {
+  /** Evaluations left for the curves still to be drawn. */
+  remaining: number
+  /** How many curves are still to be drawn, this one included. */
+  pending: number
+}
+
+/** A frame's budget, to be handed to each of `curves` {@link sampleCurve} calls. */
+export function sampleBudget(curves: number): SampleBudget {
+  return { remaining: FRAME_EVALUATIONS, pending: Math.max(1, curves) }
+}
+
+/**
+ * Samples `f` across the x range `clip` covers and returns the polylines to
+ * stroke: node-local pixel points, clipped to `clip`, split wherever the curve
+ * genuinely stops.
+ *
+ * `clip` should be the node's box grown by about a stroke width, so a curve
+ * running just outside the frame still paints the half of its stroke that falls
+ * inside it. Nothing outside that rectangle is returned, which is what keeps the
+ * rasterizer's fixed-point limit out of reach — see (2) in the module note.
+ */
+export function sampleCurve(
+  f: CurveFunction,
+  map: PlaneMap,
+  clip: PixelRect,
+  budget?: SampleBudget
+): Vector2[][] {
+  const pen = new CurvePen(clip)
+
+  // Sample across the *clip*, not the box: the extra sliver either side is what
+  // lets a curve enter the frame already at full stroke width instead of
+  // starting with a cap flush against the edge.
+  //
+  // In offsets from the centre rather than in x — see {@link Sample.t}.
+  const tLo = clip.left / map.scaleX
+  const tHi = clip.right / map.scaleX
+  if (!(tHi > tLo) || !(map.scaleX > 0) || !(map.scaleY > 0)) return []
+
+  const seeds = seedCount(clip.right - clip.left)
+  const step = (tHi - tLo) / seeds
+
+  // This curve's slice of the frame's evaluations. Bounded above so one curve
+  // can't eat the frame, and below so a graph full of them still draws every one.
+  const share = budget
+    ? Math.min(
+        MAX_EVALUATIONS,
+        Math.max(
+          MIN_EVALUATIONS,
+          Math.floor(budget.remaining / Math.max(1, budget.pending))
+        )
+      )
+    : MAX_EVALUATIONS
+  let spent = 0
+
+  const write = (slot: Sample, t: number): Sample => {
+    const x = map.centerX + t
+    const y = f(x)
+    spent++
+    const ok = Number.isFinite(y)
+    slot.t = t
+    slot.x = x
+    slot.y = y
+    slot.px = clampCoord(t * map.scaleX)
+    // A non-finite y has no position; 0 is a placeholder the `ok` flag keeps
+    // anyone from reading.
+    slot.py = ok ? clampCoord((y - map.centerY) * map.scaleY) : 0
+    slot.ok = ok
+    return slot
+  }
+
+  const at = (t: number): Sample => write(takeSample(), t)
+
+  /**
+   * The last defined sample on the way from `from` towards `to`, where exactly
+   * one of the two is defined.
+   *
+   * Three exits. Off the frame, because past the edge the only thing further
+   * halvings buy is a longer segment that is going to be clipped to the same
+   * place anyway — this is the one `log` leaves by, and the reason
+   * {@link BOUNDARY_STEPS} is generous. *Converged*, because a boundary whose
+   * value is finite stops moving after a handful of steps and `sqrt` was paying
+   * for all sixty of them. And float resolution, which nothing reaches.
+   */
+  const edgeOf = (from: Sample, to: Sample): Sample => {
+    let inside = from
+    let outsideT = to.t
+    for (let i = 0; i < BOUNDARY_STEPS; i++) {
+      if (spent >= share) break
+      if (offFrame(inside, clip)) break
+
+      const midT = (inside.t + outsideT) / 2
+      if (midT === inside.t || midT === outsideT) break // float resolution
+      const mid = at(midT)
+      if (!mid.ok) {
+        outsideT = midT
+        continue
+      }
+      const settled =
+        Math.abs(mid.px - inside.px) < TOLERANCE_PX &&
+        Math.abs(mid.py - inside.py) < TOLERANCE_PX
+      inside = mid
+      if (settled) break
+    }
+    return inside
+  }
+
+  const emit = (
+    a: Sample,
+    m: Sample | null,
+    b: Sample,
+    floored: boolean
+  ): void => {
+    if (a.ok && b.ok) {
+      if (floored && diverges(a, m, b, clip)) {
+        pen.break()
+        return
+      }
+      pen.draw(a, b)
+      return
+    }
+    if (a.ok) {
+      const edge = edgeOf(a, b)
+      if (edge.t !== a.t) pen.draw(a, edge)
+      pen.break()
+      return
+    }
+    if (b.ok) {
+      pen.break()
+      const edge = edgeOf(b, a)
+      if (edge.t !== b.t) pen.draw(edge, b)
+      else pen.start(b)
+      return
+    }
+    pen.break()
+  }
+
+  const refine = (a: Sample, b: Sample, depth: number): void => {
+    // Out of budget, or out of room in the path: draw the chord. Deliberately
+    // *not* routed through the pole test — with no midpoint there is nothing to
+    // judge by, and a vertical line through an asymptote is an ugly frame where
+    // a missing branch is a wrong one.
+    if (spent >= share || pen.points >= MAX_POINTS) {
+      emit(a, null, b, false)
+      return
+    }
+    const m = at((a.t + b.t) / 2)
+    const floored = depth >= MAX_DEPTH || b.px - a.px <= MIN_SEGMENT_PX
+    if (floored || flat(a, m, b)) {
+      // "Gave up" rather than "settled" is what identifies a pole, which is why
+      // the midpoint travels with the verdict — see {@link diverges}.
+      emit(a, m, b, floored)
+      return
+    }
+    refine(a, m, depth + 1)
+    refine(m, b, depth + 1)
+  }
+
+  // The seed endpoints come from their own pair rather than from the arena:
+  // `previous` has to survive the reset that recycles the interval it was the
+  // right-hand end of.
+  const ends: [Sample, Sample] = [blankSample(), blankSample()]
+  let previous = write(ends[0], tLo)
+  for (let i = 1; i <= seeds; i++) {
+    // Recomputed from the ends rather than accumulated, so rounding can't drift
+    // the grid off the right-hand edge over five hundred additions.
+    const next = write(ends[i & 1], i === seeds ? tHi : tLo + i * step)
+    arenaMark = 0
+    refine(previous, next, 0)
+    previous = next
+  }
+  arenaMark = 0
+
+  if (budget) {
+    budget.remaining = Math.max(0, budget.remaining - spent)
+    budget.pending = Math.max(0, budget.pending - 1)
+  }
+
+  return pen.finish()
+}
+
+/** How many uniform samples to lay down before refining anything. */
+function seedCount(widthPx: number): number {
+  const wanted = Math.round(widthPx / SEED_SPACING_PX)
+  return Math.min(MAX_SEEDS, Math.max(MIN_SEEDS, wanted))
+}
+
+/**
+ * Whether the arc `a → m → b` is straight enough, in **screen** space, to draw
+ * as one segment.
+ *
+ * Screen space and not graph space, because what "straight enough" has to mean
+ * is "the eye can't tell" — a tolerance in graph units would subdivide a flat
+ * line to death when zoomed out and give up mid-curve when zoomed in.
+ */
+function flat(a: Sample, m: Sample, b: Sample): boolean {
+  // A domain edge somewhere inside: always split, so the bisection that finds it
+  // runs on as short an interval as possible.
+  if (a.ok !== m.ok || m.ok !== b.ok) return false
+  // Nothing defined anywhere across it — there is no curve here to be wrong
+  // about, so stop.
+  if (!a.ok) return true
+
+  const dx = b.px - a.px
+  const dy = b.py - a.py
+  const length = Math.hypot(dx, dy) || 1
+  const distance = Math.abs((m.px - a.px) * dy - (m.py - a.py) * dx) / length
+  if (distance > TOLERANCE_PX) return false
+
+  // The second half of the test — see {@link ANGLE_TOLERANCE}.
+  const first = Math.atan2(m.py - a.py, m.px - a.px)
+  const second = Math.atan2(b.py - m.py, b.px - m.px)
+  let turn = Math.abs(first - second)
+  if (turn > Math.PI) turn = 2 * Math.PI - turn
+  return turn < ANGLE_TOLERANCE
+}
+
+/**
+ * Whether a segment the sampler had to give up on is an **asymptote** — the one
+ * case where drawing nothing beats drawing the chord.
+ *
+ * Two conditions, and the second is the one this module was missing. The ends
+ * must have run off *opposite* edges, which is what a vertical line through the
+ * frame looks like. And the curve must actually turn back inside the segment: a
+ * midpoint outside the range its own ends span is a pole (`tan` climbs to +∞ on
+ * one side of π/2 and arrives from -∞ on the other, so the midpoint is always
+ * outside), while a midpoint *between* them is an ordinary steep climb.
+ *
+ * Leaving the second test out is what cut `log(x)` off in mid-air. Once the y
+ * axis is stretched, `log` crosses the whole visible band inside a single leaf;
+ * the ends of that leaf are both off the frame, so its neighbours clip away to
+ * nothing, and treating the leaf itself as a pole deletes not a gap but the
+ * entire crossing — the exact artefact this module exists to prevent, arriving
+ * through the door meant to keep it out. `exp`, `x^20` and `1/x` all reach it.
+ *
+ * A `null` midpoint means the sampler ran out of budget and has nothing to judge
+ * by. Draw it: only a curve that has already spent forty thousand evaluations
+ * can get here, and a spurious vertical line is the lesser wrong.
+ */
+function diverges(
+  a: Sample,
+  m: Sample | null,
+  b: Sample,
+  clip: PixelRect
+): boolean {
+  if (!straddles(a, b, clip)) return false
+  if (m === null) return false
+  if (!m.ok) return true
+  return m.y < Math.min(a.y, b.y) || m.y > Math.max(a.y, b.y)
+}
+
+/** Whether the two ends have run off *opposite* edges of the frame. */
+function straddles(a: Sample, b: Sample, clip: PixelRect): boolean {
+  return (
+    (a.py > clip.top && b.py < clip.bottom) ||
+    (a.py < clip.bottom && b.py > clip.top)
+  )
+}
+
+/** Whether a sample has left the frame entirely. */
+function offFrame(sample: Sample, clip: PixelRect): boolean {
+  return sample.py > clip.top || sample.py < clip.bottom
+}
+
+function clampCoord(value: number): number {
+  if (value > COORD_LIMIT) return COORD_LIMIT
+  if (value < -COORD_LIMIT) return -COORD_LIMIT
+  // `NaN` cannot reach here (the caller checks `ok` first), but a `-0` would
+  // print oddly in a test snapshot and costs nothing to normalise.
+  return value === 0 ? 0 : value
+}
+
+/**
+ * Accumulates clipped polylines, one segment at a time.
+ *
+ * Incremental rather than "collect every point, then clip the polyline" because
+ * a curve is built by a recursion that already knows where its breaks are, and
+ * because the intermediate list is the thing that would carry the astronomical
+ * coordinates this module exists to keep out of the renderer.
+ */
+class CurvePen {
+  private readonly runs: Vector2[][] = []
+  private open: Vector2[] = []
+  /** The clipped end of the last drawn segment, for joining the next one to. */
+  private cursor: Vector2 | null = null
+  /** Points emitted so far, against {@link MAX_POINTS}. */
+  points = 0
+
+  constructor(private readonly clip: PixelRect) {}
+
+  /** Draws `a → b`, clipped; continues the open run when it joins on. */
+  draw(a: Sample, b: Sample): void {
+    const segment = clipSegment(a.px, a.py, b.px, b.py, this.clip)
+    if (!segment) {
+      // Wholly outside the frame: whatever run was open ended at the edge.
+      this.break()
+      return
+    }
+    const [start, end] = segment
+    if (this.cursor && samePoint(this.cursor, start)) {
+      this.push(end)
+    } else {
+      this.break()
+      this.push(start)
+      this.push(end)
+    }
+    this.cursor = end
+  }
+
+  /** Begins a run at `b` without drawing anything into it yet. */
+  start(b: Sample): void {
+    this.break()
+    if (inside(b.px, b.py, this.clip)) {
+      this.push({ x: b.px, y: b.py })
+      this.cursor = { x: b.px, y: b.py }
+    }
+  }
+
+  /** Ends the open run. A run of fewer than two points draws nothing. */
+  break(): void {
+    if (this.open.length >= 2) this.runs.push(this.open)
+    this.open = []
+    this.cursor = null
+  }
+
+  finish(): Vector2[][] {
+    this.break()
+    return this.runs
+  }
+
+  private push(point: Vector2): void {
+    this.open.push(point)
+    this.points++
+  }
+}
+
+/** Points within a tenth of a pixel are the same point, for run-joining. */
+function samePoint(a: Vector2, b: Vector2): boolean {
+  return Math.abs(a.x - b.x) < 0.1 && Math.abs(a.y - b.y) < 0.1
+}
+
+function inside(x: number, y: number, clip: PixelRect): boolean {
+  return x >= clip.left && x <= clip.right && y >= clip.bottom && y <= clip.top
+}
+
+/**
+ * Liang–Barsky clip of one segment against `clip`. Returns the surviving
+ * `[start, end]`, or `null` when the segment lies wholly outside.
+ *
+ * The piece of this module that turns "the curve stops in mid-air" into "the
+ * curve leaves through the edge": the off-frame endpoint is kept and the
+ * *segment* is cut, rather than the point being discarded and the segment never
+ * built.
+ */
+function clipSegment(
+  ax: number,
+  ay: number,
+  bx: number,
+  by: number,
+  clip: PixelRect
+): [Vector2, Vector2] | null {
+  const dx = bx - ax
+  const dy = by - ay
+  let t0 = 0
+  let t1 = 1
+
+  // Each edge as (p, q): the segment survives where p·t <= q.
+  const edges: [number, number][] = [
+    [-dx, ax - clip.left],
+    [dx, clip.right - ax],
+    [-dy, ay - clip.bottom],
+    [dy, clip.top - ay],
+  ]
+  for (const [p, q] of edges) {
+    if (p === 0) {
+      // Parallel to this edge: outside it means the whole segment is out.
+      if (q < 0) return null
+      continue
+    }
+    const r = q / p
+    if (p < 0) {
+      if (r > t1) return null
+      if (r > t0) t0 = r
+    } else {
+      if (r < t0) return null
+      if (r < t1) t1 = r
+    }
+  }
+  return [
+    { x: ax + t0 * dx, y: ay + t0 * dy },
+    { x: ax + t1 * dx, y: ay + t1 * dy },
+  ]
+}