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

package/src/kit/layout-grid.ts

@@ -0,0 +1,605 @@
+import {
+  command,
+  easeIn,
+  easeInOut,
+  easeOut,
+  flowOps,
+  insetsOps,
+  Node2D,
+  property,
+  sizeInputOps,
+  type BoxBounds,
+  type ChildPlacement,
+  type Command,
+  type CommandArgs,
+  type MeasureContext2D,
+  type EasingFunction,
+  type Node2DProps,
+  type Size2D,
+  type SizeConstraints,
+  type SpaceCamera,
+} from "@motionscript/sdk"
+
+import {
+  applyItemEffects,
+  REVEAL_STYLES,
+  WAVE_STYLES,
+  type FocusState,
+  type RevealState,
+  type RevealStyle,
+  type WaveState,
+  type WaveStyle,
+} from "./item-effects"
+import { normalizeOrder, parseOrder, slotOfItem } from "./order"
+import { hashSeed, shuffled } from "./random"
+import { blendSlot, focalLengthOf, slotsOf, spreadSlot, type Arrangement, type Slot } from "./slots"
+import { STAGGER_ORDERS, staggerProgress, staggerRanks, type StaggerOrder } from "./stagger"
+
+/** An arrangement a grid is leaving, kept as data so its slots can be worked out afresh every frame. */
+export interface GridSnapshot {
+  arrangement: Arrangement
+  /** The grid the arrangement was borrowed from, or `""` for the grid's own. */
+  source: string
+  order: readonly number[]
+  spread: number
+}
+
+/** A change of arrangement under way: where the items are coming from, and how far each has come. */
+export interface GridTransition {
+  from: GridSnapshot
+  /** Each item's eased, staggered progress, `0..1`. */
+  mix: readonly number[]
+}
+
+export interface LayoutGridProps extends Node2DProps {
+  /** Items in slot order: slot `k` holds child `order[k]`. Empty is the children's own order. */
+  order: number[]
+  /** `0` gathers every item at the centre, `1` is the arrangement, past `1` pushes them apart. */
+  spread: number
+  /** Another grid whose arrangement this one takes on — what {@link LayoutGrid.morphInto} animates. */
+  arrangeLike: string
+  // What the per-item commands write. State rather than settings: a command
+  // owns each while it runs, and a document has no reason to name them.
+  revealState: RevealState | null
+  waveState: WaveState | null
+  focusState: FocusState | null
+  transition: GridTransition | null
+}
+
+/** What a command that moves the items to new slots is built from. */
+export interface TransitionArgs {
+  data?: StaggerArgs
+  duration: number
+  easing?: EasingFunction
+}
+
+/** The stagger options every per-item command takes. */
+export interface StaggerArgs {
+  staggerOrder?: StaggerOrder
+  /** `0..0.95`: how much of the command's length the items' offsets take up. */
+  stagger?: number
+}
+
+/** `@command` descriptors for {@link StaggerArgs}, `stagger` defaulting to `fallback`. */
+export function staggerArgs(fallback: number) {
+  return [
+    { key: "staggerOrder", kind: "enum", options: STAGGER_ORDERS, default: "index" },
+    { key: "stagger", min: 0, max: 0.95, step: 0.05, default: fallback },
+  ] as const
+}
+
+/**
+ * Every grid's document key — what a reference to "another grid" may name. A
+ * `nodeRef` descriptor carries it as `nodeTypes`, for a host's picker to offer
+ * only those.
+ */
+export const LAYOUT_GRID_TYPES = ["rectangularGrid", "radialGrid", "pathGrid", "sphereGrid"] as const
+
+/** The stagger a move to new slots takes when its command states none. */
+export const TRANSITION_STAGGER = 0.3
+
+const NO_CONTENT: Size2D = { width: 0, height: 0 }
+const CENTRE = { x: 0, y: 0 }
+
+/**
+ * The base of every grid: a container that places each of its children in a
+ * slot of an arrangement — a rectangular grid, a ring, a path, a sphere.
+ *
+ * ## Children only
+ *
+ * The items are the children, in layer order. A child's slot is a parent
+ * transform on it, so its own `x`/`y`/`rotation`/`scale` — and any command on
+ * them — still work, relative to the slot. A group is one item; a grid of
+ * grids is a grid of items that happen to be grids.
+ *
+ * ## One pass
+ *
+ * Every frame: measure the children, ask the arrangement for its slots (a pure
+ * function of the props, the sizes and the clock), blend them from where a
+ * transition is leaving, and layer on the per-item effects — reveal, wave,
+ * focus. What is left is each child's box and {@link ChildPlacement}, which the
+ * renderer, picking and `global` all read, so a selection outline lands on
+ * the pixels even on a sphere.
+ *
+ * ## Commands
+ *
+ * Every command is a pure function of time, like the rest of the library. The
+ * per-item ones stagger *inside* their duration — a one-second reveal takes one
+ * second for four children or four hundred — and write their per-item state
+ * into props ({@link revealState} and its siblings), which is what keeps them
+ * seekable. The ones that change the arrangement itself (a reorder, a morph, a
+ * column count) keep the arrangement they are leaving as data and blend each
+ * item from its old slot to its new one.
+ */
+export abstract class LayoutGrid<P extends LayoutGridProps = LayoutGridProps> extends Node2D<P> {
+  @property({ default: [], kind: "order", animatable: false }) declare order: number[]
+  @property({ default: 1, min: 0, max: 3, step: 0.05 }) declare spread: number
+  @property({ default: "", kind: "nodeRef", nodeTypes: LAYOUT_GRID_TYPES, animatable: false }) declare arrangeLike: string
+  // Unset until a command writes one, so a fresh node's row does not state them.
+  @property({ default: undefined, kind: "state", animatable: false }) declare revealState: RevealState | null | undefined
+  @property({ default: undefined, kind: "state", animatable: false }) declare waveState: WaveState | null | undefined
+  @property({ default: undefined, kind: "state", animatable: false }) declare focusState: FocusState | null | undefined
+  @property({ default: undefined, kind: "state", animatable: false }) declare transition: GridTransition | null | undefined
+
+  /**
+   * Bring the items in, one after another. Every item starts hidden, so place
+   * it where the grid enters — or after a {@link conceal}.
+   */
+  @command({ args: [{ key: "style", kind: "enum", options: REVEAL_STYLES, default: "scale" }, ...staggerArgs(0.5)] })
+  reveal(args: CommandArgs<{ style?: RevealStyle } & StaggerArgs> & { duration: number }): Command<LayoutGridProps> {
+    const style = args.data?.style ?? "scale"
+    const ease = args.easing ?? (style === "scale" || style === "flip" ? easeOut("back") : easeOut("cubic"))
+    const ranks = this._ranks(args.data?.staggerOrder)
+    const stagger = args.data?.stagger ?? 0.5
+    return this.command<LayoutGridProps>((t) => {
+      if (t >= 1) return { revealState: null }
+      return { revealState: { style, values: ranks.map((rank) => ease(staggerProgress(rank, t, stagger))) } }
+    }, args.duration)
+  }
+
+  /** Take the items out, one after another — {@link reveal} in reverse. They stay hidden after. */
+  @command({ args: [{ key: "style", kind: "enum", options: REVEAL_STYLES, default: "scale" }, ...staggerArgs(0.5)] })
+  conceal(args: CommandArgs<{ style?: RevealStyle } & StaggerArgs> & { duration: number }): Command<LayoutGridProps> {
+    const style = args.data?.style ?? "scale"
+    const ease = args.easing ?? (style === "scale" || style === "flip" ? easeIn("back") : easeInOut("cubic"))
+    const ranks = this._ranks(args.data?.staggerOrder)
+    const stagger = args.data?.stagger ?? 0.5
+    const from = this.revealState?.values
+    return this.command<LayoutGridProps>((t) => ({
+      revealState: {
+        style,
+        values: ranks.map((rank, i) => (from?.[i] ?? 1) * (1 - ease(staggerProgress(rank, t, stagger)))),
+      },
+    }), args.duration)
+  }
+
+  /** Send a ripple through the items that swells each in turn and settles back. */
+  @command({
+    args: [
+      { key: "style", kind: "enum", options: WAVE_STYLES, default: "scale" },
+      { key: "amount", min: 0, max: 2, step: 0.05, default: 0.3 },
+      ...staggerArgs(0.7),
+    ],
+  })
+  wave(args: CommandArgs<{ style?: WaveStyle; amount?: number } & StaggerArgs> & { duration: number }): Command<LayoutGridProps> {
+    const style = args.data?.style ?? "scale"
+    const amount = args.data?.amount ?? 0.3
+    const ease = args.easing ?? easeInOut("sine")
+    const ranks = this._ranks(args.data?.staggerOrder)
+    const stagger = args.data?.stagger ?? 0.7
+    return this.command<LayoutGridProps>((t) => {
+      if (t >= 1) return { waveState: null }
+      return {
+        waveState: {
+          style,
+          amount,
+          values: ranks.map((rank) => Math.sin(Math.PI * ease(staggerProgress(rank, t, stagger)))),
+        },
+      }
+    }, args.duration)
+  }
+
+  /** Bring one item (by its place in the layers, from 0) forward and push the rest back. */
+  @command({
+    args: [
+      { key: "item", min: 0, step: 1, default: 0 },
+      { key: "dim", min: 0, max: 1, step: 0.05, default: 0.7 },
+      { key: "grow", min: 0, max: 1, step: 0.05, default: 0.15 },
+    ],
+  })
+  focus(args: CommandArgs<{ item?: number; dim?: number; grow?: number }> & { duration: number }): Command<LayoutGridProps> {
+    const n = this._itemCount()
+    const item = Math.round(args.data?.item ?? 0)
+    return this._focusOn((i) => i === item, n, args)
+  }
+
+  /** Bring every item back to even. */
+  @command()
+  unfocus(args: CommandArgs<Record<string, never>> & { duration: number }): Command<LayoutGridProps> {
+    const from = this.focusState
+    const ease = args.easing ?? easeInOut("cubic")
+    return this.command<LayoutGridProps>((t) => {
+      if (t >= 1 || !from) return { focusState: null }
+      const k = 1 - ease(t)
+      return { focusState: { ...from, values: from.values.map((v) => v * k) } }
+    }, args.duration)
+  }
+
+  /** Gather the items toward the centre (`0`), back to the arrangement (`1`), or push them apart. */
+  @command({ args: [{ key: "spread", min: 0, max: 3, step: 0.05, default: 1 }] })
+  spreadTo(args: CommandArgs<{ spread: number }> & { duration: number }): Command<P> {
+    return this.to({ data: { spread: args.data?.spread ?? 1 } as Partial<P>, duration: args.duration, easing: args.easing })
+  }
+
+  /** Send every item to a random slot. The same `seed` always deals the same way. */
+  @command({ args: [{ key: "seed", min: 0, step: 1, default: 1 }, ...staggerArgs(TRANSITION_STAGGER)] })
+  shuffle(args: CommandArgs<{ seed?: number } & StaggerArgs> & { duration: number }): Command<P> {
+    const current = normalizeOrder(this.order, this._itemCount())
+    let next = shuffled(current, args.data?.seed ?? 1)
+    // A shuffle that deals everything back where it was would look like nothing happened.
+    if (next.length > 1 && next.every((item, k) => item === current[k])) next = [...next.slice(1), next[0]]
+    return this._transitionTo({ order: next } as Partial<P>, args)
+  }
+
+  /** Two items trade places, by their place in the layers. */
+  @command({
+    args: [
+      { key: "first", min: 0, step: 1, default: 0 },
+      { key: "second", min: 0, step: 1, default: 1 },
+      ...staggerArgs(0),
+    ],
+  })
+  swap(args: CommandArgs<{ first?: number; second?: number } & StaggerArgs> & { duration: number }): Command<P> {
+    const order = normalizeOrder(this.order, this._itemCount())
+    const a = order.indexOf(Math.round(args.data?.first ?? 0))
+    const b = order.indexOf(Math.round(args.data?.second ?? 1))
+    if (a >= 0 && b >= 0) [order[a], order[b]] = [order[b], order[a]]
+    return this._transitionTo({ order } as Partial<P>, args, 0)
+  }
+
+  /** Move the items into a new order — a list of layer indices, first slot first, like `"2, 0, 1"`. */
+  @command({ args: [{ key: "order", kind: "text", default: "" }, ...staggerArgs(TRANSITION_STAGGER)] })
+  reorder(args: CommandArgs<{ order?: string | number[] } & StaggerArgs> & { duration: number }): Command<P> {
+    const order = normalizeOrder(parseOrder(args.data?.order), this._itemCount())
+    return this._transitionTo({ order } as Partial<P>, args)
+  }
+
+  /**
+   * Move every item into another grid's arrangement — a grid into a ring, a ring
+   * onto a sphere — and keep following it. An empty `target` morphs back to
+   * this grid's own.
+   */
+  @command({ args: [{ key: "target", kind: "nodeRef", nodeTypes: LAYOUT_GRID_TYPES }, ...staggerArgs(TRANSITION_STAGGER)] })
+  morphInto(args: CommandArgs<{ target?: string } & StaggerArgs> & { duration: number }): Command<P> {
+    return this._transitionTo({ arrangeLike: args.data?.target ?? "" } as Partial<P>, args)
+  }
+
+  /** This grid's own arrangement, for a content box of `box`. */
+  protected abstract arrangementFor(box: Size2D): Arrangement
+
+  // A grid's size is what its items come to. The base's rule — hug only when
+  // built with children — would have a grid from a document, whose children
+  // arrive after it, fill its parent instead.
+  protected override applyDefaultSize(props?: { readonly width?: unknown; readonly height?: unknown }): void {
+    if (!props || props.width === undefined) this.applyProp("width", "hug", { tween: sizeInputOps.lerp })
+    if (!props || props.height === undefined) this.applyProp("height", "hug", { tween: sizeInputOps.lerp })
+  }
+
+  /** The room each item is measured in — the whole content box, unless an arrangement has cells. */
+  protected itemSpace(_count: number, space: Size2D, _sizes?: readonly Size2D[]): Size2D {
+    return space
+  }
+
+  override measure(constraints: SizeConstraints, scope: MeasureContext2D): Partial<Size2D> {
+    this.lastMeasure = { constraints, measurer: scope }
+    const padding = this.effectivePadding()
+    const items = this.flowChildren()
+    if (items.length === 0) {
+      this._measured = null
+      return flowOps.size(this, constraints, padding, NO_CONTENT)
+    }
+    const space = flowOps.contentBox(this, constraints, padding)
+    const sizes = this._measureItems(items, space, scope)
+    this._measured = { space, sizes }
+    return flowOps.size(this, constraints, padding, extentOf(this._targetSlots(items.length, sizes, space).slots, sizes, this._focal))
+  }
+
+  protected override layoutChildren(rect: BoxBounds, scope: MeasureContext2D): void {
+    this._placements.clear()
+    const items = this.flowChildren()
+    if (items.length === 0) {
+      this._slots = []
+      this._sizes = []
+      this._focal = 0
+      return
+    }
+    const inner = insetsOps.insetBounds(rect.width, rect.height, this.effectivePadding())
+    const measured = this._measured
+    this._measured = null
+    const sizes = measured && measured.sizes.length === items.length && sameSize(measured.space, inner)
+      ? measured.sizes
+      : this._measureItems(items, inner, scope)
+    const slots = this._resolve(sizes, inner)
+    this._slots = slots
+    this._sizes = sizes
+    for (let i = 0; i < items.length; i++) {
+      const s = slots[i]
+      items[i].layout({ x: inner.x + s.x, y: inner.y - s.y, width: sizes[i].width, height: sizes[i].height }, scope)
+      if (s.rotation !== 0 || s.scale !== 1 || s.rotationX !== 0 || s.rotationY !== 0 || s.depth !== 0 || s.opacity !== 1) {
+        this._placements.set(items[i], {
+          rotation: s.rotation,
+          scale: s.scale,
+          rotationX: s.rotationX,
+          rotationY: s.rotationY,
+          depth: s.depth,
+          opacity: s.opacity,
+        })
+      }
+    }
+  }
+
+  override _placementOf(child: Node2D): ChildPlacement | null {
+    return this._placements.get(child) ?? null
+  }
+
+  /**
+   * A grid whose arrangement has depth is seen through a camera of its own,
+   * which paints its items far to near — unless it already sits in a space (an
+   * orbit camera, a 3D stage), where its items join that one and its camera.
+   */
+  override _spaceCamera(): SpaceCamera | null {
+    const focal = this._focal
+    if (focal <= 0 || this._inSpace()) return null
+    return {
+      perspective: focal,
+      orbit: 0,
+      elevation: 0,
+      dolly: 0,
+      lookAt: CENTRE,
+      zoom: 1,
+      heading: 0,
+      viewportX: 0,
+      viewportY: 0,
+    }
+  }
+
+  private readonly _placements = new Map<Node2D, ChildPlacement>()
+  /** What {@link measure} found, for {@link layoutChildren} to reuse in the same pass. */
+  private _measured: { space: Size2D; sizes: Size2D[] } | null = null
+  /** Each item's slot from the last layout — what a command ranks its stagger by. */
+  private _slots: Slot[] = []
+  /** Each item's size from the last layout. */
+  private _sizes: readonly Size2D[] = []
+  /** The last layout's camera distance, `0` while flat. */
+  private _focal = 0
+  private _borrowCache: { id: string; grid: LayoutGrid } | null = null
+
+  /** How many items a command built now will act on. */
+  protected _itemCount(): number {
+    return this.flowChildren().length
+  }
+
+  /** Each item's slot as it stands, for a command being built — the last layout's where it still fits. */
+  protected _itemSlots(): Slot[] {
+    const n = this._itemCount()
+    if (this._slots.length === n) return this._slots
+    const sizes = new Array<Size2D>(n).fill({ width: 100, height: 100 })
+    return this._targetSlots(n, sizes, contentBoxOf(this)).slots
+  }
+
+  /** The item sizes the last layout found. */
+  protected _itemSizes(): readonly Size2D[] {
+    return this._sizes.length === this._itemCount() ? this._sizes : []
+  }
+
+  /** Each item's start in a stagger. A random order is seeded by the node's id, so it never changes between builds. */
+  protected _ranks(order: StaggerOrder | undefined): number[] {
+    return staggerRanks(order ?? "index", this._itemSlots(), hashSeed(this.id))
+  }
+
+  /**
+   * Write `changes` to the arrangement and move each item from its slot in the
+   * one being left to its slot in the new one, staggered.
+   */
+  protected _transitionTo(changes: Partial<P>, args: TransitionArgs, stagger = TRANSITION_STAGGER): Command<P> {
+    const from = this._snapshot()
+    const ease = args.easing ?? easeInOut("cubic")
+    const ranks = this._ranks(args.data?.staggerOrder)
+    const spread = args.data?.stagger ?? stagger
+    return this.command<P>((t) => {
+      if (t >= 1) return { ...changes, transition: null } as Partial<P>
+      const mix = ranks.map((rank) => ease(staggerProgress(rank, t, spread)))
+      return { ...changes, transition: { from, mix } } as Partial<P>
+    }, args.duration)
+  }
+
+  /** Emphasise the items `isFocus` picks and push the rest back. */
+  protected _focusOn(
+    isFocus: (item: number) => boolean,
+    count: number,
+    args: CommandArgs<{ dim?: number; grow?: number }> & { duration: number },
+  ): Command<LayoutGridProps> {
+    const from = this.focusState
+    const dim = args.data?.dim ?? 0.7
+    const grow = args.data?.grow ?? 0.15
+    const target = Array.from({ length: count }, (_, i) => (isFocus(i) ? 1 : -1))
+    const ease = args.easing ?? easeInOut("cubic")
+    return this.command<LayoutGridProps>((t) => {
+      const e = ease(t)
+      return {
+        focusState: {
+          dim: lerp(from?.dim ?? dim, dim, e),
+          grow: lerp(from?.grow ?? grow, grow, e),
+          values: target.map((v, i) => lerp(from?.values[i] ?? 0, v, e)),
+        },
+      }
+    }, args.duration)
+  }
+
+  private _snapshot(): GridSnapshot {
+    const source = this._borrowed()
+    return {
+      arrangement: source ? source.arrangementFor(contentBoxOf(source)) : this.arrangementFor(contentBoxOf(this)),
+      source: source?.id ?? "",
+      order: normalizeOrder(this.order, this._itemCount()),
+      spread: this.spread,
+    }
+  }
+
+  private _measureItems(items: readonly Node2D[], space: Size2D, scope: MeasureContext2D): Size2D[] {
+    const measured = flowOps.measure({}, items, space, scope).sizes
+    const cell = this.itemSpace(items.length, space, measured)
+    if (cell === space) return [...measured]
+    return [...flowOps.measure({}, items, cell, scope).sizes]
+  }
+
+  /** Where each item sits in the arrangement it is heading for, before any transition or effect. */
+  private _targetSlots(count: number, sizes: readonly Size2D[], box: Size2D): { slots: Slot[]; arrangement: Arrangement } {
+    const source = this._borrowed()
+    const arrangement = source ? source.arrangementFor(contentBoxOf(source)) : this.arrangementFor(box)
+    let slots = slotsOf(arrangement, { count, sizes, box: source ? contentBoxOf(source) : box, time: this.time.total })
+    if (source) slots = this._fromGrid(source, slots)
+    const slotOf = slotOfItem(normalizeOrder(this.order, count))
+    return { slots: slotOf.map((k) => spreadSlot(slots[k], this.spread)), arrangement }
+  }
+
+  /** Each item's final slot this frame: the target, blended from any transition, with its effects on. */
+  private _resolve(sizes: readonly Size2D[], box: Size2D): Slot[] {
+    const count = sizes.length
+    const target = this._targetSlots(count, sizes, box)
+    const slots = target.slots
+    let focal = focalLengthOf(target.arrangement)
+    const transition = this.transition
+    if (transition) {
+      const { from } = transition
+      const source = from.source ? this._gridById(from.source) : null
+      const fromBox = source ? contentBoxOf(source) : box
+      let leaving = slotsOf(from.arrangement, { count, sizes, box: fromBox, time: this.time.total })
+      if (source && source !== this) leaving = this._fromGrid(source, leaving)
+      const slotOf = slotOfItem(normalizeOrder(from.order, count))
+      for (let i = 0; i < count; i++) {
+        slots[i] = blendSlot(spreadSlot(leaving[slotOf[i]], from.spread), slots[i], transition.mix[i] ?? 1)
+      }
+      // A morph into or out of depth keeps the camera for its whole length.
+      focal = focal || focalLengthOf(from.arrangement)
+    }
+    this._focal = focal
+    const reveal = this.revealState
+    const wave = this.waveState
+    const focus = this.focusState
+    if (reveal || wave || focus) {
+      for (let i = 0; i < count; i++) applyItemEffects(slots[i], i, sizes[i], reveal, wave, focus)
+    }
+    return slots
+  }
+
+  /** Whether an ancestor places this grid in a space, as `spaceFrameOf` walks it. */
+  private _inSpace(): boolean {
+    for (let n = this.parent; n; n = n.parent) {
+      if (n._spaceCamera()) return true
+      if (!n._rendersChildrenInSpace()) return false
+    }
+    return false
+  }
+
+  /** The grid {@link arrangeLike} names, when it names another grid in this tree. */
+  private _borrowed(): LayoutGrid | null {
+    const id = this.arrangeLike
+    if (!id || id === this.id) return null
+    return this._gridById(id)
+  }
+
+  private _gridById(id: string): LayoutGrid | null {
+    if (id === this.id) return this
+    const cached = this._borrowCache
+    if (cached && cached.id === id && cached.grid.mounted) return cached.grid
+    const found = findNode2D(this, id)
+    const grid = found instanceof LayoutGrid ? found : null
+    this._borrowCache = grid ? { id, grid } : null
+    return grid
+  }
+
+  /** `slots`, laid out in `source`'s frame, moved into this grid's. */
+  private _fromGrid(source: LayoutGrid, slots: Slot[]): Slot[] {
+    const frame = frameIn(this, source)
+    return slots.map((s) => {
+      const p = rotateClockwise(s.x * frame.scale, s.y * frame.scale, frame.rotation)
+      return {
+        ...s,
+        x: frame.x + p.x,
+        y: frame.y + p.y,
+        depth: s.depth * frame.scale,
+        rotation: s.rotation + frame.rotation,
+        scale: s.scale * frame.scale,
+      }
+    })
+  }
+}
+
+/** A node's content box: its laid-out size inside its padding. */
+export function contentBoxOf(grid: Node2D): Size2D {
+  const b = grid.layoutBounds
+  const inner = insetsOps.insetBounds(b.width, b.height, grid.effectivePadding())
+  return { width: inner.width, height: inner.height }
+}
+
+/** The box, centred on the grid, that holds every item where its slot puts it. */
+function extentOf(slots: readonly Slot[], sizes: readonly Size2D[], focal: number): Size2D {
+  let halfWidth = 0
+  let halfHeight = 0
+  for (let i = 0; i < slots.length; i++) {
+    const s = slots[i]
+    const size = sizes[i]
+    const rad = (s.rotation * Math.PI) / 180
+    const cos = Math.abs(Math.cos(rad))
+    const sin = Math.abs(Math.sin(rad))
+    // What the camera does to a slot at depth, so a sphere hugs its front.
+    const lens = focal > 0 && focal - s.depth > 1 ? focal / (focal - s.depth) : 1
+    const w = ((size.width * cos + size.height * sin) / 2) * s.scale * lens
+    const h = ((size.width * sin + size.height * cos) / 2) * s.scale * lens
+    halfWidth = Math.max(halfWidth, Math.abs(s.x) * lens + w)
+    halfHeight = Math.max(halfHeight, Math.abs(s.y) * lens + h)
+  }
+  return { width: halfWidth * 2, height: halfHeight * 2 }
+}
+
+function rotateClockwise(x: number, y: number, degrees: number): { x: number; y: number } {
+  if (degrees === 0) return { x, y }
+  const rad = (degrees * Math.PI) / 180
+  const cos = Math.cos(rad)
+  const sin = Math.sin(rad)
+  return { x: x * cos + y * sin, y: -x * sin + y * cos }
+}
+
+function sameSize(a: Size2D, b: Size2D): boolean {
+  return Math.abs(a.width - b.width) < 1e-6 && Math.abs(a.height - b.height) < 1e-6
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t
+}
+
+/** The 2D node `id` names in the tree `from` is in, or `null`. */
+export function findNode2D(from: Node2D, id: string): Node2D | null {
+  let root: Node2D = from
+  while (root.parent) root = root.parent
+  return findIn(root, id)
+}
+
+function findIn(at: Node2D, id: string): Node2D | null {
+  if (at.id === id) return at
+  for (const child of at.children) {
+    const found = findIn(child, id)
+    if (found) return found
+  }
+  return null
+}
+
+/** Where `node`'s frame sits in `grid`'s: offset, turn and scale, y-up. */
+export function frameIn(grid: Node2D, node: Node2D): { x: number; y: number; rotation: number; scale: number } {
+  const there = node.global
+  const here = grid.global
+  const inverse = here.scale === 0 ? 0 : 1 / here.scale
+  const offset = rotateClockwise((there.x - here.x) * inverse, (there.y - here.y) * inverse, -here.rotation)
+  return { x: offset.x, y: offset.y, rotation: there.rotation - here.rotation, scale: there.scale * inverse }
+}

package/src/kit/order.ts

@@ -0,0 +1,41 @@
+/**
+ * A grid's `order` lists items in slot order: slot `k` holds item `order[k]`.
+ * These keep it a permutation whatever it was written as — a stale entry past
+ * the count, a repeat, or nothing at all — so a child added or removed never
+ * leaves a slot empty or two items in one.
+ */
+
+/** `order` repaired into a permutation of `0..count-1`: its valid entries first, then the rest in item order. */
+export function normalizeOrder(order: readonly number[] | undefined, count: number): number[] {
+  const out: number[] = []
+  const taken = new Array<boolean>(count).fill(false)
+  for (const entry of order ?? []) {
+    const item = Math.round(entry)
+    if (item >= 0 && item < count && !taken[item]) {
+      taken[item] = true
+      out.push(item)
+    }
+  }
+  for (let item = 0; item < count; item++) if (!taken[item]) out.push(item)
+  return out
+}
+
+/** For each item, the slot it sits in. */
+export function slotOfItem(order: readonly number[]): number[] {
+  const slots = new Array<number>(order.length)
+  order.forEach((item, slot) => {
+    slots[item] = slot
+  })
+  return slots
+}
+
+/** An order written as `"2, 0, 1"` or as numbers. */
+export function parseOrder(value: unknown): number[] {
+  if (Array.isArray(value)) return value.map(Number).filter(Number.isFinite)
+  if (typeof value !== "string") return []
+  return value
+    .split(/[\s,]+/)
+    .filter((part) => part !== "")
+    .map(Number)
+    .filter(Number.isFinite)
+}

package/src/kit/random.ts

@@ -0,0 +1,29 @@
+/** A seeded generator in `[0, 1)` — mulberry32, so a shuffle is the same on every frame and every machine. */
+export function seededRandom(seed: number): () => number {
+  let a = Math.floor(seed) >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+/** `values` in a seeded random order. */
+export function shuffled<T>(values: readonly T[], seed: number): T[] {
+  const out = [...values]
+  const random = seededRandom(seed)
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1))
+    ;[out[i], out[j]] = [out[j], out[i]]
+  }
+  return out
+}
+
+/** A stable number for a string — a node's id, so its "random" stagger never changes between builds. */
+export function hashSeed(text: string): number {
+  let h = 2166136261
+  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619)
+  return h >>> 0
+}