@motionscript/grids 0.0.0-stage → 0.1.0-alpha.10

package/src/kit/stagger.ts

@@ -0,0 +1,96 @@
+import { shuffled } from "./random"
+import type { Slot } from "./slots"
+
+/**
+ * The order a per-item effect sweeps through a grid's items. The first five
+ * work on any grid; the rest follow one arrangement's own geometry — rows and
+ * columns of a rectangular grid (or top-to-bottom and left-to-right of any
+ * other), the way round a ring, the way along a path, front to back of a sphere
+ * — and fall back to item order where the grid has no such thing.
+ */
+export const STAGGER_ORDERS = [
+  "index",
+  "reverse",
+  "random",
+  "centerOut",
+  "edgesIn",
+  "row",
+  "column",
+  "angle",
+  "path",
+  "depth",
+] as const
+export type StaggerOrder = (typeof STAGGER_ORDERS)[number]
+
+/** The most of a command's length the offsets may take; the rest is each item's own motion. */
+const MAX_STAGGER = 0.95
+
+/**
+ * Each item's start, `0..1`, as a share of the stagger: `0` goes first, `1`
+ * last, and items that tie go together — a ring revealed `centerOut` from its
+ * centre appears all at once, which is what that means.
+ */
+export function staggerRanks(order: StaggerOrder, slots: readonly Slot[], seed: number): number[] {
+  const n = slots.length
+  const keys = keysOf(order, slots, seed)
+  let min = Infinity
+  let max = -Infinity
+  for (const key of keys) {
+    if (key < min) min = key
+    if (key > max) max = key
+  }
+  const range = max - min
+  if (!(range > 1e-9)) return new Array<number>(n).fill(0)
+  return keys.map((key) => (key - min) / range)
+}
+
+/**
+ * Item progress at command time `t`: each item runs over the same length of
+ * time, starting `rank · stagger` in. The stagger lives inside the command's
+ * duration, so a one-second reveal takes one second for four items or four
+ * hundred.
+ */
+export function staggerProgress(rank: number, t: number, stagger: number): number {
+  const s = Math.max(0, Math.min(MAX_STAGGER, stagger))
+  const p = s === 0 ? t : (t - rank * s) / (1 - s)
+  return p < 0 ? 0 : p > 1 ? 1 : p
+}
+
+function keysOf(order: StaggerOrder, slots: readonly Slot[], seed: number): number[] {
+  switch (order) {
+    case "reverse":
+      return slots.map((_, i) => -i)
+    case "random": {
+      const sequence = shuffled(slots.map((_, i) => i), seed)
+      const keys = new Array<number>(slots.length)
+      sequence.forEach((item, rank) => {
+        keys[item] = rank
+      })
+      return keys
+    }
+    case "centerOut":
+      return slots.map((s) => Math.round(Math.hypot(s.x, s.y, s.depth) * 1000) / 1000)
+    case "edgesIn":
+      return slots.map((s) => -Math.round(Math.hypot(s.x, s.y, s.depth) * 1000) / 1000)
+    case "row":
+      return slots.map((s) => (s.meta.kind === "rectangular" ? s.meta.row : -Math.round(s.y)))
+    case "column":
+      return slots.map((s) => (s.meta.kind === "rectangular" ? s.meta.column : Math.round(s.x)))
+    case "angle":
+      return slots.map((s, i) =>
+        s.meta.kind === "radial" ? s.meta.angle : s.meta.kind === "rectangular" || s.meta.kind === "sphere" ? clockAngle(s) : i
+      )
+    case "path":
+      return slots.map((s, i) => (s.meta.kind === "path" ? s.meta.t : i))
+    case "depth":
+      return slots.map((s, i) => (s.meta.kind === "sphere" ? -s.meta.depth : i))
+    default:
+      return slots.map((_, i) => i)
+  }
+}
+
+/** Degrees clockwise from twelve o'clock to where `s` sits. */
+function clockAngle(s: Slot): number {
+  const angle = (Math.atan2(s.x, s.y) * 180) / Math.PI
+  return angle < 0 ? angle + 360 : angle
+}

package/src/nodes.ts

@@ -0,0 +1,30 @@
+import { PathGrid } from "./path-grid"
+import { RadialGrid } from "./radial-grid"
+import { RectangularGrid } from "./rectangular-grid"
+import { SphereGrid } from "./sphere-grid"
+
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
+ * Defining a component only *declares* that key: nothing is registered by
+ * importing a module, so a registry holds exactly what its owner asked for.
+ *
+ * Listing the component **values** is also what survives bundling: this package
+ * declares `sideEffects: false`, and a document names a node type by string, so
+ * an import kept only for its side effect is exactly what gets shaken out.
+ */
+// Typed by name, so the declaration names each component rather than spelling out its type through core.
+type KitNode =
+  | typeof RectangularGrid
+  | typeof RadialGrid
+  | typeof PathGrid
+  | typeof SphereGrid
+
+export const NODES: KitNode[] = [
+  RectangularGrid,
+  RadialGrid,
+  PathGrid,
+  SphereGrid,
+]

package/src/path-grid/index.ts

@@ -0,0 +1 @@
+export * from "./path-grid"

package/src/path-grid/path-grid.ts

@@ -0,0 +1,186 @@
+import {
+  component2d,
+  pathOps,
+  Types,
+  type NodeOf,
+  type NodeView,
+  type PathData,
+  type Size2D,
+  type Values,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+} from "@motionscript/sdk"
+
+import {
+  ItemGrid,
+  PATH_SPACINGS,
+  PATH_TEMPLATES,
+  staggerArgs,
+  TRANSITION_STAGGER,
+  templatePath,
+  type PathArrangement,
+  type PathPlacement,
+  type PathTemplate,
+} from "../kit"
+
+/** A template, or `custom` for the grid's own `path`. */
+export const PATH_GRID_SHAPES = [...PATH_TEMPLATES, "custom"] as const
+export type PathGridShape = (typeof PATH_GRID_SHAPES)[number]
+
+const own = {
+  shape: Types.oneOf(PATH_GRID_SHAPES, { default: "circle" }),
+  /** Used when `shape` is `custom`: an SVG path, y-down as SVG writes one, centred on its own bounds. */
+  path: Types.path,
+  /** A path node to follow instead, by id — the items track it wherever it goes. */
+  pathNode: ItemGrid.nodeRef(["path"]),
+  spacing: Types.oneOf(PATH_SPACINGS, { default: "distribute" }),
+  spacingDistance: Types.number(80, { min: 0, step: 1 }),
+  /** Share of the path the items are moved along — `1` is once round. */
+  offset: Types.number(0, { step: 0.01 }),
+  /** Share of the path per second the items travel on their own. */
+  flowSpeed: Types.number(0, { step: 0.01, unit: "/s" }),
+  trimStart: Types.number(0, { min: 0, max: 1, step: 0.01 }),
+  trimEnd: Types.number(1, { min: 0, max: 1, step: 0.01 }),
+  alignToPath: true,
+}
+
+type Own = Values<typeof own>
+
+const AT_ORIGIN: PathPlacement = { originX: 0, originY: 0, x: 0, y: 0, rotation: 0, scale: 1 }
+
+/** The size a path grid is placed at when nothing says otherwise, since a template is drawn to fill it. */
+const DEFAULT_SIZE = { width: 640, height: 400 }
+
+const arranger: ItemGrid.Arranger<Own> = {
+  arrangement: (s, box): PathArrangement => {
+    const { path, placement } = pathIn(s, box)
+    return {
+      kind: "path",
+      path,
+      placement,
+      spacing: s.spacing,
+      spacingDistance: s.spacingDistance,
+      offset: s.offset,
+      flowSpeed: s.flowSpeed,
+      trimStart: s.trimStart,
+      trimEnd: s.trimEnd,
+      alignToPath: s.alignToPath,
+    }
+  },
+}
+
+/**
+ * Children along a path: one of the templates drawn to fill the node's box,
+ * a path of the grid's own, or a path node elsewhere in the scene, followed
+ * wherever it is.
+ *
+ * Items are spaced by distance along the curve, so they sit evenly on a tight
+ * bend and a straight alike. Animating `offset` moves them along it — on a
+ * closed path they come round again, which is a conveyor belt for free.
+ */
+export const PathGrid = ItemGrid.define(component2d({
+  key: "pathGrid",
+  state: { ...ItemGrid.state, ...own },
+  // A template is drawn to fill the box, so a path grid needs one of its own
+  // rather than hugging items whose places depend on it.
+  defaults: { ...DEFAULT_SIZE },
+  commands: {
+    ...ItemGrid.commands,
+    /** Move the items along the path by `loops` — `1` is once round, and they keep their spacing. */
+    flow: {
+      args: { loops: Types.number(1, { step: 0.25 }) },
+      run: (timeline, s) => timeline.tween({ offset: s.offset + (timeline.args.loops ?? 1) }),
+    },
+    /** Squeeze the items into part of the path, between two shares of its length. */
+    trimTo: {
+      args: {
+        trimStart: ItemGrid.hinted(0.25, { min: 0, max: 1, step: 0.01 }),
+        trimEnd: ItemGrid.hinted(0.75, { min: 0, max: 1, step: 0.01 }),
+      },
+      run: (timeline, s) => timeline.tween({
+        trimStart: timeline.args.trimStart ?? s.trimStart,
+        trimEnd: timeline.args.trimEnd ?? s.trimEnd,
+      }),
+    },
+    /**
+     * Move the items onto another path — a template, or a path node in the
+     * scene. Each item travels from its place on the old path to its place on
+     * the new one; the path itself is not morphed.
+     */
+    setPath: {
+      args: {
+        shape: ItemGrid.hinted("heart", { kind: "enum", options: PATH_GRID_SHAPES }),
+        pathNode: ItemGrid.nodeRefArg(["path"]),
+        ...staggerArgs(TRANSITION_STAGGER),
+      },
+      run: (timeline, s, children) => {
+        const pathNode = timeline.args.pathNode ?? ""
+        const changes = pathNode ? { pathNode } : { shape: timeline.args.shape ?? s.shape, pathNode: "" }
+        return ItemGrid.transitionTo(timeline as never, s, children, changes)
+      },
+    },
+  },
+  ...ItemGrid.fields(arranger),
+}), arranger)
+
+export type PathGrid = NodeOf<typeof PathGrid>
+/** What a call or a document row may set. */
+export type PathGridProps = NonNullable<Parameters<typeof PathGrid>[0]>
+
+/** The path the items follow, and where its coordinates land in this grid's frame. */
+function pathIn(s: Own, box: Size2D): { path: PathData; placement: PathPlacement } {
+  const linked = s.pathNode
+  // A document `path` draws its data in its own unit box, at its own position.
+  if (linked?.key === "path") return { path: unitPath(linked), placement: { ...AT_ORIGIN, ...linked.frame } }
+  // A face-value path draws its data centred on the data's own bounds, at its own position.
+  const data = linked?.key === "facePath" ? dataOf(linked) : undefined
+  const bounds = data !== undefined ? pathOps.bounds(data) : null
+  if (linked && data !== undefined && bounds) {
+    return {
+      path: data,
+      placement: {
+        originX: (bounds.minX + bounds.maxX) / 2,
+        originY: (bounds.minY + bounds.maxY) / 2,
+        ...linked.frame,
+      },
+    }
+  }
+  if (s.shape === "custom") {
+    const own = pathOps.bounds(s.path)
+    if (own) {
+      return {
+        path: s.path,
+        placement: {
+          ...AT_ORIGIN,
+          originX: (own.minX + own.maxX) / 2,
+          originY: (own.minY + own.maxY) / 2,
+          flipY: true,
+        },
+      }
+    }
+  }
+  const template: PathTemplate = s.shape === "custom" ? "circle" : s.shape
+  return { path: templatePath(template, box), placement: AT_ORIGIN }
+}
+
+function dataOf(view: NodeView): PathData {
+  return (view.state as { readonly data: PathData }).data
+}
+
+const unitPaths = new WeakMap<NodeView, { data: PathData; width: number; height: number; path: PathData }>()
+
+/**
+ * A path node's geometry as it draws it: stored in its unit box, y-down, and
+ * scaled to its laid-out size — kept while neither changes, so the path's
+ * measurement is kept with it.
+ */
+function unitPath(view: NodeView): PathData {
+  const data = dataOf(view)
+  const { width, height } = view.size
+  const cached = unitPaths.get(view)
+  if (cached && cached.data === data && cached.width === width && cached.height === height) return cached.path
+  const path = pathOps.anchorCommands(pathOps.anchors(data), (p) => ({ x: p.x * width, y: -p.y * height }))
+  unitPaths.set(view, { data, width, height, path })
+  return path
+}

package/src/radial-grid/index.ts

@@ -0,0 +1 @@
+export * from "./radial-grid"

package/src/radial-grid/radial-grid.ts

@@ -0,0 +1,81 @@
+import {
+  component2d,
+  Types,
+  type NodeOf,
+  type Values,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+} from "@motionscript/sdk"
+
+import { ItemGrid, normalizeOrder, RADIAL_DIRECTIONS, radialTurnToTop, type RadialArrangement } from "../kit"
+
+const own = {
+  radius: Types.number(200, { min: 0, step: 1 }),
+  startAngle: Types.number(0, { step: 1, unit: "°" }),
+  sweep: Types.number(360, { min: -360, max: 360, step: 1, unit: "°" }),
+  direction: Types.oneOf(RADIAL_DIRECTIONS, { default: "clockwise" }),
+  rotateItems: false,
+  spinSpeed: Types.number(0, { step: 1, unit: "°/s" }),
+}
+
+type Own = Values<typeof own>
+
+function arrangement(s: Own): RadialArrangement {
+  return {
+    kind: "radial",
+    radius: s.radius,
+    startAngle: s.startAngle,
+    sweep: s.sweep,
+    direction: s.direction,
+    rotateItems: s.rotateItems,
+    spinSpeed: s.spinSpeed,
+  }
+}
+
+const arranger: ItemGrid.Arranger<Own> = { arrangement }
+
+/**
+ * Children round a circle, or along an arc of one.
+ *
+ * A full circle spaces the items evenly with none on top of another; an arc
+ * puts one at each end. Angles run clockwise from twelve o'clock, so `turnTo`
+ * can bring any item to the top like a dial.
+ */
+export const RadialGrid = ItemGrid.define(component2d({
+  key: "radialGrid",
+  state: { ...ItemGrid.state, ...own },
+  defaults: ItemGrid.defaults,
+  commands: {
+    ...ItemGrid.commands,
+    /** Orbit the items round the centre by `degrees` — `360` is one full turn. */
+    spin: {
+      args: { degrees: Types.number(360, { step: 15, unit: "°" }) },
+      run: (timeline, s) => timeline.tween({ startAngle: s.startAngle + (timeline.args.degrees ?? 360) }),
+    },
+    /** Turn the ring the shorter way round until an item (by its place in the layers) sits at the top. */
+    turnTo: {
+      args: { item: Types.number(0, { min: 0, step: 1 }) },
+      run: (timeline, s, children) => {
+        const count = children.length
+        const slot = normalizeOrder(s.order, count).indexOf(Math.round(timeline.args.item ?? 0))
+        const turn = slot < 0 ? 0 : radialTurnToTop(arrangement(s), count, slot)
+        return timeline.tween({ startAngle: s.startAngle + turn })
+      },
+    },
+    radiusTo: {
+      args: { radius: ItemGrid.hinted(280, { min: 0 }) },
+      run: (timeline, s) => timeline.tween({ radius: timeline.args.radius ?? s.radius }),
+    },
+    /** Open or close the arc like a fan — from `0` to `360` is a reveal of its own. */
+    sweepTo: {
+      args: { sweep: ItemGrid.hinted(360, { min: -360, max: 360, unit: "°" }) },
+      run: (timeline, s) => timeline.tween({ sweep: timeline.args.sweep ?? s.sweep }),
+    },
+  },
+  ...ItemGrid.fields(arranger),
+}), arranger)
+
+export type RadialGrid = NodeOf<typeof RadialGrid>
+/** What a call or a document row may set. */
+export type RadialGridProps = NonNullable<Parameters<typeof RadialGrid>[0]>

package/src/rectangular-grid/index.ts

@@ -0,0 +1 @@
+export * from "./rectangular-grid"

package/src/rectangular-grid/rectangular-grid.ts

@@ -0,0 +1,145 @@
+import {
+  component2d,
+  easeInOut,
+  Types,
+  type NodeOf,
+  type Values,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+} from "@motionscript/sdk"
+
+import {
+  CELL_MODES,
+  FILL_DIRECTIONS,
+  ItemGrid,
+  LINE_ALIGNS,
+  rectangularCell,
+  staggerArgs,
+  TRANSITION_STAGGER,
+  type RectangularArrangement,
+} from "../kit"
+
+const own = {
+  columns: Types.number(3, { min: 1, step: 1 }),
+  fillDirection: Types.oneOf(FILL_DIRECTIONS, { default: "row" }),
+  cellMode: Types.oneOf(CELL_MODES, { default: "fit" }),
+  cellWidth: Types.number(120, { min: 0, step: 1 }),
+  cellHeight: Types.number(120, { min: 0, step: 1 }),
+  columnGap: Types.number(24, { step: 1 }),
+  rowGap: Types.number(24, { step: 1 }),
+  lastLineAlign: Types.oneOf(LINE_ALIGNS, { default: "start" }),
+  rowOffset: Types.number(0, { min: -1, max: 1, step: 0.05 }),
+  columnOffset: Types.number(0, { min: -1, max: 1, step: 0.05 }),
+}
+
+type Own = Values<typeof own>
+
+function arrangement(s: Own): RectangularArrangement {
+  return {
+    kind: "rectangular",
+    columns: s.columns,
+    fillDirection: s.fillDirection,
+    cellMode: s.cellMode,
+    cellWidth: s.cellWidth,
+    cellHeight: s.cellHeight,
+    columnGap: s.columnGap,
+    rowGap: s.rowGap,
+    lastLineAlign: s.lastLineAlign,
+    rowOffset: s.rowOffset,
+    columnOffset: s.columnOffset,
+  }
+}
+
+const arranger: ItemGrid.Arranger<Own> = {
+  arrangement,
+  // A child set to fill takes its cell, where the cell is not simply the largest child.
+  itemSpace: (s, count, space) => (s.cellMode === "fit" ? space : rectangularCell(arrangement(s), count, [], space)),
+}
+
+/** The focus args of a row or a column: the grow a row leaves out is the shared focus's. */
+const lineFocus = {
+  dim: Types.number(0.7, { min: 0, max: 1, step: 0.05 }),
+  grow: ItemGrid.hinted(0.1, { min: 0, max: 1, step: 0.05 }),
+}
+
+/**
+ * Children in rows and columns — the grid the other three are variations on.
+ *
+ * Cells are as big as the largest child (`fit`), a size of their own
+ * (`fixed`), or an equal share of the node's box (`fill`), which is also the
+ * room a child set to fill grows into. Shift every other row by half a cell
+ * for a brick bond or a hex pack.
+ */
+export const RectangularGrid = ItemGrid.define(component2d({
+  key: "rectangularGrid",
+  state: { ...ItemGrid.state, ...own },
+  defaults: ItemGrid.defaults,
+  commands: {
+    ...ItemGrid.commands,
+    /** Re-flow the items into `columns` columns, each moving to its new cell. */
+    columnsTo: {
+      args: { columns: ItemGrid.hinted(4, { min: 1, step: 1 }), ...staggerArgs(TRANSITION_STAGGER) },
+      run: (timeline, s, children) => {
+        const columns = Math.max(1, Math.round(timeline.args.columns ?? s.columns))
+        return ItemGrid.transitionTo(timeline as never, s, children, { columns })
+      },
+    },
+    /** Animate the spacing between columns and rows. */
+    gapTo: {
+      args: { columnGap: ItemGrid.hinted(48), rowGap: ItemGrid.hinted(48) },
+      run: (timeline) => {
+        const data: { columnGap?: number; rowGap?: number } = {}
+        if (timeline.args.columnGap !== undefined) data.columnGap = timeline.args.columnGap
+        if (timeline.args.rowGap !== undefined) data.rowGap = timeline.args.rowGap
+        return timeline.tween(data)
+      },
+    },
+    /**
+     * Animate the cell size, from whatever the cells measure now. The grid
+     * switches to `fixed` cells as it starts, since a size of its own is what
+     * `fixed` means.
+     */
+    cellSizeTo: {
+      args: { cellWidth: ItemGrid.hinted(160, { min: 0 }), cellHeight: ItemGrid.hinted(160, { min: 0 }) },
+      easing: easeInOut("cubic"),
+      run: (timeline, s, children) => {
+        const sizes = children.map((child) => child.size)
+        const box = ItemGrid.contentBox(timeline.node.size, s.padding)
+        const from = rectangularCell(arrangement(s), sizes.length, sizes, box)
+        const width = timeline.args.cellWidth ?? from.width
+        const height = timeline.args.cellHeight ?? from.height
+        return timeline.animate((t) => ({
+          cellMode: "fixed",
+          cellWidth: from.width + (width - from.width) * t,
+          cellHeight: from.height + (height - from.height) * t,
+        }))
+      },
+    },
+    /** Bring one row (from 0 at the top) forward and push the rest back. */
+    focusRow: {
+      args: { row: Types.number(0, { min: 0, step: 1 }), ...lineFocus },
+      run: (timeline, s, children) => {
+        const slots = ItemGrid.itemSlots(timeline as never, s, children)
+        const row = Math.round(timeline.args.row ?? 0)
+        const inRow = (i: number) => slots[i]?.meta.kind === "rectangular" && slots[i].meta.row === row
+        return ItemGrid.focusOn(timeline as never, s, inRow, slots.length, timeline.args.dim ?? 0.7, timeline.args.grow ?? 0.15)
+      },
+    },
+    /** Bring one column (from 0 at the left) forward and push the rest back. */
+    focusColumn: {
+      args: { column: Types.number(0, { min: 0, step: 1 }), ...lineFocus },
+      run: (timeline, s, children) => {
+        const slots = ItemGrid.itemSlots(timeline as never, s, children)
+        const column = Math.round(timeline.args.column ?? 0)
+        const inColumn = (i: number) => slots[i]?.meta.kind === "rectangular" && slots[i].meta.column === column
+        return ItemGrid.focusOn(timeline as never, s, inColumn, slots.length, timeline.args.dim ?? 0.7, timeline.args.grow ?? 0.15)
+      },
+    },
+  },
+  ...ItemGrid.fields(arranger),
+}), arranger)
+
+export type RectangularGrid = NodeOf<typeof RectangularGrid>
+/** What a call or a document row may set. */
+export type RectangularGridProps = NonNullable<Parameters<typeof RectangularGrid>[0]>

package/src/sphere-grid/index.ts

@@ -0,0 +1 @@
+export * from "./sphere-grid"

package/src/sphere-grid/sphere-grid.ts

@@ -0,0 +1,129 @@
+import {
+  component2d,
+  Types,
+  type NodeOf,
+  type Values,
+  // Named so the emitted declaration reaches these through the sdk, not core.
+  type Node2D as _Node2D,
+  type Node2DProps as _Node2DProps,
+} from "@motionscript/sdk"
+
+import {
+  ItemGrid,
+  normalizeOrder,
+  SPHERE_AXES,
+  SPHERE_FACINGS,
+  sphereFaceForward,
+  wrapDegrees,
+  type SphereArrangement,
+  type SphereAxis,
+} from "../kit"
+
+const own = {
+  radius: Types.number(220, { min: 0, step: 1 }),
+  yaw: Types.number(0, { step: 1, unit: "°" }),
+  pitch: Types.number(0, { step: 1, unit: "°" }),
+  roll: Types.number(0, { step: 1, unit: "°" }),
+  facing: Types.oneOf(SPHERE_FACINGS, { default: "outward" }),
+  focalLength: Types.number(900, { min: 100, step: 10 }),
+  depthFade: Types.number(0.5, { min: 0, max: 1, step: 0.05 }),
+  cullBackfaces: false,
+  spinSpeed: Types.number(0, { step: 1, unit: "°/s" }),
+}
+
+type Own = Values<typeof own>
+
+function arrangement(s: Own): SphereArrangement {
+  return {
+    kind: "sphere",
+    radius: s.radius,
+    yaw: s.yaw,
+    pitch: s.pitch,
+    roll: s.roll,
+    facing: s.facing,
+    focalLength: s.focalLength,
+    depthFade: s.depthFade,
+    cullBackfaces: s.cullBackfaces,
+    spinSpeed: s.spinSpeed,
+  }
+}
+
+const arranger: ItemGrid.Arranger<Own> = { arrangement }
+
+const AXIS_PROP: Record<SphereAxis, "yaw" | "pitch" | "roll"> = { x: "pitch", y: "yaw", z: "roll" }
+
+/**
+ * Children spread over a sphere — a Fibonacci lattice, as even as any number
+ * of points gets — and seen through a camera of the grid's own, so the far
+ * side is smaller, drawn first, and hidden where a face turns away.
+ *
+ * `outward` lays each item flat on the surface; `billboard` keeps each one
+ * facing the viewer, like labels on a globe. `turnTo` brings any item round
+ * to the front.
+ */
+export const SphereGrid = ItemGrid.define(component2d({
+  key: "sphereGrid",
+  state: { ...ItemGrid.state, ...own },
+  defaults: ItemGrid.defaults,
+  commands: {
+    ...ItemGrid.commands,
+    /** Turn the sphere about an axis by `degrees` — `y` spins it like a globe. */
+    spin: {
+      args: {
+        axis: Types.oneOf(SPHERE_AXES, { default: "y" }),
+        degrees: Types.number(360, { step: 15, unit: "°" }),
+      },
+      run: (timeline, s) => {
+        const key = AXIS_PROP[timeline.args.axis ?? "y"] ?? "yaw"
+        return timeline.tween({ [key]: s[key] + (timeline.args.degrees ?? 360) })
+      },
+    },
+    /** Turn the sphere to a set orientation. */
+    orientTo: {
+      args: {
+        yaw: ItemGrid.hinted(45, { unit: "°" }),
+        pitch: ItemGrid.hinted(20, { unit: "°" }),
+        roll: ItemGrid.hinted(0, { unit: "°" }),
+      },
+      run: (timeline, s) => timeline.tween({
+        yaw: timeline.args.yaw ?? s.yaw,
+        pitch: timeline.args.pitch ?? s.pitch,
+        roll: timeline.args.roll ?? s.roll,
+      }),
+    },
+    /**
+     * Turn the sphere the shorter way until an item (by its place in the layers)
+     * faces the viewer. It turns from the orientation the sphere is given: the
+     * yaw its `spinSpeed` adds by the time the command runs is not counted, as
+     * commands are built against the tree standing at time 0.
+     */
+    turnTo: {
+      args: { item: Types.number(0, { min: 0, step: 1 }) },
+      run: (timeline, s, children) => {
+        const count = children.length
+        const slot = normalizeOrder(s.order, count).indexOf(Math.round(timeline.args.item ?? 0))
+        if (slot < 0) return timeline.tween({})
+        const facing = sphereFaceForward(count, slot)
+        return timeline.tween({
+          yaw: s.yaw + wrapDegrees(facing.yaw - s.yaw),
+          pitch: s.pitch + wrapDegrees(facing.pitch - s.pitch),
+          roll: 0,
+        })
+      },
+    },
+    radiusTo: {
+      args: { radius: ItemGrid.hinted(300, { min: 0 }) },
+      run: (timeline, s) => timeline.tween({ radius: timeline.args.radius ?? s.radius }),
+    },
+    /** Dolly the camera: a shorter focal length exaggerates the depth, a longer one flattens it. */
+    focalLengthTo: {
+      args: { focalLength: ItemGrid.hinted(600, { min: 100 }) },
+      run: (timeline, s) => timeline.tween({ focalLength: timeline.args.focalLength ?? s.focalLength }),
+    },
+  },
+  ...ItemGrid.fields(arranger),
+}), arranger)
+
+export type SphereGrid = NodeOf<typeof SphereGrid>
+/** What a call or a document row may set. */
+export type SphereGridProps = NonNullable<Parameters<typeof SphereGrid>[0]>