@canvas-commons/2d 0.2.0

package/src/lib/components/Node.ts

@@ -0,0 +1,1941 @@
+import {
+  BBox,
+  ColorSignal,
+  DependencyContext,
+  PossibleColor,
+  PossibleSpacing,
+  PossibleVector2,
+  Promisable,
+  ReferenceReceiver,
+  Signal,
+  SignalValue,
+  SimpleSignal,
+  SimpleVector2Signal,
+  SpacingSignal,
+  ThreadGenerator,
+  TimingFunction,
+  UNIFORM_DESTINATION_MATRIX,
+  UNIFORM_SOURCE_MATRIX,
+  UNIFORM_TIME,
+  Vector2,
+  Vector2Signal,
+  all,
+  clamp,
+  createSignal,
+  easeInOutCubic,
+  isReactive,
+  threadable,
+  transformScalar,
+  unwrap,
+  useLogger,
+} from '@canvas-commons/core';
+import {
+  NODE_NAME,
+  cloneable,
+  colorSignal,
+  computed,
+  getPropertiesOf,
+  initial,
+  initializeSignals,
+  inspectable,
+  nodeName,
+  parser,
+  signal,
+  vector2Signal,
+  wrapper,
+} from '../decorators';
+import {FiltersSignal, filtersSignal} from '../decorators/filtersSignal';
+import {spacingSignal} from '../decorators/spacingSignal';
+import {
+  PositionSignal,
+  RotationSignal,
+  ScaleSignal,
+  positionSignal,
+  rotationSignal,
+  scaleSignal,
+} from '../decorators/transformSignals';
+import {Filter} from '../partials';
+import {
+  PossibleShaderConfig,
+  ShaderConfig,
+  parseShader,
+} from '../partials/ShaderConfig';
+import {useScene2D} from '../scenes/useScene2D';
+import {drawLine} from '../utils';
+import type {ComponentChild, ComponentChildren, NodeConstructor} from './types';
+import type {View2D} from './View2D';
+
+export type NodeState = NodeProps & Record<string, any>;
+
+export interface NodeProps {
+  ref?: ReferenceReceiver<any>;
+  children?: SignalValue<ComponentChildren>;
+  /**
+   * @deprecated Use {@link children} instead.
+   */
+  spawner?: SignalValue<ComponentChildren>;
+  key?: string;
+
+  x?: SignalValue<number>;
+  y?: SignalValue<number>;
+  position?: SignalValue<PossibleVector2>;
+  rotation?: SignalValue<number>;
+  scaleX?: SignalValue<number>;
+  scaleY?: SignalValue<number>;
+  scale?: SignalValue<PossibleVector2>;
+  skewX?: SignalValue<number>;
+  skewY?: SignalValue<number>;
+  skew?: SignalValue<PossibleVector2>;
+  zIndex?: SignalValue<number>;
+
+  opacity?: SignalValue<number>;
+  filters?: SignalValue<Filter[]>;
+
+  shadowColor?: SignalValue<PossibleColor>;
+  shadowBlur?: SignalValue<number>;
+  shadowOffsetX?: SignalValue<number>;
+  shadowOffsetY?: SignalValue<number>;
+  shadowOffset?: SignalValue<PossibleVector2>;
+
+  cache?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc Node.cachePadding}
+   */
+  cachePaddingTop?: SignalValue<number>;
+  /**
+   * {@inheritDoc Node.cachePadding}
+   */
+  cachePaddingBottom?: SignalValue<number>;
+  /**
+   * {@inheritDoc Node.cachePadding}
+   */
+  cachePaddingLeft?: SignalValue<number>;
+  /**
+   * {@inheritDoc Node.cachePadding}
+   */
+  cachePaddingRight?: SignalValue<number>;
+  /**
+   * {@inheritDoc Node.cachePadding}
+   */
+  cachePadding?: SignalValue<PossibleSpacing>;
+
+  composite?: SignalValue<boolean>;
+  compositeOperation?: SignalValue<GlobalCompositeOperation>;
+  /**
+   * @experimental
+   */
+  shaders?: PossibleShaderConfig;
+}
+
+@nodeName('Node')
+export class Node implements Promisable<Node> {
+  /**
+   * @internal
+   */
+  declare public readonly [NODE_NAME]: string;
+  declare public isClass: boolean;
+
+  /**
+   * Represents the position of this node in local space of its parent.
+   *
+   * @example
+   * Initializing the position:
+   * ```tsx
+   * // with a possible vector:
+   * <Node position={[1, 2]} />
+   * // with individual components:
+   * <Node x={1} y={2} />
+   * ```
+   *
+   * Accessing the position:
+   * ```tsx
+   * // retrieving the vector:
+   * const position = node.position();
+   * // retrieving an individual component:
+   * const x = node.position.x();
+   * ```
+   *
+   * Setting the position:
+   * ```tsx
+   * // with a possible vector:
+   * node.position([1, 2]);
+   * node.position(() => [1, 2]);
+   * // with individual components:
+   * node.position.x(1);
+   * node.position.x(() => 1);
+   * ```
+   */
+  @positionSignal()
+  declare public readonly position: PositionSignal<this>;
+
+  public get x() {
+    return this.position.x as SimpleSignal<number, this>;
+  }
+  public get y() {
+    return this.position.y as SimpleSignal<number, this>;
+  }
+
+  /**
+   * A helper signal for operating on the position in world space.
+   *
+   * @remarks
+   * Retrieving the position using this signal returns the position in world
+   * space. Similarly, setting the position using this signal transforms the
+   * new value to local space.
+   *
+   * If the new value is a function, the position of this node will be
+   * continuously updated to always match the position returned by the function.
+   * This can be useful to "pin" the node in a specific place or to make it
+   * follow another node's position.
+   *
+   * Unlike {@link position}, this signal is not compound - it doesn't contain
+   * separate signals for the `x` and `y` components.
+   *
+   * @deprecated Use `position.abs` instead.
+   */
+  @wrapper(Vector2)
+  @cloneable(false)
+  @signal()
+  declare public readonly absolutePosition: SimpleVector2Signal<this>;
+
+  protected getAbsolutePosition(): Vector2 {
+    return this.position.abs();
+  }
+
+  protected setAbsolutePosition(value: SignalValue<PossibleVector2>) {
+    this.position.abs(value);
+  }
+
+  /**
+   * Represents the rotation (in degrees) of this node relative to its parent.
+   */
+  @initial(0)
+  @rotationSignal()
+  declare public readonly rotation: RotationSignal<this>;
+
+  /**
+   * A helper signal for operating on the rotation in world space.
+   *
+   * @remarks
+   * Retrieving the rotation using this signal returns the rotation in world
+   * space. Similarly, setting the rotation using this signal transforms the
+   * new value to local space.
+   *
+   * If the new value is a function, the rotation of this node will be
+   * continuously updated to always match the rotation returned by the function.
+   *
+   * @deprecated Use `rotation.abs` instead.
+   */
+  @cloneable(false)
+  @signal()
+  declare public readonly absoluteRotation: SimpleSignal<number, this>;
+
+  protected getAbsoluteRotation() {
+    return this.rotation.abs();
+  }
+
+  protected setAbsoluteRotation(value: SignalValue<number>) {
+    this.rotation.abs(value);
+  }
+
+  /**
+   * Represents the scale of this node in local space of its parent.
+   *
+   * @example
+   * Initializing the scale:
+   * ```tsx
+   * // with a possible vector:
+   * <Node scale={[1, 2]} />
+   * // with individual components:
+   * <Node scaleX={1} scaleY={2} />
+   * ```
+   *
+   * Accessing the scale:
+   * ```tsx
+   * // retrieving the vector:
+   * const scale = node.scale();
+   * // retrieving an individual component:
+   * const scaleX = node.scale.x();
+   * ```
+   *
+   * Setting the scale:
+   * ```tsx
+   * // with a possible vector:
+   * node.scale([1, 2]);
+   * node.scale(() => [1, 2]);
+   * // with individual components:
+   * node.scale.x(1);
+   * node.scale.x(() => 1);
+   * ```
+   */
+  @initial(Vector2.one)
+  @scaleSignal('scale')
+  declare public readonly scale: ScaleSignal<this>;
+
+  /**
+   * Represents the skew of this node in local space of its parent.
+   *
+   * @example
+   * Initializing the skew:
+   * ```tsx
+   * // with a possible vector:
+   * <Node skew={[40, 20]} />
+   * // with individual components:
+   * <Node skewX={40} skewY={20} />
+   * ```
+   *
+   * Accessing the skew:
+   * ```tsx
+   * // retrieving the vector:
+   * const skew = node.skew();
+   * // retrieving an individual component:
+   * const skewX = node.skew.x();
+   * ```
+   *
+   * Setting the skew:
+   * ```tsx
+   * // with a possible vector:
+   * node.skew([40, 20]);
+   * node.skew(() => [40, 20]);
+   * // with individual components:
+   * node.skew.x(40);
+   * node.skew.x(() => 40);
+   * ```
+   */
+  @initial(Vector2.zero)
+  @vector2Signal('skew')
+  declare public readonly skew: Vector2Signal<this>;
+
+  /**
+   * A helper signal for operating on the scale in world space.
+   *
+   * @remarks
+   * Retrieving the scale using this signal returns the scale in world space.
+   * Similarly, setting the scale using this signal transforms the new value to
+   * local space.
+   *
+   * If the new value is a function, the scale of this node will be continuously
+   * updated to always match the position returned by the function.
+   *
+   * Unlike {@link scale}, this signal is not compound - it doesn't contain
+   * separate signals for the `x` and `y` components.
+   *
+   * @deprecated Use `scale.abs` instead.
+   */
+  @wrapper(Vector2)
+  @cloneable(false)
+  @signal()
+  declare public readonly absoluteScale: SimpleVector2Signal<this>;
+
+  protected getAbsoluteScale(): Vector2 {
+    return this.scale.abs();
+  }
+
+  protected setAbsoluteScale(value: SignalValue<PossibleVector2>) {
+    this.scale.abs(value);
+  }
+
+  @initial(0)
+  @signal()
+  declare public readonly zIndex: SimpleSignal<number, this>;
+
+  @initial(false)
+  @signal()
+  declare public readonly cache: SimpleSignal<boolean, this>;
+
+  /**
+   * Controls the padding of the cached canvas used by this node.
+   *
+   * @remarks
+   * By default, the size of the cache is determined based on the bounding box
+   * of the node and its children. That includes effects such as stroke or
+   * shadow. This property can be used to expand the cache area further.
+   * Usually used to account for custom effects created by {@link shaders}.
+   */
+  @spacingSignal('cachePadding')
+  declare public readonly cachePadding: SpacingSignal<this>;
+
+  @initial(false)
+  @signal()
+  declare public readonly composite: SimpleSignal<boolean, this>;
+
+  @initial('source-over')
+  @signal()
+  declare public readonly compositeOperation: SimpleSignal<
+    GlobalCompositeOperation,
+    this
+  >;
+
+  private readonly compositeOverride = createSignal(0);
+
+  @threadable()
+  protected *tweenCompositeOperation(
+    value: SignalValue<GlobalCompositeOperation>,
+    time: number,
+    timingFunction: TimingFunction,
+  ) {
+    const nextValue = unwrap(value);
+    if (nextValue === 'source-over') {
+      yield* this.compositeOverride(1, time, timingFunction);
+      this.compositeOverride(0);
+      this.compositeOperation(nextValue);
+    } else {
+      this.compositeOperation(nextValue);
+      this.compositeOverride(1);
+      yield* this.compositeOverride(0, time, timingFunction);
+    }
+  }
+
+  /**
+   * Represents the opacity of this node in the range 0-1.
+   *
+   * @remarks
+   * The value is clamped to the range 0-1.
+   */
+  @initial(1)
+  @parser((value: number) => clamp(0, 1, value))
+  @signal()
+  declare public readonly opacity: SimpleSignal<number, this>;
+
+  @computed()
+  public absoluteOpacity(): number {
+    return (this.parent()?.absoluteOpacity() ?? 1) * this.opacity();
+  }
+
+  @filtersSignal()
+  declare public readonly filters: FiltersSignal<this>;
+
+  @initial('#0000')
+  @colorSignal()
+  declare public readonly shadowColor: ColorSignal<this>;
+
+  @initial(0)
+  @signal()
+  declare public readonly shadowBlur: SimpleSignal<number, this>;
+
+  @vector2Signal('shadowOffset')
+  declare public readonly shadowOffset: Vector2Signal<this>;
+
+  /**
+   * @experimental
+   */
+  @initial([])
+  @parser(parseShader)
+  @signal()
+  declare public readonly shaders: Signal<
+    PossibleShaderConfig,
+    ShaderConfig[],
+    this
+  >;
+
+  @computed()
+  protected hasFilters(): boolean {
+    return !!this.filters().find(filter => filter.isActive());
+  }
+
+  @computed()
+  protected hasShadow() {
+    return (
+      !!this.shadowColor() &&
+      (this.shadowBlur() > 0 ||
+        this.shadowOffset.x() !== 0 ||
+        this.shadowOffset.y() !== 0)
+    );
+  }
+
+  @computed()
+  protected filterString(): string {
+    let filters = '';
+    const matrix = this.compositeToWorld();
+    for (const filter of this.filters()) {
+      if (filter.isActive()) {
+        filters += ' ' + filter.serialize(matrix);
+      }
+    }
+
+    return filters;
+  }
+
+  /**
+   * @deprecated Use {@link children} instead.
+   */
+  @inspectable(false)
+  @cloneable(false)
+  @signal()
+  declare protected readonly spawner: SimpleSignal<ComponentChildren, this>;
+  protected getSpawner(): ComponentChildren {
+    return this.children();
+  }
+  protected setSpawner(value: SignalValue<ComponentChildren>) {
+    this.children(value);
+  }
+
+  @inspectable(false)
+  @cloneable(false)
+  @signal()
+  declare public readonly children: Signal<ComponentChildren, Node[], this>;
+  protected setChildren(value: SignalValue<ComponentChildren>) {
+    if (this.children.context.raw() === value) {
+      return;
+    }
+
+    this.children.context.setter(value);
+    if (!isReactive(value)) {
+      this.spawnChildren(false, value);
+    } else if (!this.hasSpawnedChildren) {
+      for (const oldChild of this.realChildren) {
+        oldChild.parent(null);
+      }
+    }
+  }
+  protected getChildren(): Node[] {
+    this.children.context.getter();
+    return this.spawnedChildren();
+  }
+
+  @computed()
+  protected spawnedChildren(): Node[] {
+    const children = this.children.context.getter();
+    if (isReactive(this.children.context.raw())) {
+      this.spawnChildren(true, children);
+    }
+    return this.realChildren;
+  }
+
+  @computed()
+  protected sortedChildren(): Node[] {
+    return [...this.children()].sort((a, b) =>
+      Math.sign(a.zIndex() - b.zIndex()),
+    );
+  }
+
+  protected view2D: View2D;
+  private stateStack: NodeState[] = [];
+  protected realChildren: Node[] = [];
+  protected hasSpawnedChildren = false;
+  private unregister: () => void;
+  public readonly parent = createSignal<Node | null>(null);
+  public readonly properties = getPropertiesOf(this);
+  public readonly key: string;
+  public readonly creationStack?: string;
+
+  public constructor({children, spawner, key, ...rest}: NodeProps) {
+    const scene = useScene2D();
+    [this.key, this.unregister] = scene.registerNode(this, key);
+    this.view2D = scene.getView();
+    this.creationStack = new Error().stack;
+    initializeSignals(this, rest);
+    if (spawner) {
+      useLogger().warn({
+        message: 'Node.spawner() has been deprecated.',
+        remarks: 'Use <code>Node.children()</code> instead.',
+        inspect: this.key,
+        stack: new Error().stack,
+      });
+    }
+    this.children(spawner ?? children);
+  }
+
+  /**
+   * Get the local-to-world matrix for this node.
+   *
+   * @remarks
+   * This matrix transforms vectors from local space of this node to world
+   * space.
+   *
+   * @example
+   * Calculate the absolute position of a point located 200 pixels to the right
+   * of the node:
+   * ```ts
+   * const local = new Vector2(0, 200);
+   * const world = local.transformAsPoint(node.localToWorld());
+   * ```
+   */
+  @computed()
+  public localToWorld(): DOMMatrix {
+    const parent = this.parent();
+    return parent
+      ? parent.localToWorld().multiply(this.localToParent())
+      : this.localToParent();
+  }
+
+  /**
+   * Get the world-to-local matrix for this node.
+   *
+   * @remarks
+   * This matrix transforms vectors from world space to local space of this
+   * node.
+   *
+   * @example
+   * Calculate the position relative to this node for a point located in the
+   * top-left corner of the screen:
+   * ```ts
+   * const world = new Vector2(0, 0);
+   * const local = world.transformAsPoint(node.worldToLocal());
+   * ```
+   */
+  @computed()
+  public worldToLocal() {
+    return this.localToWorld().inverse();
+  }
+
+  /**
+   * Get the world-to-parent matrix for this node.
+   *
+   * @remarks
+   * This matrix transforms vectors from world space to local space of this
+   * node's parent.
+   */
+  @computed()
+  public worldToParent(): DOMMatrix {
+    return this.parent()?.worldToLocal() ?? new DOMMatrix();
+  }
+
+  /**
+   * Get the parent-to-world matrix for this node.
+   *
+   * @remarks
+   * This matrix transforms vectors from local space of this node's parent to
+   * world space.
+   */
+  @computed()
+  public parentToWorld(): DOMMatrix {
+    return this.parent()?.localToWorld() ?? new DOMMatrix();
+  }
+
+  /**
+   * Get the local-to-parent matrix for this node.
+   *
+   * @remarks
+   * This matrix transforms vectors from local space of this node to local space
+   * of this node's parent.
+   */
+  @computed()
+  public localToParent(): DOMMatrix {
+    const matrix = new DOMMatrix();
+    matrix.translateSelf(this.x(), this.y());
+    matrix.rotateSelf(0, 0, this.rotation());
+    matrix.scaleSelf(this.scale.x(), this.scale.y());
+    matrix.skewXSelf(this.skew.x());
+    matrix.skewYSelf(this.skew.y());
+
+    return matrix;
+  }
+
+  /**
+   * A matrix mapping composite space to world space.
+   *
+   * @remarks
+   * Certain effects such as blur and shadows ignore the current transformation.
+   * This matrix can be used to transform their parameters so that the effect
+   * appears relative to the closest composite root.
+   */
+  @computed()
+  public compositeToWorld(): DOMMatrix {
+    return this.compositeRoot()?.localToWorld() ?? new DOMMatrix();
+  }
+
+  @computed()
+  protected compositeRoot(): Node | null {
+    if (this.composite()) {
+      return this;
+    }
+
+    return this.parent()?.compositeRoot() ?? null;
+  }
+
+  @computed()
+  public compositeToLocal() {
+    const root = this.compositeRoot();
+    if (root) {
+      const worldToLocal = this.worldToLocal();
+      worldToLocal.m44 = 1;
+      return root.localToWorld().multiply(worldToLocal);
+    }
+    return new DOMMatrix();
+  }
+
+  public view(): View2D {
+    return this.view2D;
+  }
+
+  /**
+   * Add the given node(s) as the children of this node.
+   *
+   * @remarks
+   * The nodes will be appended at the end of the children list.
+   *
+   * @example
+   * ```tsx
+   * const node = <Layout />;
+   * node.add(<Rect />);
+   * node.add(<Circle />);
+   * ```
+   * Result:
+   * ```mermaid
+   * graph TD;
+   *   layout([Layout])
+   *   circle([Circle])
+   *   rect([Rect])
+   *     layout-->rect;
+   *     layout-->circle;
+   * ```
+   *
+   * @param node - A node or an array of nodes to append.
+   */
+  public add(node: ComponentChildren): this {
+    return this.insert(node, Infinity);
+  }
+
+  /**
+   * Insert the given node(s) at the specified index in the children list.
+   *
+   * @example
+   * ```tsx
+   * const node = (
+   *   <Layout>
+   *     <Rect />
+   *     <Circle />
+   *   </Layout>
+   * );
+   *
+   * node.insert(<Txt />, 1);
+   * ```
+   *
+   * Result:
+   * ```mermaid
+   * graph TD;
+   *   layout([Layout])
+   *   circle([Circle])
+   *   text([Text])
+   *   rect([Rect])
+   *     layout-->rect;
+   *     layout-->text;
+   *     layout-->circle;
+   * ```
+   *
+   * @param node - A node or an array of nodes to insert.
+   * @param index - An index at which to insert the node(s).
+   */
+  public insert(node: ComponentChildren, index = 0): this {
+    const array: ComponentChild[] = Array.isArray(node) ? node : [node];
+    if (array.length === 0) {
+      return this;
+    }
+
+    const children = this.children();
+    const newChildren = children.slice(0, index);
+
+    for (const node of array) {
+      if (node instanceof Node) {
+        newChildren.push(node);
+        node.remove();
+        node.parent(this);
+      }
+    }
+
+    newChildren.push(...children.slice(index));
+    this.setParsedChildren(newChildren);
+
+    return this;
+  }
+
+  /**
+   * Remove this node from the tree.
+   */
+  public remove(): this {
+    const current = this.parent();
+    if (current === null) {
+      return this;
+    }
+
+    current.removeChild(this);
+    this.parent(null);
+    return this;
+  }
+
+  /**
+   * Rearrange this node in relation to its siblings.
+   *
+   * @remarks
+   * Children are rendered starting from the beginning of the children list.
+   * We can change the rendering order by rearranging said list.
+   *
+   * A positive `by` arguments move the node up (it will be rendered on top of
+   * the elements it has passed). Negative values move it down.
+   *
+   * @param by - Number of places by which the node should be moved.
+   */
+  public move(by = 1): this {
+    const parent = this.parent();
+    if (by === 0 || !parent) {
+      return this;
+    }
+
+    const children = parent.children();
+    const newChildren: Node[] = [];
+
+    if (by > 0) {
+      for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (child === this) {
+          const target = i + by;
+          for (; i < target && i + 1 < children.length; i++) {
+            newChildren[i] = children[i + 1];
+          }
+        }
+        newChildren[i] = child;
+      }
+    } else {
+      for (let i = children.length - 1; i >= 0; i--) {
+        const child = children[i];
+        if (child === this) {
+          const target = i + by;
+          for (; i > target && i > 0; i--) {
+            newChildren[i] = children[i - 1];
+          }
+        }
+        newChildren[i] = child;
+      }
+    }
+
+    parent.setParsedChildren(newChildren);
+
+    return this;
+  }
+
+  /**
+   * Move the node up in relation to its siblings.
+   *
+   * @remarks
+   * The node will exchange places with the sibling right above it (if any) and
+   * from then on will be rendered on top of it.
+   */
+  public moveUp(): this {
+    return this.move(1);
+  }
+
+  /**
+   * Move the node down in relation to its siblings.
+   *
+   * @remarks
+   * The node will exchange places with the sibling right below it (if any) and
+   * from then on will be rendered under it.
+   */
+  public moveDown(): this {
+    return this.move(-1);
+  }
+
+  /**
+   * Move the node to the top in relation to its siblings.
+   *
+   * @remarks
+   * The node will be placed at the end of the children list and from then on
+   * will be rendered on top of all of its siblings.
+   */
+  public moveToTop(): this {
+    return this.move(Infinity);
+  }
+
+  /**
+   * Move the node to the bottom in relation to its siblings.
+   *
+   * @remarks
+   * The node will be placed at the beginning of the children list and from then
+   * on will be rendered below all of its siblings.
+   */
+  public moveToBottom(): this {
+    return this.move(-Infinity);
+  }
+
+  /**
+   * Move the node to the provided position relative to its siblings.
+   *
+   * @remarks
+   * If the node is getting moved to a lower position, it will be placed below
+   * the sibling that's currently at the provided index (if any).
+   * If the node is getting moved to a higher position, it will be placed above
+   * the sibling that's currently at the provided index (if any).
+   *
+   * @param index - The index to move the node to.
+   */
+  public moveTo(index: number): this {
+    const parent = this.parent();
+    if (!parent) {
+      return this;
+    }
+
+    const currentIndex = parent.children().indexOf(this);
+    const by = index - currentIndex;
+
+    return this.move(by);
+  }
+
+  /**
+   * Move the node below the provided node in the parent's layout.
+   *
+   * @remarks
+   * The node will be moved below the provided node and from then on will be
+   * rendered below it. By default, if the node is already positioned lower than
+   * the sibling node, it will not get moved.
+   *
+   * @param node - The sibling node below which to move.
+   * @param directlyBelow - Whether the node should be positioned directly below
+   *                        the sibling. When true, will move the node even if
+   *                        it is already positioned below the sibling.
+   */
+  public moveBelow(node: Node, directlyBelow = false): this {
+    const parent = this.parent();
+    if (!parent) {
+      return this;
+    }
+
+    if (node.parent() !== parent) {
+      useLogger().error(
+        "Cannot position nodes relative to each other if they don't belong to the same parent.",
+      );
+      return this;
+    }
+
+    const children = parent.children();
+    const ownIndex = children.indexOf(this);
+    const otherIndex = children.indexOf(node);
+
+    if (!directlyBelow && ownIndex < otherIndex) {
+      // Nothing to do if the node is already positioned below the target node.
+      // We could move the node so it's directly below the sibling node, but
+      // that might suddenly move it on top of other nodes. This is likely
+      // not what the user wanted to happen when calling this method.
+      return this;
+    }
+
+    const by = otherIndex - ownIndex - 1;
+
+    return this.move(by);
+  }
+
+  /**
+   * Move the node above the provided node in the parent's layout.
+   *
+   * @remarks
+   * The node will be moved above the provided node and from then on will be
+   * rendered on top of it. By default, if the node is already positioned
+   * higher than the sibling node, it will not get moved.
+   *
+   * @param node - The sibling node below which to move.
+   * @param directlyAbove - Whether the node should be positioned directly above the
+   *                        sibling. When true, will move the node even if it is
+   *                        already positioned above the sibling.
+   */
+  public moveAbove(node: Node, directlyAbove = false): this {
+    const parent = this.parent();
+    if (!parent) {
+      return this;
+    }
+
+    if (node.parent() !== parent) {
+      useLogger().error(
+        "Cannot position nodes relative to each other if they don't belong to the same parent.",
+      );
+      return this;
+    }
+
+    const children = parent.children();
+    const ownIndex = children.indexOf(this);
+    const otherIndex = children.indexOf(node);
+
+    if (!directlyAbove && ownIndex > otherIndex) {
+      // Nothing to do if the node is already positioned above the target node.
+      // We could move the node so it's directly above the sibling node, but
+      // that might suddenly move it below other nodes. This is likely not what
+      // the user wanted to happen when calling this method.
+      return this;
+    }
+
+    const by = otherIndex - ownIndex + 1;
+
+    return this.move(by);
+  }
+
+  /**
+   * Change the parent of this node while keeping the absolute transform.
+   *
+   * @remarks
+   * After performing this operation, the node will stay in the same place
+   * visually, but its parent will be changed.
+   *
+   * @param newParent - The new parent of this node.
+   */
+  public reparent(newParent: Node): this {
+    const position = this.position.abs();
+    const rotation = this.rotation.abs();
+    const scale = this.scale.abs();
+    newParent.add(this);
+    this.position.abs(position);
+    this.rotation.abs(rotation);
+    this.scale.abs(scale);
+
+    return this;
+  }
+
+  /**
+   * Remove all children of this node.
+   */
+  public removeChildren(): this {
+    for (const oldChild of this.realChildren) {
+      oldChild.parent(null);
+    }
+    this.setParsedChildren([]);
+
+    return this;
+  }
+
+  /**
+   * Get the current children of this node.
+   *
+   * @remarks
+   * Unlike {@link children}, this method does not have any side effects.
+   * It does not register the `children` signal as a dependency, and it does not
+   * spawn any children. It can be used to safely retrieve the current state of
+   * the scene graph for debugging purposes.
+   */
+  public peekChildren(): readonly Node[] {
+    return this.realChildren;
+  }
+
+  /**
+   * Find all descendants of this node that match the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findAll<T extends Node>(predicate: (node: any) => node is T): T[];
+  /**
+   * Find all descendants of this node that match the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findAll<T extends Node = Node>(predicate: (node: any) => boolean): T[];
+  public findAll<T extends Node>(predicate: (node: any) => node is T): T[] {
+    const result: T[] = [];
+    const queue = this.reversedChildren();
+    while (queue.length > 0) {
+      const node = queue.pop()!;
+      if (predicate(node)) {
+        result.push(node);
+      }
+      const children = node.children();
+      for (let i = children.length - 1; i >= 0; i--) {
+        queue.push(children[i]);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Find the first descendant of this node that matches the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findFirst<T extends Node>(
+    predicate: (node: Node) => node is T,
+  ): T | null;
+  /**
+   * Find the first descendant of this node that matches the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findFirst<T extends Node = Node>(
+    predicate: (node: Node) => boolean,
+  ): T | null;
+  public findFirst<T extends Node>(
+    predicate: (node: Node) => node is T,
+  ): T | null {
+    const queue = this.reversedChildren();
+    while (queue.length > 0) {
+      const node = queue.pop()!;
+      if (predicate(node)) {
+        return node;
+      }
+      const children = node.children();
+      for (let i = children.length - 1; i >= 0; i--) {
+        queue.push(children[i]);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Find the last descendant of this node that matches the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findLast<T extends Node>(
+    predicate: (node: Node) => node is T,
+  ): T | null;
+  /**
+   * Find the last descendant of this node that matches the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findLast<T extends Node = Node>(
+    predicate: (node: Node) => boolean,
+  ): T | null;
+  public findLast<T extends Node>(
+    predicate: (node: Node) => node is T,
+  ): T | null {
+    const search: Node[] = [];
+    const queue = this.reversedChildren();
+
+    while (queue.length > 0) {
+      const node = queue.pop()!;
+      search.push(node);
+      const children = node.children();
+      for (let i = children.length - 1; i >= 0; i--) {
+        queue.push(children[i]);
+      }
+    }
+
+    while (search.length > 0) {
+      const node = search.pop()!;
+      if (predicate(node)) {
+        return node;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Find the closest ancestor of this node that matches the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findAncestor<T extends Node>(
+    predicate: (node: Node) => node is T,
+  ): T | null;
+  /**
+   * Find the closest ancestor of this node that matches the given predicate.
+   *
+   * @param predicate - A function that returns true if the node matches.
+   */
+  public findAncestor<T extends Node = Node>(
+    predicate: (node: Node) => boolean,
+  ): T | null;
+  public findAncestor<T extends Node>(
+    predicate: (node: Node) => node is T,
+  ): T | null {
+    let parent: Node | null = this.parent();
+    while (parent) {
+      if (predicate(parent)) {
+        return parent;
+      }
+      parent = parent.parent();
+    }
+
+    return null;
+  }
+
+  /**
+   * Get the nth children cast to the specified type.
+   *
+   * @param index - The index of the child to retrieve.
+   */
+  public childAs<T extends Node = Node>(index: number): T | null {
+    return (this.children()[index] as T) ?? null;
+  }
+
+  /**
+   * Get the children array cast to the specified type.
+   */
+  public childrenAs<T extends Node = Node>(): T[] {
+    return this.children() as T[];
+  }
+
+  /**
+   * Get the parent cast to the specified type.
+   */
+  public parentAs<T extends Node = Node>(): T | null {
+    return (this.parent() as T) ?? null;
+  }
+
+  /**
+   * Prepare this node to be disposed of.
+   *
+   * @remarks
+   * This method is called automatically when a scene is refreshed. It will
+   * be called even if the node is not currently attached to the tree.
+   *
+   * The goal of this method is to clean any external references to allow the
+   * node to be garbage collected.
+   */
+  public dispose() {
+    if (!this.unregister) {
+      return;
+    }
+
+    this.stateStack = [];
+    this.unregister();
+    this.unregister = null!;
+    for (const {signal} of this) {
+      signal?.context.dispose();
+    }
+    for (const child of this.realChildren) {
+      child.dispose();
+    }
+  }
+
+  /**
+   * Create a copy of this node.
+   *
+   * @param customProps - Properties to override.
+   */
+  public clone(customProps: NodeState = {}): this {
+    const props = {...customProps};
+    if (isReactive(this.children.context.raw())) {
+      props.children ??= this.children.context.raw();
+    } else if (this.children().length > 0) {
+      props.children ??= this.children().map(child => child.clone());
+    }
+
+    for (const {key, meta, signal} of this) {
+      if (!meta.cloneable || key in props) continue;
+      if (meta.compound) {
+        for (const [key, property] of meta.compoundEntries) {
+          if (property in props) continue;
+          const component = (<Record<string, SimpleSignal<any>>>(
+            (<unknown>signal)
+          ))[key];
+          if (!component.context.isInitial()) {
+            props[property] = component.context.raw();
+          }
+        }
+      } else if (!signal.context.isInitial()) {
+        props[key] = signal.context.raw();
+      }
+    }
+
+    return this.instantiate(props);
+  }
+
+  /**
+   * Create a copy of this node.
+   *
+   * @remarks
+   * Unlike {@link clone}, a snapshot clone calculates any reactive properties
+   * at the moment of cloning and passes the raw values to the copy.
+   *
+   * @param customProps - Properties to override.
+   */
+  public snapshotClone(customProps: NodeState = {}): this {
+    const props = {
+      ...this.getState(),
+      ...customProps,
+    };
+
+    if (this.children().length > 0) {
+      props.children ??= this.children().map(child => child.snapshotClone());
+    }
+
+    return this.instantiate(props);
+  }
+
+  /**
+   * Create a reactive copy of this node.
+   *
+   * @remarks
+   * A reactive copy has all its properties dynamically updated to match the
+   * source node.
+   *
+   * @param customProps - Properties to override.
+   */
+  public reactiveClone(customProps: NodeState = {}): this {
+    const props = {...customProps};
+    if (this.children().length > 0) {
+      props.children ??= this.children().map(child => child.reactiveClone());
+    }
+
+    for (const {key, meta, signal} of this) {
+      if (!meta.cloneable || key in props) continue;
+      props[key] = () => signal();
+    }
+
+    return this.instantiate(props);
+  }
+
+  /**
+   * Create an instance of this node's class.
+   *
+   * @param props - Properties to pass to the constructor.
+   */
+  public instantiate(props: NodeProps = {}): this {
+    return new (<NodeConstructor<NodeProps, this>>this.constructor)(props);
+  }
+
+  /**
+   * Set the children without parsing them.
+   *
+   * @remarks
+   * This method assumes that the caller took care of parsing the children and
+   * updating the hierarchy.
+   *
+   * @param value - The children to set.
+   */
+  protected setParsedChildren(value: Node[]) {
+    this.children.context.setter(value);
+    this.realChildren = value;
+  }
+
+  protected spawnChildren(reactive: boolean, children: ComponentChildren) {
+    const parsedChildren = this.parseChildren(children);
+
+    const keep = new Set<string>();
+    for (const newChild of parsedChildren) {
+      const current = newChild.parent.context.raw() as Node | null;
+      if (current && current !== this) {
+        current.removeChild(newChild);
+      }
+      keep.add(newChild.key);
+      newChild.parent(this);
+    }
+
+    for (const oldChild of this.realChildren) {
+      if (!keep.has(oldChild.key)) {
+        oldChild.parent(null);
+      }
+    }
+
+    this.hasSpawnedChildren = reactive;
+    this.realChildren = parsedChildren;
+  }
+
+  /**
+   * Parse any `ComponentChildren` into an array of nodes.
+   *
+   * @param children - The children to parse.
+   */
+  protected parseChildren(children: ComponentChildren): Node[] {
+    const result: Node[] = [];
+    const array = Array.isArray(children) ? children : [children];
+    for (const child of array) {
+      if (child instanceof Node) {
+        result.push(child);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Remove the given child.
+   */
+  protected removeChild(child: Node) {
+    this.setParsedChildren(this.children().filter(node => node !== child));
+  }
+
+  /**
+   * Whether this node should be cached or not.
+   */
+  protected requiresCache(): boolean {
+    return (
+      this.cache() ||
+      this.opacity() < 1 ||
+      this.compositeOperation() !== 'source-over' ||
+      this.hasFilters() ||
+      this.hasShadow() ||
+      this.shaders().length > 0
+    );
+  }
+
+  @computed()
+  protected cacheCanvas(): CanvasRenderingContext2D {
+    const canvas = document.createElement('canvas').getContext('2d');
+    if (!canvas) {
+      throw new Error('Could not create a cache canvas');
+    }
+
+    return canvas;
+  }
+
+  /**
+   * Get a cache canvas with the contents of this node rendered onto it.
+   */
+  @computed()
+  protected cachedCanvas() {
+    const context = this.cacheCanvas();
+    const cache = this.worldSpaceCacheBBox();
+    const matrix = this.localToWorld();
+
+    context.canvas.width = cache.width;
+    context.canvas.height = cache.height;
+
+    context.setTransform(
+      matrix.a,
+      matrix.b,
+      matrix.c,
+      matrix.d,
+      matrix.e - cache.x,
+      matrix.f - cache.y,
+    );
+    this.draw(context);
+
+    return context;
+  }
+
+  /**
+   * Get a bounding box for the contents rendered by this node.
+   *
+   * @remarks
+   * The returned bounding box should be in local space.
+   */
+  protected getCacheBBox(): BBox {
+    return new BBox();
+  }
+
+  /**
+   * Get a bounding box for the contents rendered by this node as well
+   * as its children.
+   */
+  @computed()
+  public cacheBBox(): BBox {
+    const cache = this.getCacheBBox();
+    const children = this.children();
+    const padding = this.cachePadding();
+    if (children.length === 0) {
+      return cache.addSpacing(padding);
+    }
+
+    const points: Vector2[] = cache.corners;
+    for (const child of children) {
+      const childCache = child.fullCacheBBox();
+      const childMatrix = child.localToParent();
+      points.push(
+        ...childCache.corners.map(r => r.transformAsPoint(childMatrix)),
+      );
+    }
+
+    const bbox = BBox.fromPoints(...points);
+    return bbox.addSpacing(padding);
+  }
+
+  /**
+   * Get a bounding box for the contents rendered by this node (including
+   * effects applied after caching).
+   *
+   * @remarks
+   * The returned bounding box should be in local space.
+   */
+  @computed()
+  protected fullCacheBBox(): BBox {
+    const matrix = this.compositeToLocal();
+    const shadowOffset = this.shadowOffset().transform(matrix);
+    const shadowBlur = transformScalar(this.shadowBlur(), matrix);
+
+    const result = this.cacheBBox().expand(
+      this.filters.blur() * 2 + shadowBlur,
+    );
+
+    if (shadowOffset.x < 0) {
+      result.x += shadowOffset.x;
+      result.width -= shadowOffset.x;
+    } else {
+      result.width += shadowOffset.x;
+    }
+
+    if (shadowOffset.y < 0) {
+      result.y += shadowOffset.y;
+      result.height -= shadowOffset.y;
+    } else {
+      result.height += shadowOffset.y;
+    }
+
+    return result;
+  }
+
+  /**
+   * Get a bounding box in world space for the contents rendered by this node as
+   * well as its children.
+   *
+   * @remarks
+   * This is the same the bounding box returned by {@link cacheBBox} only
+   * transformed to world space.
+   */
+  @computed()
+  protected worldSpaceCacheBBox(): BBox {
+    const viewBBox = BBox.fromSizeCentered(this.view().size()).expand(
+      this.view().cachePadding(),
+    );
+    const canvasBBox = BBox.fromPoints(
+      ...viewBBox.transformCorners(this.view().localToWorld()),
+    );
+    const cacheBBox = BBox.fromPoints(
+      ...this.cacheBBox().transformCorners(this.localToWorld()),
+    );
+
+    return canvasBBox.intersection(cacheBBox).pixelPerfect.expand(2);
+  }
+
+  @computed()
+  protected parentWorldSpaceCacheBBox(): BBox {
+    return (
+      this.findAncestor(node => node.requiresCache())?.worldSpaceCacheBBox() ??
+      new BBox(Vector2.zero, useScene2D().getRealSize())
+    );
+  }
+
+  /**
+   * Prepare the given context for drawing a cached node onto it.
+   *
+   * @remarks
+   * This method is called before the contents of the cache canvas are drawn
+   * on the screen. It can be used to apply effects to the entire node together
+   * with its children, instead of applying them individually.
+   * Effects such as transparency, shadows, and filters use this technique.
+   *
+   * Whether the node is cached is decided by the {@link requiresCache} method.
+   *
+   * @param context - The context using which the cache will be drawn.
+   */
+  protected setupDrawFromCache(context: CanvasRenderingContext2D) {
+    context.globalCompositeOperation = this.compositeOperation();
+    context.globalAlpha *= this.opacity();
+    if (this.hasFilters()) {
+      context.filter = this.filterString();
+    }
+    if (this.hasShadow()) {
+      const matrix = this.compositeToWorld();
+      const offset = this.shadowOffset().transform(matrix);
+      const blur = transformScalar(this.shadowBlur(), matrix);
+
+      context.shadowColor = this.shadowColor().serialize();
+      context.shadowBlur = blur;
+      context.shadowOffsetX = offset.x;
+      context.shadowOffsetY = offset.y;
+    }
+
+    const matrix = this.worldToLocal();
+    context.transform(
+      matrix.a,
+      matrix.b,
+      matrix.c,
+      matrix.d,
+      matrix.e,
+      matrix.f,
+    );
+  }
+
+  protected renderFromSource(
+    context: CanvasRenderingContext2D,
+    source: CanvasImageSource,
+    x: number,
+    y: number,
+  ) {
+    this.setupDrawFromCache(context);
+
+    const compositeOverride = this.compositeOverride();
+    context.drawImage(source, x, y);
+    if (compositeOverride > 0) {
+      context.save();
+      context.globalAlpha *= compositeOverride;
+      context.globalCompositeOperation = 'source-over';
+      context.drawImage(source, x, y);
+      context.restore();
+    }
+  }
+
+  private shaderCanvas(destination: TexImageSource, source: TexImageSource) {
+    const shaders = this.shaders();
+    if (shaders.length === 0) {
+      return null;
+    }
+
+    const scene = useScene2D();
+    const size = scene.getRealSize();
+    const parentCacheRect = this.parentWorldSpaceCacheBBox();
+    const cameraToWorld = new DOMMatrix()
+      .scaleSelf(
+        size.width / parentCacheRect.width,
+        size.height / -parentCacheRect.height,
+      )
+      .translateSelf(
+        parentCacheRect.x / -size.width,
+        parentCacheRect.y / size.height - 1,
+      );
+
+    const cacheRect = this.worldSpaceCacheBBox();
+    const cameraToCache = new DOMMatrix()
+      .scaleSelf(size.width / cacheRect.width, size.height / -cacheRect.height)
+      .translateSelf(cacheRect.x / -size.width, cacheRect.y / size.height - 1)
+      .invertSelf();
+
+    const gl = scene.shaders.getGL();
+    scene.shaders.copyTextures(destination, source);
+    scene.shaders.clear();
+
+    for (const shader of shaders) {
+      const program = scene.shaders.getProgram(shader.fragment);
+      if (!program) {
+        continue;
+      }
+
+      if (shader.uniforms) {
+        for (const [name, uniform] of Object.entries(shader.uniforms)) {
+          const location = gl.getUniformLocation(program, name);
+          if (location === null) {
+            continue;
+          }
+
+          const value = unwrap(uniform);
+          if (typeof value === 'number') {
+            gl.uniform1f(location, value);
+          } else if ('toUniform' in value) {
+            value.toUniform(gl, location);
+          } else if (value.length === 1) {
+            gl.uniform1f(location, value[0]);
+          } else if (value.length === 2) {
+            gl.uniform2f(location, value[0], value[1]);
+          } else if (value.length === 3) {
+            gl.uniform3f(location, value[0], value[1], value[2]);
+          } else if (value.length === 4) {
+            gl.uniform4f(location, value[0], value[1], value[2], value[3]);
+          }
+        }
+      }
+
+      gl.uniform1f(
+        gl.getUniformLocation(program, UNIFORM_TIME),
+        this.view2D.globalTime(),
+      );
+
+      gl.uniform1i(
+        gl.getUniformLocation(program, UNIFORM_TIME),
+        scene.playback.frame,
+      );
+
+      gl.uniformMatrix4fv(
+        gl.getUniformLocation(program, UNIFORM_SOURCE_MATRIX),
+        false,
+        cameraToCache.toFloat32Array(),
+      );
+
+      gl.uniformMatrix4fv(
+        gl.getUniformLocation(program, UNIFORM_DESTINATION_MATRIX),
+        false,
+        cameraToWorld.toFloat32Array(),
+      );
+
+      shader.setup?.(gl, program);
+      scene.shaders.render();
+      shader.teardown?.(gl, program);
+    }
+
+    return gl.canvas;
+  }
+
+  /**
+   * Render this node onto the given canvas.
+   *
+   * @param context - The context to draw with.
+   */
+  public render(context: CanvasRenderingContext2D) {
+    if (this.absoluteOpacity() <= 0) {
+      return;
+    }
+
+    context.save();
+    this.transformContext(context);
+
+    if (this.requiresCache()) {
+      const cacheRect = this.worldSpaceCacheBBox();
+      if (cacheRect.width !== 0 && cacheRect.height !== 0) {
+        const cache = this.cachedCanvas().canvas;
+        const source = this.shaderCanvas(context.canvas, cache);
+        if (source) {
+          this.renderFromSource(context, source, 0, 0);
+        } else {
+          this.renderFromSource(
+            context,
+            cache,
+            cacheRect.position.x,
+            cacheRect.position.y,
+          );
+        }
+      }
+    } else {
+      this.draw(context);
+    }
+
+    context.restore();
+  }
+
+  /**
+   * Draw this node onto the canvas.
+   *
+   * @remarks
+   * This method is used when drawing directly onto the screen as well as onto
+   * the cache canvas.
+   * It assumes that the context have already been transformed to local space.
+   *
+   * @param context - The context to draw with.
+   */
+  protected draw(context: CanvasRenderingContext2D) {
+    this.drawChildren(context);
+  }
+
+  protected drawChildren(context: CanvasRenderingContext2D) {
+    for (const child of this.sortedChildren()) {
+      child.render(context);
+    }
+  }
+
+  /**
+   * Draw an overlay for this node.
+   *
+   * @remarks
+   * The overlay for the currently inspected node is displayed on top of the
+   * canvas.
+   *
+   * The provided context is in screen space. The local-to-screen matrix can be
+   * used to transform all shapes that need to be displayed.
+   * This approach allows to keep the line widths and gizmo sizes consistent,
+   * no matter how zoomed-in the view is.
+   *
+   * @param context - The context to draw with.
+   * @param matrix - A local-to-screen matrix.
+   */
+  public drawOverlay(context: CanvasRenderingContext2D, matrix: DOMMatrix) {
+    const box = this.cacheBBox().transformCorners(matrix);
+    const cache = this.getCacheBBox().transformCorners(matrix);
+    context.strokeStyle = 'white';
+    context.lineWidth = 1;
+    context.beginPath();
+    drawLine(context, box);
+    context.closePath();
+    context.stroke();
+
+    context.strokeStyle = 'blue';
+    context.beginPath();
+    drawLine(context, cache);
+    context.closePath();
+    context.stroke();
+  }
+
+  protected transformContext(context: CanvasRenderingContext2D) {
+    const matrix = this.localToParent();
+    context.transform(
+      matrix.a,
+      matrix.b,
+      matrix.c,
+      matrix.d,
+      matrix.e,
+      matrix.f,
+    );
+  }
+
+  /**
+   * Try to find a node intersecting the given position.
+   *
+   * @param position - The searched position.
+   */
+  public hit(position: Vector2): Node | null {
+    let hit: Node | null = null;
+    const local = position.transformAsPoint(this.localToParent().inverse());
+    const children = this.children();
+    for (let i = children.length - 1; i >= 0; i--) {
+      hit = children[i].hit(local);
+      if (hit) {
+        break;
+      }
+    }
+
+    return hit;
+  }
+
+  /**
+   * Collect all asynchronous resources used by this node.
+   */
+  protected collectAsyncResources() {
+    for (const child of this.children()) {
+      child.collectAsyncResources();
+    }
+  }
+
+  /**
+   * Wait for any asynchronous resources that this node or its children have.
+   *
+   * @remarks
+   * Certain resources like images are always loaded asynchronously.
+   * Awaiting this method makes sure that all such resources are done loading
+   * before continuing the animation.
+   */
+  public async toPromise(): Promise<this> {
+    do {
+      await DependencyContext.consumePromises();
+      this.collectAsyncResources();
+    } while (DependencyContext.hasPromises());
+    return this;
+  }
+
+  /**
+   * Return a snapshot of the node's current signal values.
+   *
+   * @remarks
+   * This method will calculate the values of any reactive properties of the
+   * node at the time the method is called.
+   */
+  public getState(): NodeState {
+    const state: NodeState = {};
+    for (const {key, meta, signal} of this) {
+      if (!meta.cloneable || key in state) continue;
+      state[key] = signal();
+    }
+    return state;
+  }
+
+  /**
+   * Apply the given state to the node, setting all matching signal values to
+   * the provided values.
+   *
+   * @param state - The state to apply to the node.
+   */
+  public applyState(state: NodeState): void;
+  /**
+   * Smoothly transition between the current state of the node and the given
+   * state.
+   *
+   * @param state - The state to transition to.
+   * @param duration - The duration of the transition.
+   * @param timing - The timing function to use for the transition.
+   */
+  public applyState(
+    state: NodeState,
+    duration: number,
+    timing?: TimingFunction,
+  ): ThreadGenerator;
+  public applyState(
+    state: NodeState,
+    duration?: number,
+    timing: TimingFunction = easeInOutCubic,
+  ): ThreadGenerator | void {
+    if (duration === undefined) {
+      for (const key in state) {
+        const signal = this.signalByKey(key);
+        if (signal) {
+          signal(state[key]);
+        }
+      }
+    }
+
+    const tasks: ThreadGenerator[] = [];
+    for (const key in state) {
+      const signal = this.signalByKey(key);
+      if (state[key] !== signal.context.raw()) {
+        tasks.push(signal(state[key], duration!, timing));
+      }
+    }
+
+    return all(...tasks);
+  }
+
+  /**
+   * Push a snapshot of the node's current state onto the node's state stack.
+   *
+   * @remarks
+   * This method can be used together with the {@link restore} method to save a
+   * node's current state and later restore it. It is possible to store more
+   * than one state by calling `save` method multiple times.
+   */
+  public save(): void {
+    this.stateStack.push(this.getState());
+  }
+
+  /**
+   * Restore the node to its last saved state.
+   *
+   * @remarks
+   * This method can be used together with the {@link save} method to restore a
+   * node to a previously saved state. Restoring a node to a previous state
+   * removes that state from the state stack.
+   *
+   * @example
+   * ```tsx
+   * const node = <Circle width={100} height={100} fill={"lightseagreen"} />
+   *
+   * view.add(node);
+   *
+   * // Save the node's current state
+   * node.save();
+   *
+   * // Modify some of the node's properties
+   * yield* node.scale(2, 1);
+   * yield* node.fill('hotpink', 1);
+   *
+   * // Restore the node to its saved state
+   * node.restore();
+   * ```
+   */
+  public restore(): void;
+  /**
+   * Tween the node to its last saved state.
+   *
+   * @remarks
+   * This method can be used together with the {@link save} method to restore a
+   * node to a previously saved state. Restoring a node to a previous state
+   * removes that state from the state stack.
+   *
+   * @example
+   * ```tsx
+   * const node = <Circle width={100} height={100} fill={"lightseagreen"} />
+   *
+   * view.add(node);
+   *
+   * // Save the node's current state
+   * node.save();
+   *
+   * // Modify some of the node's properties
+   * yield* node.scale(2, 1);
+   * yield* node.fill('hotpink', 1);
+   *
+   * // Tween the node to its saved state over 1 second
+   * yield* node.restore(1);
+   * ```
+   *
+   * @param duration - The duration of the transition.
+   * @param timing - The timing function to use for the transition.
+   */
+  public restore(duration: number, timing?: TimingFunction): ThreadGenerator;
+  public restore(
+    duration?: number,
+    timing: TimingFunction = easeInOutCubic,
+  ): ThreadGenerator | void {
+    const state = this.stateStack.pop();
+
+    if (state !== undefined) {
+      return this.applyState(state, duration!, timing);
+    }
+  }
+
+  public *[Symbol.iterator]() {
+    for (const key in this.properties) {
+      const meta = this.properties[key];
+      const signal = this.signalByKey(key);
+      yield {meta, signal, key};
+    }
+  }
+
+  private signalByKey(key: string): SimpleSignal<any> {
+    return (<Record<string, SimpleSignal<any>>>(<unknown>this))[key];
+  }
+
+  private reversedChildren() {
+    const children = this.children();
+    const result: Node[] = [];
+    for (let i = children.length - 1; i >= 0; i--) {
+      result.push(children[i]);
+    }
+    return result;
+  }
+}
+
+Node.prototype.isClass = true;