def add_child(self, child: AnyNode) -> None:
    """Add a child node to this node."""
    if child in self._children:
        return
    self._children.append(child)
    child.parent = cast("AnyNode", self)
    self.child_added.emit(child)

def iter_parents(self) -> Iterator[Node]:
    """Return list of parents starting from this node.

    The chain ends at the first node with no parents.
    """
    yield self

    x = self
    while True:
        try:
            parent = x.parent
        except Exception:
            break
        if parent is None:
            break
        yield parent
        x = parent

def look_at(self, target: Position3D, /, *, up: Vector3D | None = None) -> None:
    """Adjusts the camera to look at a target point in the world.

    Parameters
    ----------
    target: Position3D
        The position in 3D space that the camera should look at.
    up: Vector3D, optional
        The up direction for the camera. If provided, this vector must be
        perpendicular to the forward vector that results from looking at target.
    """
    position = self.transform.map((0, 0, 0))[:3]
    self.forward = tuple(target - position)
    if up is not None:
        if np.linalg.norm(up) == 0:
            raise ValueError("Up vector must be non-zero.")
        if np.abs(np.dot(self.forward, up)) > 1e-6:
            raise ValueError("Up vector must be perpendicular to forward vector.")
        self.up = up

def model_post_init(self, __context: Any) -> None:
    """Called after the model is initialized."""
    objects.register(self)
    logger.debug(
        "Created model %-12r id: %s", type(self).__name__, self._model_id.hex[:8]
    )

def passes_through(self, ray: Ray) -> float | None:
    """Returns the depth t at which the provided ray intersects this node.

    The ray, in this case, is defined by R(t) = ray_origin + ray_direction * t,
    where t>=0

    Parameters
    ----------
    ray : Ray
        The ray passing through the scene

    Returns
    -------
    t: float | None
        The depth t at which the ray intersects the node, or None if it never
        intersects.
    """
    # Nodes that want to support ray intersection should override this method.
    return None

def path_to_node(self, other: Node) -> tuple[list[Node], list[Node]]:
    """Return two lists describing the path from this node to another.

    Parameters
    ----------
    other : instance of Node
        The other node.

    Returns
    -------
    p1 : list
        First path (see below).
    p2 : list
        Second path (see below).

    Notes
    -----
    The first list starts with this node and ends with the common parent
    between the endpoint nodes. The second list contains the remainder of
    the path from the common parent to the specified ending node.

    For example, consider the following scenegraph::

        A --- B --- C --- D
               \
                --- E --- F

    Calling `D.node_path(F)` will return::

        ([D, C, B], [E, F])

    """
    my_parents = list(self.iter_parents())
    their_parents = list(other.iter_parents())
    common_parent = next((p for p in my_parents if p in their_parents), None)
    if common_parent is None:
        slf = f"{self.__class__.__name__} {id(self)}"
        nd = f"{other.__class__.__name__} {id(other)}"
        raise RuntimeError(f"No common parent between nodes {slf} and {nd}.")

    up = my_parents[: my_parents.index(common_parent) + 1]
    down = their_parents[: their_parents.index(common_parent)][::-1]
    return (up, down)

def remove_child(self, child: AnyNode) -> None:
    """Remove a child node from this node. Does not raise if child is missing."""
    if child in self._children:
        self._children.remove(child)
        child.parent = None
        self.child_removed.emit(child)

def transform_to_node(self, other: Node) -> Transform:
    """Return Transform that maps from coordinate frame of `self` to `other`.

    Note that there must be a _single_ path in the scenegraph that connects
    the two entities; otherwise an exception will be raised.

    Parameters
    ----------
    other : instance of Node
        The other node.

    Returns
    -------
    transform : instance of ChainTransform
        The transform.
    """
    a, b = self.path_to_node(other)
    tforms = [n.transform for n in a[:-1]] + [n.transform.inv() for n in b]
    return Transform.chain(*tforms[::-1])

def tree_repr(self) -> str:
    """Return an ASCII/Unicode tree representation of self and its descendants."""
    from scenex.util import tree_repr

    return tree_repr(self, node_repr=object.__repr__)

@abstractmethod
def handle_event(self, event: Event, view: View) -> bool:
    """
    Handle a user interaction event to control the camera.

    This method is called automatically on all events on the camera's view that were
    not handled by previous handlers during scenex event processing.

    Parameters
    ----------
    event : Event
        The input event to handle (MouseMoveEvent, MousePressEvent, WheelEvent,
        KeyPressEvent, etc.)
    view : View
        The view containing the camera to manipulate.

    Returns
    -------
    bool
        True if the event was fully handled and should not propagate to other
        handlers, False if not handled or other handlers should process it.

    Notes
    -----
    A ``View`` is passed rather than a ``Camera`` directly because controllers
    need ``view.to_ray()`` to unproject screen-space event positions into world
    space, which requires both the camera matrices and the viewport dimensions.
    """
    ...

def close(self) -> None:
    """Close the canvas and release resources."""
    for adaptor in self._get_adaptors():
        cast("CanvasAdaptor", adaptor)._snx_close()

def content_rect_for(self, view: View) -> tuple[int, int, int, int]:
    """The pixel rect (x, y, width, height) of the content area for a view.

    Applies the view's padding, border_width, and margin insets to the
    outer rect returned by ``rect_for``.
    """
    x, y, w, h = self.rect_for(view)
    layout = view.layout
    offset = int(layout.padding + layout.border_width + layout.margin)
    return (x + offset, y + offset, w - 2 * offset, h - 2 * offset)

def filter_event(self, event: Event) -> bool:
    """Pass *event* through the canvas-level filter, if any.

    Returns True iff the event was handled and should not propagate.
    """
    if self._filter:
        handled = self._filter(event)
        if not isinstance(handled, bool):
            logger.warning(
                f"Canvas event filter {self._filter} did not return a boolean. "
                "Returning False."
            )
            handled = False
        return handled
    return False

def handle(self, event: Event) -> bool:
    """Handle the passed event."""
    # 0. Handle events pertaining to the canvas model
    if isinstance(event, ResizeEvent):
        self.size = (event.width, event.height)

    # 1. Canvas-level filter sees all events first.
    if self.filter_event(event):
        return True

    # 2. Pass the event to the view under the mouse.
    # NOTE: Currently, only mouse events have a position. Maybe other events should
    # have them too?
    if isinstance(event, MouseEvent):
        # Find the view under the mouse, if any.
        current_view = self._containing_view(event.pos)

        # If that view is different from the last view...
        # TODO: Add a test for this once multiple views are better supported
        if self._last_mouse_view != current_view:
            # ...send a MouseLeaveEvent to the last view...
            if self._last_mouse_view is not None:
                self._last_mouse_view.filter_event(MouseLeaveEvent())
            # ...and a MouseEnterEvent to the new view (if the incoming event isn't
            # one already).
            if current_view is not None and not isinstance(event, MouseEnterEvent):
                current_view.filter_event(
                    MouseEnterEvent(pos=event.pos, buttons=event.buttons)
                )
        self._last_mouse_view = current_view

        if current_view is not None:
            # 2a. Give the view under the mouse the chance to handle the event.
            if current_view.filter_event(event):
                return True
            # 2b. If the view didn't handle the event, give any camera controller
            #    on the view the chance to handle it.
            if current_view.camera.interactive:
                if ctrl := current_view.camera.controller:
                    return ctrl.handle_event(event, current_view)

    # 3. MouseLeave events won't be on any view (because they have no position),
    #    so we need to handle them at the canvas level to clear the last_mouse_view.
    elif isinstance(event, MouseLeaveEvent):
        if self._last_mouse_view is not None:
            handled = self._last_mouse_view.filter_event(event)
            self._last_mouse_view = None
            return handled

    return False

def model_post_init(self, __context: Any) -> None:
    """Post-initialization hook for the model."""
    # Update all current views
    for view in self.views:
        view.canvas = self

    self.views.item_inserted.connect(self._on_view_inserted)
    self.views.item_removed.connect(self._on_view_removed)
    self.views.item_changed.connect(self._on_view_changed)

def rect_for(self, view: View) -> tuple[int, int, int, int]:
    """The pixel rect (x, y, width, height) for a view, computed from its layout."""
    x = view.layout.x_start.resolve(self.width)
    w = view.layout.x_end.resolve(self.width) - x
    y = view.layout.y_start.resolve(self.height)
    h = view.layout.y_end.resolve(self.height) - y
    return (x, y, w, h)

def render(self) -> np.ndarray:
    """Render the canvas to an image array.

    Returns
    -------
    np.ndarray
        The rendered canvas as an RGBA image array. The array is expected
        to follow standard image conventions, with shape
        ``(height, width, 4)``.
    """
    if adaptors := self._get_adaptors(create=True):
        return cast("CanvasAdaptor", adaptors[0])._snx_render()
    raise RuntimeError("No adaptor found for Canvas.")

def set_event_filter(
    self, event_filter: Callable[[Event], bool] | None
) -> Callable[[Event], bool] | None:
    """Register a callable to filter all canvas events before view dispatch.

    Parameters
    ----------
    event_filter : Callable[[Event], bool] | None
        A callable that takes an Event and returns True if the event was handled
        and should not be propagated further, False otherwise. Pass None to remove
        any existing filter.

    Returns
    -------
    Callable[[Event], bool] | None
        The previous event filter, or None if there was no filter.
    """
    old, self._filter = self._filter, event_filter
    return old

def add_child(self, child: AnyNode) -> None:
    """Add a child node to this node."""
    if child in self._children:
        return
    self._children.append(child)
    child.parent = cast("AnyNode", self)
    self.child_added.emit(child)

def iter_parents(self) -> Iterator[Node]:
    """Return list of parents starting from this node.

    The chain ends at the first node with no parents.
    """
    yield self

    x = self
    while True:
        try:
            parent = x.parent
        except Exception:
            break
        if parent is None:
            break
        yield parent
        x = parent

def model_post_init(self, __context: Any) -> None:
    """Called after the model is initialized."""
    objects.register(self)
    logger.debug(
        "Created model %-12r id: %s", type(self).__name__, self._model_id.hex[:8]
    )

def path_to_node(self, other: Node) -> tuple[list[Node], list[Node]]:
    """Return two lists describing the path from this node to another.

    Parameters
    ----------
    other : instance of Node
        The other node.

    Returns
    -------
    p1 : list
        First path (see below).
    p2 : list
        Second path (see below).

    Notes
    -----
    The first list starts with this node and ends with the common parent
    between the endpoint nodes. The second list contains the remainder of
    the path from the common parent to the specified ending node.

    For example, consider the following scenegraph::

        A --- B --- C --- D
               \
                --- E --- F

    Calling `D.node_path(F)` will return::

        ([D, C, B], [E, F])

    """
    my_parents = list(self.iter_parents())
    their_parents = list(other.iter_parents())
    common_parent = next((p for p in my_parents if p in their_parents), None)
    if common_parent is None:
        slf = f"{self.__class__.__name__} {id(self)}"
        nd = f"{other.__class__.__name__} {id(other)}"
        raise RuntimeError(f"No common parent between nodes {slf} and {nd}.")

    up = my_parents[: my_parents.index(common_parent) + 1]
    down = their_parents[: their_parents.index(common_parent)][::-1]
    return (up, down)

def remove_child(self, child: AnyNode) -> None:
    """Remove a child node from this node. Does not raise if child is missing."""
    if child in self._children:
        self._children.remove(child)
        child.parent = None
        self.child_removed.emit(child)

def transform_to_node(self, other: Node) -> Transform:
    """Return Transform that maps from coordinate frame of `self` to `other`.

    Note that there must be a _single_ path in the scenegraph that connects
    the two entities; otherwise an exception will be raised.

    Parameters
    ----------
    other : instance of Node
        The other node.

    Returns
    -------
    transform : instance of ChainTransform
        The transform.
    """
    a, b = self.path_to_node(other)
    tforms = [n.transform for n in a[:-1]] + [n.transform.inv() for n in b]
    return Transform.chain(*tforms[::-1])

def tree_repr(self) -> str:
    """Return an ASCII/Unicode tree representation of self and its descendants."""
    from scenex.util import tree_repr

    return tree_repr(self, node_repr=object.__repr__)

def model_post_init(self, __context: Any) -> None:
    """Called after the model is initialized."""
    objects.register(self)
    logger.debug(
        "Created model %-12r id: %s", type(self).__name__, self._model_id.hex[:8]
    )

def handle_resize(self, view: View) -> None:
    """Handle view resize by adjusting projection to maintain aspect ratio."""
    # If the current projection differs from the last adjustment, or if there is no
    # reference to begin with, this is a new resize sequence.
    if view.camera.projection != self._last_adjustment or self._reference is None:
        self._reference = view.camera.projection

    if (view_rect := view.rect) is None or self._reference is None:
        # Nothing to do.
        return
    _, _, view_width, view_height = view_rect
    if view_height == 0:
        return

    # Extract projection scales that define the content aspect ratio
    ref_mat = self._reference.root
    ref_x_scale = ref_mat[0, 0]
    ref_y_scale = ref_mat[1, 1]
    if ref_y_scale == 0:
        return

    # Compute aspect ratios
    # NOTE: projection scales are inversely proportional to the displayed region,
    # so content_aspect = y_scale / x_scale
    view_aspect = view_width / view_height
    content_aspect = abs(ref_y_scale / ref_x_scale)

    # Expand the narrower dimension to match the view aspect
    if content_aspect < view_aspect:
        # View is wider: expand horizontal frustum (reduce x scale)
        adjusted_proj = self._reference.scaled(
            (content_aspect / view_aspect, 1.0, 1.0)
        )
    else:
        # View is taller: expand vertical frustum (reduce y scale)
        adjusted_proj = self._reference.scaled(
            (1.0, view_aspect / content_aspect, 1.0)
        )

    # Store the adjustment before applying it
    view.camera.projection = self._last_adjustment = adjusted_proj

def model_post_init(self, __context: Any) -> None:
    """Called after the model is initialized."""
    objects.register(self)
    logger.debug(
        "Created model %-12r id: %s", type(self).__name__, self._model_id.hex[:8]
    )

def add_child(self, child: AnyNode) -> None:
    """Add a child node to this node."""
    if child in self._children:
        return
    self._children.append(child)
    child.parent = cast("AnyNode", self)
    self.child_added.emit(child)

def iter_parents(self) -> Iterator[Node]:
    """Return list of parents starting from this node.

    The chain ends at the first node with no parents.
    """
    yield self

    x = self
    while True:
        try:
            parent = x.parent
        except Exception:
            break
        if parent is None:
            break
        yield parent
        x = parent

def model_post_init(self, __context: Any) -> None:
    """Called after the model is initialized."""
    objects.register(self)
    logger.debug(
        "Created model %-12r id: %s", type(self).__name__, self._model_id.hex[:8]
    )

def passes_through(self, ray: Ray) -> float | None:
    """
    Check if the ray passes through this line.

    Parameters
    ----------
    ray : Ray
        The ray to test for intersection.

    Returns
    -------
    float | None
        The distance to the closest intersection, or None if no intersection.
    """
    verts = np.asarray(self.vertices)
    # Convert vertices to canvas space
    canvas_vertices = self._node_to_canvas(ray.source)
    # Convert ray to canvas space
    canvas_ray = Line._world_to_canvas(ray, np.array([ray.origin]))[0]

    starts = canvas_vertices[:-1]
    ends = canvas_vertices[1:]

    # Compute the distance from the ray ON THE CANVAS to the closest point the line
    # associated with each line segment.
    #
    # Equation loaned from https://en.wikipedia.org/wiki/Distance_from_a_point_to_a_line#Line_defined_by_two_points
    num = np.abs(
        (ends[:, 1] - starts[:, 1]) * canvas_ray[0]
        - (ends[:, 0] - starts[:, 0]) * canvas_ray[1]
        + ends[:, 0] * starts[:, 1]
        - ends[:, 1] * starts[:, 0]
    )
    den = np.sqrt(
        (ends[:, 1] - starts[:, 1]) ** 2 + (ends[:, 0] - starts[:, 0]) ** 2
    )
    den[den == 0] = float("inf")  # Avoid division by zero
    distance = num / den

    # Determine the corresponding point in world space corresponding to that closest
    # point. Note that this point is only on the line segment if 0 <= t <= 1.
    # (We check this at the end.)
    a = np.subtract(canvas_ray, starts)
    b = np.subtract(ends, starts)
    # Vectorized version of dot product
    t = np.sum(a * b, axis=1) / np.sum(b * b, axis=1)
    intersect_world = verts[1:] + t[:, np.newaxis] * (verts[:-1] - verts[1:])

    # Calculate the distance along the ray to the intersection point
    # The ray is defined as: ray.origin + d * ray.direction
    # We need to find d such that ray.origin + d * ray.direction = intersect_world
    # This gives us: d * ray.direction = intersect_world - ray.origin
    # Solving for d: d = dot(intersect_world - ray.origin, ray.direction) /
    #                     dot(ray.direction, ray.direction)
    ray_to_intersect = np.subtract(intersect_world, ray.origin)
    ray_dir_squared = np.dot(ray.direction, ray.direction)

    if ray_dir_squared == 0:
        return None  # Degenerate ray

    d = np.dot(ray_to_intersect, ray.direction) / ray_dir_squared

    # Our ray intersects the line if:
    # 1. The distance from the ray to the line is less than the line width
    # 2. The intersection point is within the line segment (0 <= t <= 1)
    # 3. The intersection point is in front of the ray origin (d >= 0)
    condition = (distance <= self.width) & (t >= 0) & (t <= 1) & (d >= 0)
    valid_intersections = d[condition]
    if len(valid_intersections):
        return float(np.min(valid_intersections))
    else:
        return None

def path_to_node(self, other: Node) -> tuple[list[Node], list[Node]]:
    """Return two lists describing the path from this node to another.

    Parameters
    ----------
    other : instance of Node
        The other node.

    Returns
    -------
    p1 : list
        First path (see below).
    p2 : list
        Second path (see below).

    Notes
    -----
    The first list starts with this node and ends with the common parent
    between the endpoint nodes. The second list contains the remainder of
    the path from the common parent to the specified ending node.

    For example, consider the following scenegraph::

        A --- B --- C --- D
               \
                --- E --- F

    Calling `D.node_path(F)` will return::

        ([D, C, B], [E, F])

    """
    my_parents = list(self.iter_parents())
    their_parents = list(other.iter_parents())
    common_parent = next((p for p in my_parents if p in their_parents), None)
    if common_parent is None:
        slf = f"{self.__class__.__name__} {id(self)}"
        nd = f"{other.__class__.__name__} {id(other)}"
        raise RuntimeError(f"No common parent between nodes {slf} and {nd}.")

    up = my_parents[: my_parents.index(common_parent) + 1]
    down = their_parents[: their_parents.index(common_parent)][::-1]
    return (up, down)

def remove_child(self, child: AnyNode) -> None:
    """Remove a child node from this node. Does not raise if child is missing."""
    if child in self._children:
        self._children.remove(child)
        child.parent = None
        self.child_removed.emit(child)

def transform_to_node(self, other: Node) -> Transform:
    """Return Transform that maps from coordinate frame of `self` to `other`.

    Note that there must be a _single_ path in the scenegraph that connects
    the two entities; otherwise an exception will be raised.

    Parameters
    ----------
    other : instance of Node
        The other node.

    Returns
    -------
    transform : instance of ChainTransform
        The transform.
    """
    a, b = self.path_to_node(other)
    tforms = [n.transform for n in a[:-1]] + [n.transform.inv() for n in b]
    return Transform.chain(*tforms[::-1])

def tree_repr(self) -> str:
    """Return an ASCII/Unicode tree representation of self and its descendants."""
    from scenex.util import tree_repr

    return tree_repr(self, node_repr=object.__repr__)