Figler.Scene.Graph (figler v0.1.0-beta.1)

Copy Markdown View Source

Effective scene graph handle.

Figler.Scene.Index is the fast raw projection of Kiwi node records. Figler.Scene.Graph is the separate surface intended for resolved Figma semantics: populated instances, symbol overrides, component props, derived symbol data, and variable/style resolution.

The graph keeps a pure Elixir working set seeded from the native raw index. Query and navigation APIs accept the resulting graph, while Figma resolver stages remain inspectable in Elixir.

Malformed graph options and GUIDs raise Figler.Error with stable codes and structured context.

Summary

Types

t()

Opaque effective scene graph resource.

Functions

build(input, opts \\ [])

Builds an effective scene graph handle.

diff(graph, opts \\ [])

Diffs effective graph nodes against their projected source nodes.

diff_node(index, graph, guid)

Diffs one raw index node against its graph counterpart.

explain(graph, guid)

Explains how a node appears in the effective graph.

instance(graph, guid)

Returns instance-specific effective graph metadata for a node.

profile(input, opts \\ [])

Profiles graph construction and resolver stages.

seed_nodes(input, opts \\ [])

Returns structured seed nodes for the graph resolver.

source_node(graph, guid)

Returns the projected source node for a graph node.

stats(graph)

Returns graph build/runtime stats.

tree(graph, opts \\ [])

Returns a resolved tree from the effective graph.

unresolved(graph, opts \\ [])

Returns unresolved graph items.

Types

t()

@opaque t()

Opaque effective scene graph resource.

Functions

build(input, opts \\ [])

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

Builds an effective scene graph handle.

Accepts the same binary inputs as Figler.Scene.index/1, an existing %Figler.Scene.Index{}, a native index resource, or another graph.

Options are validated, stored on the graph, and define the resolver pipeline. Unknown stages and conflicting selection options raise Figler.Error rather than silently selecting a different pipeline.

Options:

  • :stages - explicit resolver stages. Defaults to the standard pipeline.
  • :only - alias for :stages, useful for focused debugging.
  • :until - include default stages through this stage.
  • :skip - remove stages from the selected pipeline.
  • :focus - one or more source GUIDs to resolve. When set, resolver stages only run from matching source instances and their source descendants.
  • :root - alias for :focus, useful for resolving one subtree.
  • :resolve_variables - false, :known, or :preserve. Defaults to :known.
  • :resolve_styles - false, :refs, or :known. Defaults to false.
  • :fields - optional projected fields hint for future graph materialization.

diff(graph, opts \\ [])

@spec diff(
  t(),
  keyword()
) :: [map()]

Diffs effective graph nodes against their projected source nodes.

Returns only nodes whose projected source differs from the effective node. Pass root: to diff a subtree.

diff_node(index, graph, guid)

@spec diff_node(Figler.Scene.Index.t() | reference(), t(), String.t()) :: map() | nil

Diffs one raw index node against its graph counterpart.

explain(graph, guid)

@spec explain(t(), String.t()) :: map() | nil

Explains how a node appears in the effective graph.

The explanation includes the resolved node, projected source node when known, provenance, applied resolver operations, unresolved diagnostics recorded on the node, and instance metadata for instance nodes.

graph = Figler.Scene.graph(fig_binary, root: "3740:112537")
Figler.Scene.Graph.explain(graph, "3740:112537")

instance(graph, guid)

@spec instance(t(), String.t()) :: map() | nil

Returns instance-specific effective graph metadata for a node.

Returns nil for non-instance nodes.

profile(input, opts \\ [])

@spec profile(
  binary() | Figler.Scene.Index.t() | reference() | t(),
  keyword()
) :: map()

Profiles graph construction and resolver stages.

Returns the final graph, total build time, initial seed/materialization time, and per-stage timings. Options are the same as build/2.

seed_nodes(input, opts \\ [])

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

Returns structured seed nodes for the graph resolver.

source_node(graph, guid)

@spec source_node(t(), String.t()) :: Figler.Scene.Node.t() | nil

Returns the projected source node for a graph node.

stats(graph)

@spec stats(t()) :: map()

Returns graph build/runtime stats.

tree(graph, opts \\ [])

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

Returns a resolved tree from the effective graph.

Options:

  • :root - graph GUID string/tuple to use as root. Defaults to all roots.

  • :depth - maximum child depth. Defaults to 3.

    graph = Figler.Scene.graph(fig_binary, root: "3740:112537") Figler.Scene.Graph.tree(graph, root: "3740:112537", depth: 3)

unresolved(graph, opts \\ [])

@spec unresolved(
  t(),
  keyword()
) :: [term()]

Returns unresolved graph items.