@motionscript/layout-grid 0.0.0-stage → 0.1.0-alpha.3

package/src/kit/slots/index.ts

@@ -0,0 +1,39 @@
+import { pathSlots, type PathArrangement } from "./path"
+import { radialSlots, type RadialArrangement } from "./radial"
+import { rectangularSlots, type RectangularArrangement } from "./rectangular"
+import type { Slot, SlotInput } from "./slot"
+import { sphereSlots, type SphereArrangement } from "./sphere"
+
+export * from "./slot"
+export * from "./rectangular"
+export * from "./radial"
+export * from "./path"
+export * from "./path-templates"
+export * from "./sphere"
+
+/**
+ * Everything an arrangement needs to place items, as plain data — so a
+ * transition can keep the one it is leaving, and a grid can borrow another's.
+ */
+export type Arrangement = RectangularArrangement | RadialArrangement | PathArrangement | SphereArrangement
+
+export type ArrangementKind = Arrangement["kind"]
+
+/** Where each of `input.count` items sits under `arrangement`, in slot order. */
+export function slotsOf(arrangement: Arrangement, input: SlotInput): Slot[] {
+  switch (arrangement.kind) {
+    case "rectangular":
+      return rectangularSlots(arrangement, input)
+    case "radial":
+      return radialSlots(arrangement, input)
+    case "path":
+      return pathSlots(arrangement, input)
+    case "sphere":
+      return sphereSlots(arrangement, input)
+  }
+}
+
+/** The camera distance an arrangement is seen through, or `0` when it is flat. */
+export function focalLengthOf(arrangement: Arrangement): number {
+  return arrangement.kind === "sphere" ? Math.max(1, arrangement.focalLength) : 0
+}

package/src/kit/slots/path-templates.ts

@@ -0,0 +1,120 @@
+import type { PathCommand, Size2D } from "@motionscript/sdk"
+
+/**
+ * The shapes a path grid can follow without a path of its own, each drawn to
+ * fill the grid's box. Centred and y-up, like every path in the library; the
+ * closed ones run clockwise, so an item flowing along any of them travels the
+ * same way round.
+ */
+export const PATH_TEMPLATES = [
+  "circle",
+  "square",
+  "star",
+  "heart",
+  "infinity",
+  "wave",
+  "spiral",
+  "arc",
+  "line",
+] as const
+export type PathTemplate = (typeof PATH_TEMPLATES)[number]
+
+/** What a template is drawn at when the grid has no box to fill. */
+const FALLBACK = 400
+
+const DRAWN = new Map<string, PathCommand[]>()
+const DRAWN_CACHE = 64
+
+/**
+ * `template` drawn to fill `box`. The same template at the same size is the
+ * same array, which is what lets the path's measurement be kept between frames.
+ */
+export function templatePath(template: PathTemplate, box: Size2D): PathCommand[] {
+  const key = `${template}:${Math.round(box.width * 100)}:${Math.round(box.height * 100)}`
+  const hit = DRAWN.get(key)
+  if (hit) return hit
+  const path = drawTemplate(template, box)
+  if (DRAWN.size >= DRAWN_CACHE) DRAWN.delete(DRAWN.keys().next().value!)
+  DRAWN.set(key, path)
+  return path
+}
+
+function drawTemplate(template: PathTemplate, box: Size2D): PathCommand[] {
+  const w = box.width > 0 ? box.width : FALLBACK
+  const h = box.height > 0 ? box.height : FALLBACK
+  const rx = w / 2
+  const ry = h / 2
+  switch (template) {
+    case "square":
+      return closed([
+        [-rx, ry], [rx, ry], [rx, -ry], [-rx, -ry],
+      ])
+    case "star": {
+      const points: [number, number][] = []
+      for (let i = 0; i < 10; i++) {
+        const angle = (i * Math.PI) / 5
+        const r = i % 2 === 0 ? 1 : 0.45
+        points.push([Math.sin(angle) * rx * r, Math.cos(angle) * ry * r])
+      }
+      return closed(points)
+    }
+    case "heart":
+      return closed(sample(96, (t) => {
+        // The classic heart curve, from its top notch, clockwise.
+        const a = t * 2 * Math.PI
+        const x = 16 * Math.sin(a) ** 3
+        const y = 13 * Math.cos(a) - 5 * Math.cos(2 * a) - 2 * Math.cos(3 * a) - Math.cos(4 * a)
+        return [(x / 17) * rx, ((y + 2.5) / 15.5) * ry]
+      }).slice(0, -1))
+    case "infinity":
+      return closed(sample(96, (t) => {
+        const a = t * 2 * Math.PI
+        const d = 1 + Math.sin(a) ** 2
+        return [(Math.cos(a) / d) * rx, ((Math.sin(a) * Math.cos(a)) / d) * ry * 2]
+      }).slice(0, -1))
+    case "wave":
+      return open(sample(96, (t) => [(-1 + 2 * t) * rx, Math.sin(t * 4 * Math.PI) * ry * 0.6]))
+    case "spiral":
+      return open(sample(160, (t) => {
+        const a = t * 3 * 2 * Math.PI
+        const r = 0.08 + 0.92 * t
+        return [Math.sin(a) * rx * r, Math.cos(a) * ry * r]
+      }))
+    case "arc":
+      return open(sample(64, (t) => {
+        const a = -Math.PI / 2 + t * Math.PI
+        return [Math.sin(a) * rx, -ry + Math.cos(a) * h]
+      }))
+    case "line":
+      return [{ type: "M", x: -rx, y: 0 }, { type: "L", x: rx, y: 0 }]
+    default:
+      return ellipse(rx, ry)
+  }
+}
+
+/** Four quarter-arcs from the top, clockwise. */
+function ellipse(rx: number, ry: number): PathCommand[] {
+  const k = 0.5522847498
+  return [
+    { type: "M", x: 0, y: ry },
+    { type: "C", x1: k * rx, y1: ry, x2: rx, y2: k * ry, x: rx, y: 0 },
+    { type: "C", x1: rx, y1: -k * ry, x2: k * rx, y2: -ry, x: 0, y: -ry },
+    { type: "C", x1: -k * rx, y1: -ry, x2: -rx, y2: -k * ry, x: -rx, y: 0 },
+    { type: "C", x1: -rx, y1: k * ry, x2: -k * rx, y2: ry, x: 0, y: ry },
+    { type: "Z" },
+  ]
+}
+
+function sample(steps: number, at: (t: number) => [number, number]): [number, number][] {
+  const points: [number, number][] = []
+  for (let i = 0; i <= steps; i++) points.push(at(i / steps))
+  return points
+}
+
+function open(points: [number, number][]): PathCommand[] {
+  return points.map(([x, y], i) => (i === 0 ? { type: "M", x, y } : { type: "L", x, y }))
+}
+
+function closed(points: [number, number][]): PathCommand[] {
+  return [...open(points), { type: "Z" }]
+}

package/src/kit/slots/path.ts

@@ -0,0 +1,120 @@
+import { pathOps, type PathData, type PathSampler } from "@motionscript/sdk"
+
+import { slot, type Slot, type SlotInput } from "./slot"
+
+/** `distribute` spreads the items over the path; `fixed` sets them a distance apart. */
+export const PATH_SPACINGS = ["distribute", "fixed"] as const
+export type PathSpacing = (typeof PATH_SPACINGS)[number]
+
+/** How path coordinates land in the grid's frame: `origin` of the path goes to `(x, y)`, turned and scaled. */
+export interface PathPlacement {
+  originX: number
+  originY: number
+  /** The path is y-down, as SVG and the editor write one. */
+  flipY?: boolean
+  x: number
+  y: number
+  /** Degrees clockwise. */
+  rotation: number
+  scale: number
+}
+
+export interface PathArrangement {
+  kind: "path"
+  /** y-up, like every path in the library, unless its placement says otherwise. */
+  path: PathData
+  placement: PathPlacement
+  spacing: PathSpacing
+  /** Pixels between items when `spacing` is `fixed`. */
+  spacingDistance: number
+  /** Share of the path the items are moved along; wraps on a closed path. */
+  offset: number
+  /** Share of the path per second the items travel on their own. */
+  flowSpeed: number
+  trimStart: number
+  trimEnd: number
+  /** Turn each item to follow the path's direction. */
+  alignToPath: boolean
+}
+
+const SAMPLERS = new Map<PathData, { sampler: PathSampler; closed: boolean }>()
+const SAMPLER_CACHE = 32
+
+/** A sampler for `path`, kept while the same value keeps arriving — a path is re-read every frame. */
+function measured(path: PathData): { sampler: PathSampler; closed: boolean } {
+  const hit = SAMPLERS.get(path)
+  if (hit) return hit
+  const contours = pathOps.contours(path)
+  const entry = {
+    sampler: pathOps.sampler(path),
+    closed: contours.length === 1 && contours[0].closed,
+  }
+  if (SAMPLERS.size >= SAMPLER_CACHE) SAMPLERS.delete(SAMPLERS.keys().next().value!)
+  SAMPLERS.set(path, entry)
+  return entry
+}
+
+/**
+ * Items at even arc-length steps — by distance along the curve rather than the
+ * path's own parameter, which bunches them up wherever a curve is tight.
+ *
+ * On a closed path used whole, `n` items take `n` equal steps and `offset`
+ * wraps round, so an animated offset is a loop. Anywhere else the ends are
+ * ends: `n` items take `n - 1` steps so both get one, and an item moved past
+ * either is hidden rather than piled on it.
+ */
+export function pathSlots(arrangement: PathArrangement, input: SlotInput): Slot[] {
+  const { count } = input
+  if (count === 0) return []
+  const { sampler, closed } = measured(arrangement.path)
+  const length = sampler.length
+  const a = clamp01(Math.min(arrangement.trimStart, arrangement.trimEnd))
+  const b = clamp01(Math.max(arrangement.trimStart, arrangement.trimEnd))
+  const start = a * length
+  const span = (b - a) * length
+  const loops = closed && a === 0 && b === 1
+  const offset = arrangement.offset + arrangement.flowSpeed * input.time
+  const place = arrangement.placement
+  const rad = (place.rotation * Math.PI) / 180
+  const cos = Math.cos(rad)
+  const sin = Math.sin(rad)
+
+  const slots: Slot[] = []
+  for (let k = 0; k < count; k++) {
+    let u: number
+    if (arrangement.spacing === "fixed" && span > 0) {
+      u = offset + (k * arrangement.spacingDistance) / span
+    } else if (loops) {
+      u = offset + k / count
+    } else {
+      u = offset + (count === 1 ? 0.5 : k / (count - 1))
+    }
+    let visible = true
+    if (loops) u = u - Math.floor(u)
+    else if (u < -1e-9 || u > 1 + 1e-9) visible = false
+    const at = sampler.frameAt(start + clamp01(u) * span)
+    if (!at) {
+      const s = slot(0, 0, { kind: "path", t: clamp01(u) })
+      s.opacity = 0
+      slots.push(s)
+      continue
+    }
+    // Into the grid's frame: about the path's origin, turned clockwise (y-up).
+    const flip = place.flipY ? -1 : 1
+    const px = (at.x - place.originX) * place.scale
+    const py = (at.y - place.originY) * place.scale * flip
+    const s = slot(
+      place.x + px * cos + py * sin,
+      place.y - px * sin + py * cos,
+      { kind: "path", t: clamp01(u) },
+    )
+    if (arrangement.alignToPath) s.rotation = (-Math.atan2(at.ty * flip, at.tx) * 180) / Math.PI + place.rotation
+    if (!visible) s.opacity = 0
+    slots.push(s)
+  }
+  return slots
+}
+
+function clamp01(v: number): number {
+  return v < 0 ? 0 : v > 1 ? 1 : v
+}

package/src/kit/slots/radial.ts

@@ -0,0 +1,62 @@
+import { slot, type Slot, type SlotInput } from "./slot"
+
+export const RADIAL_DIRECTIONS = ["clockwise", "counterclockwise"] as const
+export type RadialDirection = (typeof RADIAL_DIRECTIONS)[number]
+
+export interface RadialArrangement {
+  kind: "radial"
+  radius: number
+  /** Where the first item sits, degrees clockwise from twelve o'clock. */
+  startAngle: number
+  /** How much of the circle the items span, degrees. */
+  sweep: number
+  direction: RadialDirection
+  /** Turn each item so its top faces away from the centre. */
+  rotateItems: boolean
+  /** Degrees per second the ring turns on its own. */
+  spinSpeed: number
+}
+
+/**
+ * The angle of each of `count` slots, clockwise from twelve o'clock. A full
+ * circle divides by the count, so the last item does not land on the first; an
+ * arc divides by one less, so both ends get an item. In between the divisor
+ * slides from one to the other as the arc closes — steeply, so an arc is an arc
+ * until it is nearly whole, and a sweep animated to 360 lands without a jump.
+ */
+export function radialAngles(arrangement: RadialArrangement, count: number, time: number): number[] {
+  const sweep = arrangement.sweep
+  const closing = Math.min(1, Math.abs(sweep) / 360) ** 8
+  const step = count <= 1 ? 0 : sweep / (count - 1 + closing)
+  const sign = arrangement.direction === "counterclockwise" ? -1 : 1
+  const start = arrangement.startAngle + arrangement.spinSpeed * time
+  const angles: number[] = []
+  for (let k = 0; k < count; k++) angles.push(start + sign * k * step)
+  return angles
+}
+
+export function radialSlots(arrangement: RadialArrangement, input: SlotInput): Slot[] {
+  const angles = radialAngles(arrangement, input.count, input.time)
+  const start = angles[0] ?? 0
+  return angles.map((angle) => {
+    const rad = (angle * Math.PI) / 180
+    const s = slot(arrangement.radius * Math.sin(rad), arrangement.radius * Math.cos(rad), {
+      kind: "radial",
+      angle: Math.abs(angle - start),
+    })
+    if (arrangement.rotateItems) s.rotation = angle
+    return s
+  })
+}
+
+/** The change to `startAngle` that brings slot `index` to twelve o'clock by the shorter way round. */
+export function radialTurnToTop(arrangement: RadialArrangement, count: number, index: number): number {
+  const angle = radialAngles({ ...arrangement, spinSpeed: 0 }, count, 0)[index] ?? arrangement.startAngle
+  return -wrapDegrees(angle)
+}
+
+/** `degrees` folded into `(-180, 180]`. */
+export function wrapDegrees(degrees: number): number {
+  const wrapped = ((degrees % 360) + 360) % 360
+  return wrapped > 180 ? wrapped - 360 : wrapped
+}

package/src/kit/slots/rectangular.ts

@@ -0,0 +1,108 @@
+import type { Size2D } from "@motionscript/sdk"
+
+import { largest, slot, type Slot, type SlotInput } from "./slot"
+
+export const FILL_DIRECTIONS = ["row", "column"] as const
+export type FillDirection = (typeof FILL_DIRECTIONS)[number]
+
+/**
+ * How big a cell is: the largest child (`fit`), a size of its own (`fixed`), or
+ * an equal share of the grid's box (`fill`), which is also the room a child set
+ * to `fill` grows into.
+ */
+export const CELL_MODES = ["fit", "fixed", "fill"] as const
+export type CellMode = (typeof CELL_MODES)[number]
+
+/** Where a short last row (or column, filling by column) sits. */
+export const LINE_ALIGNS = ["start", "center", "end"] as const
+export type LineAlign = (typeof LINE_ALIGNS)[number]
+
+export interface RectangularArrangement {
+  kind: "rectangular"
+  columns: number
+  fillDirection: FillDirection
+  cellMode: CellMode
+  cellWidth: number
+  cellHeight: number
+  columnGap: number
+  rowGap: number
+  lastLineAlign: LineAlign
+  /** Share of a column's pitch every other row shifts right — `0.5` is a brick bond. */
+  rowOffset: number
+  /** Share of a row's pitch every other column shifts down. */
+  columnOffset: number
+}
+
+/** Rows and columns `count` items make, `columns` wide. */
+export function rectangularShape(arrangement: RectangularArrangement, count: number): { rows: number; columns: number } {
+  const columns = Math.max(1, Math.round(arrangement.columns))
+  const rows = Math.max(1, Math.ceil(count / columns))
+  // Filling by column, the rows are set by the count, and a column the items
+  // never reach would pull the block off centre.
+  if (arrangement.fillDirection === "column") return { rows, columns: Math.max(1, Math.ceil(count / rows)) }
+  return { rows, columns }
+}
+
+/** The cell every item is laid out in — what a `fill` child is measured against. */
+export function rectangularCell(
+  arrangement: RectangularArrangement,
+  count: number,
+  sizes: readonly Size2D[],
+  box: Size2D,
+): Size2D {
+  const { rows, columns } = rectangularShape(arrangement, count)
+  switch (arrangement.cellMode) {
+    case "fixed":
+      return { width: Math.max(0, arrangement.cellWidth), height: Math.max(0, arrangement.cellHeight) }
+    case "fill":
+      return {
+        width: Math.max(0, (box.width - arrangement.columnGap * (columns - 1)) / columns),
+        height: Math.max(0, (box.height - arrangement.rowGap * (rows - 1)) / rows),
+      }
+    default:
+      return largest(sizes)
+  }
+}
+
+/**
+ * Items fill rows left to right, top to bottom (or columns top to bottom, left to
+ * right), and the whole block is centred on the grid.
+ */
+export function rectangularSlots(arrangement: RectangularArrangement, input: SlotInput): Slot[] {
+  const { count } = input
+  if (count === 0) return []
+  const { rows, columns } = rectangularShape(arrangement, count)
+  const byColumn = arrangement.fillDirection === "column"
+  // Filling by column keeps the column count and lets the rows follow from it.
+  const lines = byColumn ? columns : rows
+  const perLine = byColumn ? rows : columns
+  const cell = rectangularCell(arrangement, count, input.sizes, input.box)
+  const pitchX = cell.width + arrangement.columnGap
+  const pitchY = cell.height + arrangement.rowGap
+  const lastLine = lines - 1
+  const lastCount = count - lastLine * perLine
+  const shortBy = perLine - lastCount
+  const lead = arrangement.lastLineAlign === "center" ? shortBy / 2 : arrangement.lastLineAlign === "end" ? shortBy : 0
+  // Shifting every other row by a share of a pitch moves the block's centre by
+  // half that share; taking it back keeps the block centred on the grid.
+  const shiftX = arrangement.rowOffset * pitchX
+  const shiftY = arrangement.columnOffset * pitchY
+
+  const slots: Slot[] = []
+  for (let i = 0; i < count; i++) {
+    const line = Math.floor(i / perLine)
+    let along = i % perLine
+    if (line === lastLine) along += lead
+    const row = byColumn ? along : line
+    const column = byColumn ? line : along
+    // A centred short line sits between whole cells; its parity is the cell it covers most.
+    const rowIndex = Math.round(row)
+    const columnIndex = Math.round(column)
+    const x = (column - (columns - 1) / 2) * pitchX
+      + (rowIndex % 2 === 1 ? shiftX : 0) - (rows > 1 ? shiftX / 2 : 0)
+    const y = ((rows - 1) / 2 - row) * pitchY
+      - (columnIndex % 2 === 1 ? shiftY : 0) + (columns > 1 ? shiftY / 2 : 0)
+    slots.push(slot(x, y, { kind: "rectangular", row: rowIndex, column: columnIndex }))
+  }
+  return slots
+}

package/src/kit/slots/slot.ts

@@ -0,0 +1,82 @@
+import type { Size2D } from "@motionscript/sdk"
+
+/**
+ * One place in an arrangement, in the grid's own frame: centred on it, y-up,
+ * `depth` toward the viewer.
+ *
+ * Pure data, and the whole of what an arrangement produces — which is what lets
+ * a morph blend any two of them item by item, whatever shapes they came from.
+ */
+export interface Slot {
+  x: number
+  y: number
+  depth: number
+  /** Degrees clockwise. */
+  rotation: number
+  /** Tilt, degrees, as a node's own `rotationX`/`rotationY`. */
+  rotationX: number
+  rotationY: number
+  scale: number
+  opacity: number
+  meta: SlotMeta
+}
+
+/** What kind of place a slot is — the orderings a stagger can follow. */
+export type SlotMeta =
+  | { kind: "rectangular"; row: number; column: number }
+  /** Degrees clockwise from the arrangement's first slot. */
+  | { kind: "radial"; angle: number }
+  /** `0..1` along the part of the path in use. */
+  | { kind: "path"; t: number }
+  /** `depth` is `-1` at the back of the sphere and `1` at the front. */
+  | { kind: "sphere"; lat: number; lon: number; depth: number }
+
+/** What an arrangement is laid out for. */
+export interface SlotInput {
+  count: number
+  /** Each item's measured size, in item order. */
+  sizes: readonly Size2D[]
+  /** The grid's content box. */
+  box: Size2D
+  /** Scene seconds, for arrangements that move on their own. */
+  time: number
+}
+
+export function slot(x: number, y: number, meta: SlotMeta): Slot {
+  return { x, y, depth: 0, rotation: 0, rotationX: 0, rotationY: 0, scale: 1, opacity: 1, meta }
+}
+
+/** `a` toward `b`. The meta switches halfway, since an ordering cannot be half one thing. */
+export function blendSlot(a: Slot, b: Slot, t: number): Slot {
+  if (t <= 0) return a
+  if (t >= 1) return b
+  const mix = (p: number, q: number) => p + (q - p) * t
+  return {
+    x: mix(a.x, b.x),
+    y: mix(a.y, b.y),
+    depth: mix(a.depth, b.depth),
+    rotation: mix(a.rotation, b.rotation),
+    rotationX: mix(a.rotationX, b.rotationX),
+    rotationY: mix(a.rotationY, b.rotationY),
+    scale: mix(a.scale, b.scale),
+    opacity: mix(a.opacity, b.opacity),
+    meta: t < 0.5 ? a.meta : b.meta,
+  }
+}
+
+/** Push `s` away from (or pull it toward) the grid's centre. */
+export function spreadSlot(s: Slot, spread: number): Slot {
+  if (spread === 1) return s
+  return { ...s, x: s.x * spread, y: s.y * spread, depth: s.depth * spread }
+}
+
+/** Largest width and height among `sizes`. */
+export function largest(sizes: readonly Size2D[]): Size2D {
+  let width = 0
+  let height = 0
+  for (const size of sizes) {
+    if (size.width > width) width = size.width
+    if (size.height > height) height = size.height
+  }
+  return { width, height }
+}

package/src/kit/slots/sphere.ts

@@ -0,0 +1,94 @@
+import { slot, type Slot, type SlotInput } from "./slot"
+
+/** `outward` lays each item on the sphere's surface; `billboard` keeps every item facing the viewer. */
+export const SPHERE_FACINGS = ["outward", "billboard"] as const
+export type SphereFacing = (typeof SPHERE_FACINGS)[number]
+
+export const SPHERE_AXES = ["x", "y", "z"] as const
+export type SphereAxis = (typeof SPHERE_AXES)[number]
+
+export interface SphereArrangement {
+  kind: "sphere"
+  radius: number
+  /** Turn about the vertical axis, degrees — positive carries the front to the right. */
+  yaw: number
+  /** Turn about the horizontal axis, degrees — positive brings the top toward the viewer. */
+  pitch: number
+  /** Turn about the view axis, degrees clockwise. */
+  roll: number
+  facing: SphereFacing
+  /** The camera's distance from the sphere's centre plane, px — smaller is more dramatic. */
+  focalLength: number
+  /** How much the back half fades, `0..1`. */
+  depthFade: number
+  /** Hide the items whose faces point away from the viewer. */
+  cullBackfaces: boolean
+  /** Degrees per second of yaw the sphere turns on its own. */
+  spinSpeed: number
+}
+
+const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5))
+const DEG = 180 / Math.PI
+
+/** Point `k` of `count` on the unit sphere — a Fibonacci lattice, as even as `count` points get. */
+export function fibonacciPoint(k: number, count: number): [number, number, number] {
+  if (count <= 1) return [0, 0, 1]
+  const y = 1 - (2 * (k + 0.5)) / count
+  const r = Math.sqrt(Math.max(0, 1 - y * y))
+  const theta = k * GOLDEN_ANGLE
+  return [Math.cos(theta) * r, y, Math.sin(theta) * r]
+}
+
+/** `p` turned by yaw, then pitch, then roll — y-up, z toward the viewer. */
+export function orient(p: readonly [number, number, number], yaw: number, pitch: number, roll: number): [number, number, number] {
+  const [x0, y0, z0] = p
+  const ya = yaw / DEG, pa = pitch / DEG, ra = roll / DEG
+  const x1 = x0 * Math.cos(ya) + z0 * Math.sin(ya)
+  const z1 = -x0 * Math.sin(ya) + z0 * Math.cos(ya)
+  const y2 = y0 * Math.cos(pa) - z1 * Math.sin(pa)
+  const z2 = y0 * Math.sin(pa) + z1 * Math.cos(pa)
+  return [x1 * Math.cos(ra) + y2 * Math.sin(ra), -x1 * Math.sin(ra) + y2 * Math.cos(ra), z2]
+}
+
+export function sphereSlots(arrangement: SphereArrangement, input: SlotInput): Slot[] {
+  const { count } = input
+  const radius = arrangement.radius
+  const yaw = arrangement.yaw + arrangement.spinSpeed * input.time
+  const outward = arrangement.facing === "outward"
+  const slots: Slot[] = []
+  for (let k = 0; k < count; k++) {
+    const q = fibonacciPoint(k, count)
+    const [nx, ny, nz] = orient(q, yaw, arrangement.pitch, arrangement.roll)
+    const s = slot(nx * radius, ny * radius, {
+      kind: "sphere",
+      lat: Math.asin(Math.max(-1, Math.min(1, q[1]))) * DEG,
+      lon: Math.atan2(q[2], q[0]) * DEG,
+      depth: nz,
+    })
+    s.depth = nz * radius
+    if (outward) {
+      // The tilt whose `Rx · Ry` turns a face's normal onto the surface normal.
+      s.rotationY = Math.asin(Math.max(-1, Math.min(1, nx))) * DEG
+      s.rotationX = Math.atan2(ny, nz) * DEG
+    }
+    s.opacity = 1 - arrangement.depthFade * (1 - (nz + 1) / 2)
+    if (outward && arrangement.cullBackfaces && facesAway(s, [nx, ny, nz], arrangement.focalLength)) s.opacity = 0
+    slots.push(s)
+  }
+  return slots
+}
+
+/** Whether an outward face at `s` shows its back to a viewer `focal` px in front of the centre. */
+function facesAway(s: Slot, normal: readonly [number, number, number], focal: number): boolean {
+  if (focal <= 0) return normal[2] < 0
+  return normal[0] * -s.x + normal[1] * -s.y + normal[2] * (focal - s.depth) < 0
+}
+
+/** The yaw and pitch that bring point `index` of `count` round to face the viewer. */
+export function sphereFaceForward(count: number, index: number): { yaw: number; pitch: number } {
+  const [x, y, z] = fibonacciPoint(index, count)
+  return {
+    yaw: -Math.atan2(x, z) * DEG,
+    pitch: Math.atan2(y, Math.hypot(x, z)) * DEG,
+  }
+}