@spec ancestors(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  String.t()
) ::
  [scene_node()]

Returns ancestors for a node GUID, ordered from root to parent.

@spec attribute([scene_node()], atom() | String.t()) :: [term()]

Returns projected field values from nodes, similar to Floki.attribute/2.

@spec by_type(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()],
  atom() | String.t(),
  keyword()
) :: [scene_node()]

Returns nodes of a given projected node type without constructing XPath.

@spec children(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  String.t()
) ::
  [scene_node()]

Returns direct children for a parent GUID in scene order.

@spec components(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()]
) :: [scene_node()]

Returns nodes with component keys.

@spec descendants(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  String.t()
) ::
  [scene_node()]

Returns all descendants for a node GUID in scene order.

@spec find(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  keyword()
) :: [scene_node()]

Finds nodes by common projected fields without interpolating XPath.

@spec graph(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  keyword()
) :: Figler.Scene.Graph.t()

Builds an effective scene graph handle.

Scene.index/1 is the fast raw projection. Scene.graph/2 is the separate surface for resolved Figma semantics such as populated instances, symbol overrides, component props, derived symbol data, and variable/style resolution.

@spec index(binary()) :: Figler.Scene.Index.t()

Builds a reusable native scene index resource.

Use this when running multiple XPath queries over the same scene.

@spec name_contains(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()],
  String.t(),
  keyword()
) :: [scene_node()]

Returns nodes whose projected name contains needle without constructing XPath.

@spec named(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()],
  String.t()
) :: [scene_node()]

Returns nodes with an exact projected name without constructing XPath.

@spec node(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  String.t()
) ::
  scene_node() | nil

Looks up a projected scene node by GUID.

@spec pages(binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference()) ::
  [scene_node()]

Returns canvas/page nodes.

@spec parent(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  String.t()
) ::
  scene_node() | nil

Returns the parent node for a node GUID.

@spec payload!(binary()) :: binary()

Extracts the raw Figma Kiwi Message binary from any supported scene input.

@spec query(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  String.t(),
  keyword()
) :: [scene_node()]

Queries a binary scene, reusable scene index, or graph source projection with XPath. For an effective graph, XPath runs against its reusable raw index; helper APIs such as by_type/3, named/2, and find/2 inspect effective graph nodes, including resolved clones.

Options:

• :fields - list of projected fields to keep in returned nodes. :guid and :node_type are always kept. Defaults to all fields.

Scene nodes are exposed as elements named by their Figma node type, for example //canvas or //text.

@spec roots(binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference()) ::
  [scene_node()]

Returns root nodes in scene order.

@spec siblings(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  String.t()
) ::
  [scene_node()]

Returns sibling nodes for a node GUID in scene order.

@spec summary(binary()) :: Figler.Scene.Summary.t()

Returns a projected scene summary.

@spec text(
  [scene_node()],
  keyword()
) :: String.t()

Returns projected text from nodes, similar to Floki.text/2.

@spec text_contains(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()],
  String.t(),
  keyword()
) :: [scene_node()]

Returns text nodes whose projected text contains needle without constructing XPath.

@spec text_nodes(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()]
) :: [scene_node()]

Returns text nodes.

@spec tree(
  binary() | Figler.Scene.Index.t() | Figler.Scene.Graph.t() | reference(),
  keyword()
) :: [Figler.Scene.Node.t()] | Figler.Scene.Node.t() | nil

Builds a lightweight nested scene tree.

@spec with_fills(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()]
) :: [scene_node()]

Returns nodes with one or more fill paints.

@spec with_strokes(
  binary()
  | Figler.Scene.Index.t()
  | Figler.Scene.Graph.t()
  | reference()
  | [scene_node()]
) :: [scene_node()]

Returns nodes with one or more stroke paints.