#######
 Nodes
#######

.. currentmodule:: turbohtml

A parsed tree is made of nodes. :class:`Node` carries the navigation, query, mutation, and serialization surface every
node shares; the concrete types below add their own data. Text is a real :class:`Text` child node (the WHATWG DOM
shape), so there is no text/tail split.

.. autoclass:: Node
    :members:

.. autoclass:: Element
    :members:

.. autoclass:: Namespace
    :members:

An element can host a shadow tree with :meth:`Element.attach_shadow`, returning a :class:`ShadowRoot` -- a
document-fragment-like root held off the light tree. ``<slot>`` elements inside it pull in the host's children by name;
:meth:`Element.assigned_nodes`, :meth:`Element.assigned_elements`, :attr:`Node.assigned_slot`, and
:attr:`Node.flattened_children` read the assignment and the composed tree. See :doc:`/how-to/shadow-dom` for recipes and
:doc:`/explanation/shadow-dom` for the model.

.. autoclass:: ShadowRoot
    :members:

.. autoclass:: Text
    :members:

.. autoclass:: Comment
    :members:

.. autoclass:: CData
    :members:

.. autoclass:: ProcessingInstruction
    :members:

.. autoclass:: Doctype
    :members:

A :class:`Range` marks a run of the tree between two boundary points (a ``(container, offset)`` pair each) and copies,
moves, deletes, or wraps everything between them, following the DOM Living Standard. :class:`StaticRange` is its
immutable snapshot. See :doc:`/explanation/ranges` for the boundary-point model and :doc:`/how-to/ranges` for recipes.

.. autoclass:: Range
    :members:

.. autoclass:: StaticRange
    :members:

A :class:`MutationObserver` records changes made to a subtree through the mutation API and hands them back as
:class:`MutationRecord` values. Delivery is synchronous: pull the batch with
:meth:`~turbohtml.MutationObserver.take_records`, or push it to a callback with
:meth:`~turbohtml.MutationObserver.deliver`. See :doc:`/explanation/mutation` for the synchronous model and
:doc:`/how-to/observing-mutations` for recipes.

.. autoclass:: MutationObserver
    :members:

.. autoclass:: MutationRecord
    :members:

:meth:`Node.links` yields one :class:`Link` per link it finds.

.. autoclass:: Link
    :members:

:meth:`Node.article` returns an :class:`Article` record: the scored content body and the page metadata harvested beside
it.

.. autoclass:: Article
    :members:

When a tree is parsed with ``source_locations=True``, :attr:`Node.source_location` returns a :class:`SourceLocation`
record built from :class:`SourceSpan` values -- the start-tag, end-tag, and per-attribute spans parse5 exposes as
``sourceCodeLocationInfo``.

.. autoclass:: SourceLocation
    :members:

.. autoclass:: SourceSpan
    :members:

*******************
 Traversal objects
*******************

The DOM Living Standard traversal objects walk a subtree under a :class:`NodeFilter` bitmask and callback. A
:class:`TreeWalker` is a movable cursor; a :class:`NodeIterator` is a flat forward/backward view. See
:doc:`/how-to/traversing` for recipes and :doc:`/explanation/traversal` for the reject/skip semantics.

.. autoclass:: NodeFilter
    :members:
    :undoc-members:

.. autoclass:: TreeWalker
    :members:

.. autoclass:: NodeIterator
    :members: