@motionscript/grids 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/kit/item-grid.ts

@@ -1,45 +1,75 @@
 import {
-  command,
+  commandsFor,
   easeIn,
   easeInOut,
   easeOut,
-  findNode2D,
   flowOps,
-  frameIn,
   insetsOps,
-  Node2D,
-  property,
-  sizeInputOps,
-  type BoxBounds,
-  type ChildPlacement,
-  type Command,
-  type CommandArgs,
-  type MeasureContext2D,
-  type EasingFunction,
-  type Node2DProps,
+  Types,
+  type ChildView,
+  type InsetsResolved,
+  type LayoutBox,
+  type LayoutItem,
+  type Measurer,
+  type Node2D,
+  type NodeFrame,
+  type NodeView,
+  type Piece,
+  type Placement2D,
+  type RenderContext,
   type Size2D,
-  type SizeConstraints,
   type SpaceCamera,
+  type Timeline,
+  type Values,
 } from "@motionscript/sdk"
 
-// Once this kit's own; kept on its barrel for the grids that import them from it.
-export { findNode2D, frameIn } 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"
 
+/**
+ * What every grid is built from: a container that places each of its children
+ * in a slot of an arrangement — a rectangular grid, a ring, a path, a sphere.
+ * Spread `state` and `commands` in, take `defaults`, hand `fields` the
+ * {@link Arranger} that makes this grid's arrangement from its state, and pass
+ * the finished component and its arranger through {@link define}.
+ *
+ * ## 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 state, 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 slot, 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. 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 entries
+ * (`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.
+ */
+
 /** An arrangement a grid is leaving, kept as data so its slots can be worked out afresh every frame. */
 export interface GridSnapshot {
   arrangement: Arrangement
@@ -56,28 +86,6 @@ export interface GridTransition {
   mix: readonly number[]
 }
 
-export interface ItemGridProps 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 ItemGrid.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
@@ -85,14 +93,6 @@ export interface StaggerArgs {
   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
@@ -103,448 +103,511 @@ export const ITEM_GRID_TYPES = ["rectangularGrid", "radialGrid", "pathGrid", "sp
 /** The stagger a move to new slots takes when its command states none. */
 export const TRANSITION_STAGGER = 0.3
 
+/** A reference to another node, a host's picker offering only `types`. Its fields read a view of it. */
+export function nodeRef(types: readonly string[]) {
+  const described = { kind: "nodeRef", nodeTypes: types, animatable: false }
+  return Types.custom<string, NodeView | null>("", described)
+}
+
+/** The stagger args every per-item command takes, `stagger` defaulting to `fallback`. */
+export function staggerArgs(fallback: number) {
+  return {
+    staggerOrder: Types.oneOf(STAGGER_ORDERS, { default: "index" }),
+    stagger: Types.number(fallback, { min: 0, max: 0.95, step: 0.05 }),
+  }
+}
+
+/**
+ * A command arg a host fills in with `hint`, which a row may leave out: the
+ * command then keeps what the grid has. A run arg's default is both what a
+ * host offers and what an omitted arg means, so the hint rides on the arg's
+ * description alone, and an omitted arg reads `undefined`.
+ */
+export function hinted<T extends number | string>(hint: T, options: object = {}) {
+  const described: Record<string, unknown> = { ...options, default: hint }
+  return Types.custom<T | undefined>(undefined, described as never)
+}
+
+/** A command arg naming another node, a host's picker offering only `types`; left out, it reads `undefined`. */
+export function nodeRefArg(types: readonly string[]) {
+  const described = { kind: "nodeRef", nodeTypes: types }
+  return Types.custom<string | undefined>(undefined, described)
+}
+
+/** The state every grid shares. */
+export const state = {
+  /** Items in slot order: slot `k` holds child `order[k]`. Empty is the children's own order. */
+  order: Types.custom<number[]>([], { kind: "order", animatable: false }),
+  /** `0` gathers every item at the centre, `1` is the arrangement, past `1` pushes them apart. */
+  spread: Types.number(1, { min: 0, max: 3, step: 0.05 }),
+  /** Another grid whose arrangement this one takes on — what `morphInto` animates. */
+  arrangeLike: nodeRef(ITEM_GRID_TYPES),
+  // 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. Unset
+  // until a command writes one, so a fresh node's row does not state them.
+  revealState: Types.custom<RevealState | null | undefined>(undefined, { kind: "state", animatable: false }),
+  waveState: Types.custom<WaveState | null | undefined>(undefined, { kind: "state", animatable: false }),
+  focusState: Types.custom<FocusState | null | undefined>(undefined, { kind: "state", animatable: false }),
+  transition: Types.custom<GridTransition | null | undefined>(undefined, { kind: "state", animatable: false }),
+  /** The grid a transition's leaving arrangement was borrowed from, followed while the items travel. */
+  transitionSource: Types.custom<string, NodeView | null, { readonly private: true }>("", { kind: "nodeRef", private: true }),
+}
+
+/** A grid's size is what its items come to, whether it was built with children or they arrive after it. */
+export const defaults = { width: "hug", height: "hug" } as const
+
+/** What a grid's commands read of its state, beyond its own arrangement's entries. */
+export type GridValues = Values<typeof state> & { readonly padding: InsetsResolved }
+
+/** What a grid's measure, layout and render read of its state, beyond its own arrangement's entries. */
+export type GridState = GridValues & {
+  readonly width: LayoutItem["width"]
+  readonly height: LayoutItem["height"]
+  readonly children: readonly ChildView[]
+}
+
+/** What makes one grid's arrangement from its state: the rest of a grid is this module. */
+export interface Arranger<S = unknown> {
+  /** This grid's own arrangement, for a content box of `box`. */
+  arrangement(state: S, box: Size2D): Arrangement
+  /** The room each item is measured in — the whole content box, unless the arrangement has cells. */
+  itemSpace?(state: S, count: number, space: Size2D): Size2D
+}
+
+type GridComponent = { readonly key: string; readonly node: abstract new (...args: never[]) => object }
+
+const GRIDS = new Map<string, { readonly component: GridComponent; readonly arranger: Arranger<never> }>()
+
+/**
+ * `component` as a grid: registers its `arranger`, which another grid borrowing
+ * its arrangement or morphing into it reads it by, and which {@link isGrid} knows it by.
+ */
+export function define<C extends GridComponent, S>(component: C, arranger: Arranger<S>): C {
+  GRIDS.set(component.key, { component, arranger: arranger as Arranger<never> })
+  return component
+}
+
+/** Whether `value` is a node of one of the grids {@link define} has seen. */
+export function isGrid(value: unknown): boolean {
+  for (const { component } of GRIDS.values()) if (value instanceof component.node) return true
+  return false
+}
+
+/** The grid's measure, layout and render, for `arranger`'s arrangement: spread them into the component. */
+export function fields<S>(arranger: Arranger<S>) {
+  return {
+    measure: (measurer: Measurer, s: GridState & S, children: readonly ChildView[]) => measure(measurer, s, children, arranger),
+    layout: (box: LayoutBox, s: GridState & S, children: readonly ChildView[]) => layout(box, s, children, arranger),
+    render: (ctx: RenderContext, s: GridState & S) => render(ctx, s, arranger),
+  }
+}
+
 const NO_CONTENT: Size2D = { width: 0, height: 0 }
 const CENTRE = { x: 0, y: 0 }
 
+/** What `measure` found, for `layout` to reuse in the same pass. Keyed by the grid's state, one object per node. */
+const measured = new WeakMap<object, { space: Size2D; sizes: Size2D[] }>()
+
+export function measure<S>(measurer: Measurer, s: GridState & S, children: readonly ChildView[], arranger: Arranger<S>): Size2D {
+  const constraints = { maxWidth: measurer.max.width, maxHeight: measurer.max.height }
+  const padding = s.padding
+  if (children.length === 0) {
+    measured.delete(s)
+    return flowOps.size(s, constraints, padding, NO_CONTENT)
+  }
+  const space = flowOps.contentBox(s, constraints, padding)
+  const sizes = measureItems(children, space, s, arranger)
+  measured.set(s, { space, sizes })
+  const grid = { state: s, arranger, children, isSelf: sharesChildren(children) }
+  const target = targetSlots(grid, sizes.length, sizes, space, measurer.time.total)
+  return flowOps.size(s, constraints, padding, extentOf(target.slots, sizes, focalOf(s, target.arrangement)))
+}
+
+export function layout<S>(box: LayoutBox, s: GridState & S, children: readonly ChildView[], arranger: Arranger<S>): readonly Placement2D[] {
+  const kept = measured.get(s)
+  measured.delete(s)
+  if (children.length === 0) return []
+  const inner = insetsOps.insetBounds(box.width, box.height, s.padding)
+  const sizes = kept && kept.sizes.length === children.length && sameSize(kept.space, inner)
+    ? kept.sizes
+    : measureItems(children, inner, s, arranger)
+  const slots = resolve({ state: s, arranger, children, isSelf: sharesChildren(children) }, sizes, inner, box.time.total)
+  return slots.map((slot, i) => placement(inner, slot, sizes[i]))
+}
+
 /**
- * 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.
+ * 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.
  */
-export abstract class ItemGrid<P extends ItemGridProps = ItemGridProps> 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: ITEM_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
+export function render<S>(ctx: RenderContext, s: GridState & S, arranger: Arranger<S>): void {
+  // With no items there is nothing to see through a camera.
+  const focal = s.children.length === 0 ? 0 : focalOf(s, arrangementOf({ state: s, arranger, children: [], isSelf: () => false }, contentBox(ctx.size, s.padding)))
+  if (focal > 0 && !ctx.inSpace) ctx.space(cameraAt(focal))
+  else ctx.children()
+}
 
-  /**
-   * 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<ItemGridProps> {
-    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<ItemGridProps>((t) => {
-      if (t >= 1) return { revealState: null }
-      return { revealState: { style, values: ranks.map((rank) => ease(staggerProgress(rank, t, stagger))) } }
-    }, args.duration)
-  }
+/** A node's content box: its laid-out size inside its padding. */
+export function contentBoxOf(grid: Node2D): Size2D {
+  const b = grid.layoutBounds
+  return contentBox({ width: b.width, height: b.height }, grid.effectivePadding())
+}
+
+// ---- what commands share --------------------------------------------------
 
-  /** 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<ItemGridProps> {
-    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<ItemGridProps>((t) => ({
-      revealState: {
-        style,
-        values: ranks.map((rank, i) => (from?.[i] ?? 1) * (1 - ease(staggerProgress(rank, t, stagger)))),
+type GridTimeline = Timeline<StaggerArgs, never>
+
+/**
+ * Each item's slot in its arrangement as it stands, for a command being built,
+ * at the clock commands are built against (the tree stands at time 0 while a
+ * timeline compiles): what its stagger is ranked by.
+ */
+export function itemSlots(timeline: Timeline<object, never>, s: GridValues, children: readonly ChildView[]): Slot[] {
+  const grid = commandGrid(timeline, s, children)
+  const sizes = children.map((child) => child.size)
+  return targetSlots(grid, children.length, sizes, contentBox(timeline.node.size, s.padding), 0).slots
+}
+
+/** Each item's start in a stagger. A random order is seeded by the node's id, so it never changes between builds. */
+export function ranks(timeline: Timeline<object, never>, s: GridValues, children: readonly ChildView[], order: StaggerOrder | undefined): number[] {
+  return staggerRanks(order ?? "index", itemSlots(timeline, s, children), hashSeed(timeline.node.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.
+ */
+export function transitionTo(
+  timeline: GridTimeline,
+  s: GridValues,
+  children: readonly ChildView[],
+  changes: Record<string, unknown>,
+  stagger = TRANSITION_STAGGER,
+): Piece {
+  const from = snapshot(timeline, s, children)
+  const ease = timeline.easing ?? easeInOut("cubic")
+  const order = ranks(timeline, s, children, timeline.args.staggerOrder)
+  const spread = timeline.args.stagger ?? stagger
+  return timeline.animate((t) => {
+    if (t >= 1) return { ...changes, transition: null, transitionSource: "" } as never
+    const mix = order.map((rank) => ease(staggerProgress(rank, t, spread)))
+    return { ...changes, transition: { from, mix }, transitionSource: from.source } as never
+  }, { eased: false })
+}
+
+/** Emphasise the items `isFocus` picks and push the rest back. */
+export function focusOn(
+  timeline: Timeline<object, never>,
+  s: GridValues,
+  isFocus: (item: number) => boolean,
+  count: number,
+  dim: number,
+  grow: number,
+): Piece {
+  const from = s.focusState
+  const target = Array.from({ length: count }, (_, i) => (isFocus(i) ? 1 : -1))
+  const ease = timeline.easing ?? easeInOut("cubic")
+  return timeline.animate((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)
-  }
+    } as never
+  }, { eased: false })
+}
 
-  /** 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<ItemGridProps> {
-    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<ItemGridProps>((t) => {
-      if (t >= 1) return { waveState: null }
-      return {
-        waveState: {
+// What the commands are typed against: the shared state, and the padding every node has.
+const GRID_STATE = { ...state, padding: Types.insets }
+
+export const commands = commandsFor(GRID_STATE, {
+  /**
+   * Bring the items in, one after another. Every item starts hidden, so place
+   * it where the grid enters — or after a `conceal`.
+   */
+  reveal: {
+    args: { style: Types.oneOf(REVEAL_STYLES, { default: "scale" }), ...staggerArgs(0.5) },
+    run: (timeline, s, children) => {
+      const style = timeline.args.style ?? "scale"
+      const ease = timeline.easing ?? (style === "scale" || style === "flip" ? easeOut("back") : easeOut("cubic"))
+      const order = ranks(timeline as never, s, children, timeline.args.staggerOrder)
+      const stagger = timeline.args.stagger ?? 0.5
+      return timeline.animate((t) => {
+        if (t >= 1) return { revealState: null }
+        return { revealState: { style, values: order.map((rank) => ease(staggerProgress(rank, t, stagger))) } }
+      }, { eased: false })
+    },
+  },
+  /** Take the items out, one after another — `reveal` in reverse. They stay hidden after. */
+  conceal: {
+    args: { style: Types.oneOf(REVEAL_STYLES, { default: "scale" }), ...staggerArgs(0.5) },
+    run: (timeline, s, children) => {
+      const style = timeline.args.style ?? "scale"
+      const ease = timeline.easing ?? (style === "scale" || style === "flip" ? easeIn("back") : easeInOut("cubic"))
+      const order = ranks(timeline as never, s, children, timeline.args.staggerOrder)
+      const stagger = timeline.args.stagger ?? 0.5
+      const from = s.revealState?.values
+      return timeline.animate((t) => ({
+        revealState: {
           style,
-          amount,
-          values: ranks.map((rank) => Math.sin(Math.PI * ease(staggerProgress(rank, t, stagger)))),
+          values: order.map((rank, i) => (from?.[i] ?? 1) * (1 - ease(staggerProgress(rank, t, stagger)))),
         },
-      }
-    }, args.duration)
-  }
-
+      }), { eased: false })
+    },
+  },
+  /** Send a ripple through the items that swells each in turn and settles back. */
+  wave: {
+    args: {
+      style: Types.oneOf(WAVE_STYLES, { default: "scale" }),
+      amount: Types.number(0.3, { min: 0, max: 2, step: 0.05 }),
+      ...staggerArgs(0.7),
+    },
+    run: (timeline, s, children) => {
+      const style = timeline.args.style ?? "scale"
+      const amount = timeline.args.amount ?? 0.3
+      const ease = timeline.easing ?? easeInOut("sine")
+      const order = ranks(timeline as never, s, children, timeline.args.staggerOrder)
+      const stagger = timeline.args.stagger ?? 0.7
+      return timeline.animate((t) => {
+        if (t >= 1) return { waveState: null }
+        return { waveState: { style, amount, values: order.map((rank) => Math.sin(Math.PI * ease(staggerProgress(rank, t, stagger)))) } }
+      }, { eased: false })
+    },
+  },
   /** 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<ItemGridProps> {
-    const n = this._itemCount()
-    const item = Math.round(args.data?.item ?? 0)
-    return this._focusOn((i) => i === item, n, args)
-  }
-
+  focus: {
+    args: {
+      item: Types.number(0, { min: 0, step: 1 }),
+      dim: Types.number(0.7, { min: 0, max: 1, step: 0.05 }),
+      grow: Types.number(0.15, { min: 0, max: 1, step: 0.05 }),
+    },
+    run: (timeline, s, children) => {
+      const item = Math.round(timeline.args.item ?? 0)
+      return focusOn(timeline as never, s, (i) => i === item, children.length, timeline.args.dim ?? 0.7, timeline.args.grow ?? 0.15)
+    },
+  },
   /** Bring every item back to even. */
-  @command()
-  unfocus(args: CommandArgs<Record<string, never>> & { duration: number }): Command<ItemGridProps> {
-    const from = this.focusState
-    const ease = args.easing ?? easeInOut("cubic")
-    return this.command<ItemGridProps>((t) => {
+  unfocus: (timeline, s) => {
+    const from = s.focusState
+    const ease = timeline.easing ?? easeInOut("cubic")
+    return timeline.animate((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)
-  }
-
+    }, { eased: false })
+  },
   /** 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 })
-  }
-
+  spreadTo: {
+    args: { spread: Types.number(1, { min: 0, max: 3, step: 0.05 }) },
+    run: (timeline) => timeline.tween({ spread: timeline.args.spread ?? 1 }),
+  },
   /** 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)
-  }
-
+  shuffle: {
+    args: { seed: Types.number(1, { min: 0, step: 1 }), ...staggerArgs(TRANSITION_STAGGER) },
+    run: (timeline, s, children) => {
+      const current = normalizeOrder(s.order, children.length)
+      let next = shuffled(current, timeline.args.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 transitionTo(timeline as never, s, children, { order: next })
+    },
+  },
   /** 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 },
+  swap: {
+    args: {
+      first: Types.number(0, { min: 0, step: 1 }),
+      second: Types.number(1, { min: 0, step: 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)
-  }
-
+    },
+    run: (timeline, s, children) => {
+      const order = normalizeOrder(s.order, children.length)
+      const a = order.indexOf(Math.round(timeline.args.first ?? 0))
+      const b = order.indexOf(Math.round(timeline.args.second ?? 1))
+      if (a >= 0 && b >= 0) [order[a], order[b]] = [order[b], order[a]]
+      return transitionTo(timeline as never, s, children, { order }, 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)
-  }
-
+  reorder: {
+    args: { order: Types.text(""), ...staggerArgs(TRANSITION_STAGGER) },
+    run: (timeline, s, children) => {
+      const order = normalizeOrder(parseOrder(timeline.args.order), children.length)
+      return transitionTo(timeline as never, s, children, { order })
+    },
+  },
   /**
    * 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: ITEM_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,
-        })
-      }
-    }
-  }
+  morphInto: {
+    args: { target: nodeRefArg(ITEM_GRID_TYPES), ...staggerArgs(TRANSITION_STAGGER) },
+    run: (timeline, s, children) => transitionTo(timeline as never, s, children, { arrangeLike: timeline.args.target ?? "" }),
+  },
+})
+
+// ---- the one pass ------------------------------------------------------------
+
+interface Grid {
+  readonly state: GridValues
+  readonly arranger: Arranger<never>
+  readonly children: readonly ChildView[]
+  /** Whether a view is this grid itself, which borrows nothing from itself. */
+  readonly isSelf: (view: NodeView) => boolean
+}
 
-  override _placementOf(child: Node2D): ChildPlacement | null {
-    return this._placements.get(child) ?? null
-  }
+function arrangerOf(key: string): Arranger<never> {
+  const grid = GRIDS.get(key)
+  if (!grid) throw new Error(`"${key}" is no grid: pass its component through ItemGrid.define.`)
+  return grid.arranger
+}
 
-  /**
-   * 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,
-    }
-  }
+/** A grid `view` names, when it is one this kit can arrange and not the reader itself. */
+function gridIn(view: NodeView | null | undefined, grid: Grid): { view: NodeView; arranger: Arranger<never> } | null {
+  if (!view) return null
+  const found = GRIDS.get(view.key)
+  if (!found || grid.isSelf(view)) return null
+  return { view, arranger: found.arranger }
+}
 
-  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: ItemGrid } | null = null
-
-  /** How many items a command built now will act on. */
-  protected _itemCount(): number {
-    return this.flowChildren().length
+/** In layout, a view is this grid when it holds the same children: a child has one parent. */
+function sharesChildren(children: readonly ChildView[]): (view: NodeView) => boolean {
+  return (view) => {
+    if (children.length === 0) return false
+    const theirs = (view.state as { readonly children?: readonly ChildView[] }).children
+    return theirs?.[0] === children[0]
   }
+}
 
-  /** 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
-  }
+function commandGrid(timeline: Timeline<object, never>, s: GridValues, children: readonly ChildView[]): Grid {
+  return { state: s, arranger: arrangerOf(timeline.node.key), children, isSelf: (view) => view.id === timeline.node.id }
+}
 
-  /** The item sizes the last layout found. */
-  protected _itemSizes(): readonly Size2D[] {
-    return this._sizes.length === this._itemCount() ? this._sizes : []
+function snapshot(timeline: Timeline<object, never>, s: GridValues, children: readonly ChildView[]): GridSnapshot {
+  const grid = commandGrid(timeline, s, children)
+  const source = gridIn(s.arrangeLike, grid)
+  return {
+    arrangement: source
+      ? source.arranger.arrangement(source.view.state as never, viewBox(source.view))
+      : grid.arranger.arrangement(s as never, contentBox(timeline.node.size, s.padding)),
+    source: source?.view.id ?? "",
+    order: normalizeOrder(s.order, children.length),
+    spread: s.spread,
   }
+}
 
-  /** 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))
-  }
+function measureItems(children: readonly ChildView[], space: Size2D, s: unknown, arranger: Arranger<never>): Size2D[] {
+  const sizes = children.map((child) => child.measure(space))
+  const cell = arranger.itemSpace ? arranger.itemSpace(s as never, children.length, space) : space
+  if (cell === space) return sizes
+  return children.map((child) => child.measure(cell))
+}
 
-  /**
-   * 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)
-  }
+/** The arrangement the grid is heading for: the one it borrows, or its own. */
+function arrangementOf(grid: Grid, box: Size2D): Arrangement {
+  const source = gridIn(grid.state.arrangeLike, grid)
+  return source ? source.arranger.arrangement(source.view.state as never, viewBox(source.view)) : grid.arranger.arrangement(grid.state as never, box)
+}
 
-  /** 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<ItemGridProps> {
-    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<ItemGridProps>((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)
-  }
+/** Where each item sits in the arrangement it is heading for, before any transition or effect. */
+function targetSlots(grid: Grid, count: number, sizes: readonly Size2D[], box: Size2D, time: number): { slots: Slot[]; arrangement: Arrangement } {
+  const s = grid.state
+  const source = gridIn(s.arrangeLike, grid)
+  const sourceBox = source ? viewBox(source.view) : box
+  const arrangement = source ? source.arranger.arrangement(source.view.state as never, sourceBox) : grid.arranger.arrangement(s as never, box)
+  let slots = slotsOf(arrangement, { count, sizes, box: sourceBox, time })
+  if (source) slots = inFrame(source.view.frame, slots)
+  const slotOf = slotOfItem(normalizeOrder(s.order, count))
+  return { slots: slotOf.map((k) => spreadSlot(slots[k], s.spread)), arrangement }
+}
 
-  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,
+/** Each item's final slot this frame: the target, blended from any transition, with its effects on. */
+function resolve(grid: Grid, sizes: readonly Size2D[], box: Size2D, time: number): Slot[] {
+  const s = grid.state
+  const count = sizes.length
+  const slots = targetSlots(grid, count, sizes, box, time).slots
+  const transition = s.transition
+  if (transition) {
+    const { from } = transition
+    const named = from.source ? s.transitionSource : null
+    const source = named && named.id === from.source && GRIDS.has(named.key) ? named : null
+    const self = source !== null && grid.isSelf(source)
+    const fromBox = source && !self ? viewBox(source) : box
+    let leaving = slotsOf(from.arrangement, { count, sizes, box: fromBox, time })
+    if (source && !self) leaving = inFrame(source.frame, 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)
     }
   }
-
-  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 }
+  const reveal = s.revealState
+  const wave = s.waveState
+  const focus = s.focusState
+  if (reveal || wave || focus) {
+    for (let i = 0; i < count; i++) applyItemEffects(slots[i], i, sizes[i], reveal, wave, focus)
   }
+  return slots
+}
 
-  /** 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
-  }
+/** The camera distance the grid is seen through: the target's, or, while a morph runs, the one it is leaving. */
+function focalOf(s: GridValues, target: Arrangement): number {
+  // A morph into or out of depth keeps the camera for its whole length.
+  return focalLengthOf(target) || (s.transition ? focalLengthOf(s.transition.from.arrangement) : 0)
+}
 
-  /** 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
+function cameraAt(focal: number): SpaceCamera {
+  return {
+    perspective: focal,
+    orbit: 0,
+    elevation: 0,
+    dolly: 0,
+    lookAt: CENTRE,
+    zoom: 1,
+    heading: 0,
+    viewportX: 0,
+    viewportY: 0,
   }
+}
 
-  /** The grid {@link arrangeLike} names, when it names another grid in this tree. */
-  private _borrowed(): ItemGrid | null {
-    const id = this.arrangeLike
-    if (!id || id === this.id) return null
-    return this._gridById(id)
+/** A slot as a child's placement: its box centred on the slot, and the slot's transform when it has one. */
+function placement(inner: { x: number; y: number }, s: Slot, size: Size2D): Placement2D {
+  const box = { x: inner.x + s.x, y: s.y - inner.y, width: size.width, height: size.height }
+  if (s.rotation === 0 && s.scale === 1 && s.rotationX === 0 && s.rotationY === 0 && s.depth === 0 && s.opacity === 1) return box
+  return {
+    ...box,
+    rotation: s.rotation,
+    scale: s.scale,
+    rotationX: s.rotationX,
+    rotationY: s.rotationY,
+    depth: s.depth,
+    opacity: s.opacity,
   }
+}
 
-  private _gridById(id: string): ItemGrid | 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 ItemGrid ? found : null
-    this._borrowCache = grid ? { id, grid } : null
-    return grid
-  }
+/** `slots`, laid out in another grid's frame, moved into this grid's. */
+function inFrame(frame: NodeFrame, slots: Slot[]): Slot[] {
+  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,
+    }
+  })
+}
 
-  /** `slots`, laid out in `source`'s frame, moved into this grid's. */
-  private _fromGrid(source: ItemGrid, 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,
-      }
-    })
-  }
+function viewBox(view: NodeView): Size2D {
+  return contentBox(view.size, (view.state as { readonly padding: InsetsResolved }).padding)
 }
 
-/** 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())
+/** A box of `size` inside `padding`: what a command reads as its grid's content box from `timeline.node.size`. */
+export function contentBox(size: Size2D, padding: InsetsResolved): Size2D {
+  const inner = insetsOps.insetBounds(size.width, size.height, padding)
   return { width: inner.width, height: inner.height }
 }