Skip to content

Visualize Your Ideas With Code

51.6 KB
Raw Blame
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,
  modify,
  threadable,
  transformAngle,
  transformScalar,
  unwrap,
  useLogger,
} from '@motion-canvas/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 {Filter} from '../partials';
import {
  PossibleShaderConfig,
  ShaderConfig,
  parseShader,
} from '../partials/ShaderConfig';
import {useScene2D} from '../scenes/useScene2D';
import {drawLine} from '../utils';
import type {View2D} from './View2D';
import type {ComponentChild, ComponentChildren, NodeConstructor} from './types';

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
   */
  public declare readonly [NODE_NAME]: string;
  public declare 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);
   * ```
   */
  @vector2Signal()
  public declare readonly position: Vector2Signal<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.
   */
  @wrapper(Vector2)
  @cloneable(false)
  @signal()
  public declare readonly absolutePosition: SimpleVector2Signal<this>;

  protected getAbsolutePosition(): Vector2 {
    return new Vector2(this.parentToWorld().transformPoint(this.position()));
  }

  protected setAbsolutePosition(value: SignalValue<PossibleVector2>) {
    this.position(
      modify(value, unwrapped =>
        new Vector2(unwrapped).transformAsPoint(this.worldToParent()),
      ),
    );
  }

  /**
   * Represents the rotation (in degrees) of this node relative to its parent.
   */
  @initial(0)
  @signal()
  public declare readonly rotation: SimpleSignal<number, 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.
   */
  @cloneable(false)
  @signal()
  public declare readonly absoluteRotation: SimpleSignal<number, this>;

  protected getAbsoluteRotation() {
    const matrix = this.localToWorld();
    return Vector2.degrees(matrix.m11, matrix.m12);
  }

  protected setAbsoluteRotation(value: SignalValue<number>) {
    this.rotation(
      modify(value, unwrapped =>
        transformAngle(unwrapped, this.worldToParent()),
      ),
    );
  }

  /**
   * 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)
  @vector2Signal('scale')
  public declare readonly scale: Vector2Signal<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')
  public declare 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.
   */
  @wrapper(Vector2)
  @cloneable(false)
  @signal()
  public declare readonly absoluteScale: SimpleVector2Signal<this>;

  protected getAbsoluteScale(): Vector2 {
    const matrix = this.localToWorld();
    return new Vector2(
      Vector2.magnitude(matrix.m11, matrix.m12),
      Vector2.magnitude(matrix.m21, matrix.m22),
    );
  }

  protected setAbsoluteScale(value: SignalValue<PossibleVector2>) {
    this.scale(
      modify(value, unwrapped => this.getRelativeScale(new Vector2(unwrapped))),
    );
  }

  private getRelativeScale(scale: Vector2): Vector2 {
    const parentScale = this.parent()?.absoluteScale() ?? Vector2.one;
    return scale.div(parentScale);
  }

  @initial(0)
  @signal()
  public declare readonly zIndex: SimpleSignal<number, this>;

  @initial(false)
  @signal()
  public declare 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')
  public declare readonly cachePadding: SpacingSignal<this>;

  @initial(false)
  @signal()
  public declare readonly composite: SimpleSignal<boolean, this>;

  @initial('source-over')
  @signal()
  public declare 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()
  public declare readonly opacity: SimpleSignal<number, this>;

  @computed()
  public absoluteOpacity(): number {
    return (this.parent()?.absoluteOpacity() ?? 1) * this.opacity();
  }

  @filtersSignal()
  public declare readonly filters: FiltersSignal<this>;

  @initial('#0000')
  @colorSignal()
  public declare readonly shadowColor: ColorSignal<this>;

  @initial(0)
  @signal()
  public declare readonly shadowBlur: SimpleSignal<number, this>;

  @vector2Signal('shadowOffset')
  public declare readonly shadowOffset: Vector2Signal<this>;

  /**
   * @experimental
   */
  @initial([])
  @parser(parseShader)
  @signal()
  public declare 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()
  protected declare readonly spawner: SimpleSignal<ComponentChildren, this>;
  protected getSpawner(): ComponentChildren {
    return this.children();
  }
  protected setSpawner(value: SignalValue<ComponentChildren>) {
    this.children(value);
  }

  @inspectable(false)
  @cloneable(false)
  @signal()
  public declare 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.absolutePosition();
    const rotation = this.absoluteRotation();
    const scale = this.absoluteScale();
    newParent.add(this);
    this.absolutePosition(position);
    this.absoluteRotation(rotation);
    this.absoluteScale(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;