graph module

graph

• from-spec()
• build()
• parse()
• node()
• source()
• sink()
• edge()
• group()
• pin()
• start()
• pos()
• map()
• style()
• eval-fields()
• info()
• dot()
• nodes()
• edges()
• node-data()
• edge-data()
• update-node-data()
• update-edge-data()
• cut()
• boundaries()
• join()
• join-edges()
• cycles()
• forests()

from-spec

Construct a graph from a versioned Linnest graph-spec CBOR document.

This is the native renderer boundary. Unlike parse, it does not parse DOT.

build

Build one graph object from a stream of node and edge items.

Use node, source, sink, and edge to create graph items. Positional items may be passed as comma-separated arguments or yielded from a Typst code block.

#let g = build({
  node(<a>, label: [a])
  node(<b>, label: [b])
  node(<c>, label: [c])
  edge(source(<a>), sink(<b>))
  edge(source(<b>), sink(<c>))
  edge(source(<a>), sink(<c>))
})

#let g = build(name: "My Graph", {
})
#info(g).name

#let g = build(data: (a:(b:(1, ))), {
})
#info(g).data

#let g = build(statements: (a:1), {
})
#info(g).global-statements

#let g = build(default-edge-statements: (a:1), {
   node(<a>)
   edge(source(<a>))
   edge(sink(<a>))
})
#edges(g).map(e=>e.statements)

#let g = build(default-node-data: (a:1), {
   node(<a>)
   node(<b>,a:2)
   node(<c>,b:(a:1))
})
#nodes(g).map(n=>n.data)

#let g = build(default-edge-data: (a:1,b:[$m_mu$]), {
   node(<a>,id:0)
   edge(source(<a>),id:1)
   edge(sink(<a>),<e>,id:0,b:[#set text(font:"Reforma")
   This is a test: ])
})
#edges(g).map(e=>e.data.b).join()

#let g = build(default-source-data: (a:1), {
   node(<a>)
   edge(source(<a>))
   edge(sink(<a>))
})
#edges(g).map(e=>if e.source != none {e.source.data} else {none})

#let g = build(default-sink-data: (a:1), {
   node(<a>)
   edge(source(<a>))
   edge(sink(<a>))
})
#edges(g).map(e=>if e.sink != none {e.sink.data} else {none})

parse

Parse one or more DOT graphs into graph objects.

Default data are applied before eval-* fields are evaluated, so default data strings can refer to parsed record fields such as #str(name). Parsed fields take precedence over default data fields, so DOT label="..." overrides default-node-data: (label: ...).

Linnest uses dot-parser for DOT syntax and then gives special meaning to a small set of attributes. Every other attribute is preserved as a flat string statement. Preserved statements are visible through info, nodes, edges, map, and eval-fields, but they do not become native Typst data unless a matching eval-* argument is passed.

#let src = ```dot
digraph { a [label="A"]; }
```
#let n = nodes(parse(src.text).first()).first()
#n.statements.label
#n.data

Graph-level handling:

• The DOT graph name becomes graph.info(g).name. A graph-level name attribute can name an anonymous graph; a named graph/digraph header takes precedence.

#let src = ```dot
digraph header_wins { graph [name="ignored"]; a }
```
#info(parse(src.text).first()).name

• Top-level key=value statements and graph [key=value] attributes become graph.info(g).global-statements, except for the consumed name. They do not configure layout, even when a key looks like a layout option; pass layout options directly to layout.

#let src = ```dot
digraph { steps=1; graph [subtitle="nested"]; a }
```
#let statements = info(parse(src.text).first()).global-statements
#statements.steps
#statements.subtitle

• node [key=value] and edge [key=value] become default-node-statements and default-edge-statements. They are merged into each parsed node or edge before local attributes, so local attributes override defaults.

#let src = ```dot
digraph { node [color=gray]; edge [particle=g]; a [color=red]; a -> b }
```
#let g = parse(src.text).first()
#nodes(g).first().statements.color
#edges(g).first().statements.particle

Node handling:

• The DOT node id becomes the node name returned by nodes. If the DOT node id is numeric, it is consumed as the node index instead and the public name is none.

#let src = ```dot
digraph { alpha; 1; }
```
#nodes(parse(src.text).first()).map(n => n.name)

• id=<n> is also consumed as an explicit node index. Explicit node indexes must be unique and in bounds after parsing.

#let src = ```dot
digraph { a [id=1]; b [id=0]; }
```
#nodes(parse(src.text).first()).map(n => n.name)

• style=invis marks the DOT node as a dangling external endpoint. It is not returned by nodes. Its remaining attributes are copied onto the external edge that touches it, except shape and label; style and id are consumed.

#let src = ```dot
digraph { ext [style=invis, column=left, label=skip]; ext -> a [id=0]; }
```
#let g = parse(src.text).first()
#nodes(g).map(n => n.name)
#edges(g).first().statements.column
#edges(g).first().statements.at("label", default: none)

• Node style is consumed for every node; only style=invis has special behavior. Use another attribute name for drawing style metadata that must survive parsing.

#let src = ```dot
digraph { a [style=filled, "draw-style"=filled]; }
```
#nodes(parse(src.text).first()).first().statements

• pos is parsed as node placement. Simple numeric values are exposed as node.pos; extended placement values are used by layout. pin is an explicit layout constraint and is not exposed as a public statement. The pos-x-set and pos-y-set record fields say which axes were explicitly supplied, including for partial placements whose resolved pos contains both coordinates. dot preserves them as canonical Linnest DOT extension attributes.

#let src = ```dot
digraph { a [id=0, pos="0,0!"]; b [id=1, pos="ref(node:0)+2,0!"]; }
```
#let parsed-nodes = nodes(parse(src.text).first())
#parsed-nodes.map(n => n.pos)
#parsed-nodes.map(n => n.statements.at("pin", default: none))

• shift is parsed as a drawing shift and also remains available as a statement. eval is retained for legacy round-tripping. Other node attributes are preserved as node statements.

#let src = ```dot
digraph { a [shift="0.1,0", eval=legacy, label=A]; }
```
#let n = nodes(parse(src.text).first()).first()
#n.shift
#n.statements

Edge handling:

• id=<n> is consumed as the edge index. It is not preserved as a statement; drawing callbacks expose the resulting stable edge index as eid. Explicit edge indexes must be unique and in bounds. Without explicit ids, edge order is parser-internal, not DOT input order.

#let src = ```dot
digraph { a -> b [id=1, label=later]; b -> c [id=0, label=first]; }
```
#let parsed-edges = edges(parse(src.text).first())
#parsed-edges.map(e => e.edge)
#parsed-edges.map(e => e.statements.label)
#parsed-edges.map(e => e.statements.at("id", default: none))

• dir=forward, dir=back, and dir=none become edge orientations "default", "reversed", and "undirected". If omitted, directed DOT edges are "default" and undirected DOT edges are "undirected".

#let src = ```dot
digraph { a -> b [id=0]; b -> c [id=1, dir=back]; c -> d [id=2, dir=none]; }
```
#edges(parse(src.text).first()).map(e => e.orientation)

• source="..." and sink="..." are consumed as endpoint statement values and removed from edge statements. On an external edge, use the attribute matching the real endpoint side in the DOT edge: ext -> a uses sink=..., while a -> ext uses source=....

#let src = ```dot
digraph { ext [style=invis]; ext -> a [id=0, sink=in]; a -> ext [id=1, source=out]; }
```
#let endpoint-statement(endpoint) = if endpoint == none { none } else { endpoint.at("statement", default: none) }
#let parsed-edges = edges(parse(src.text).first())
#parsed-edges.map(e => endpoint-statement(e.source))
#parsed-edges.map(e => endpoint-statement(e.sink))
#parsed-edges.map(e => e.statements.at("source", default: none))

• pos is parsed as the edge control-point placement. pin is an explicit edge layout constraint. shift, label-pos, label-angle, and bend are parsed into edge geometry fields; except for pin, they also remain available as statements. The pos-x-set and pos-y-set record fields identify explicitly supplied axes, including partial placements; dot preserves them as canonical Linnest DOT extension attributes. Other edge attributes are preserved as edge statements.

#let src = ```dot
digraph { a -> b [id=0, pos="0,1!", pin="x:@edge", shift="0.1,0", "label-pos"="0,1.2", "label-angle"="0.3rad", bend="0.4rad", particle=g]; }
```
#let e = edges(parse(src.text).first()).first()
#e.pos
#e.shift
#e.label-pos
#e.label-angle
#e.bend
#e.statements.particle
#e.statements.at("pin", default: none)

• Attributes copied from an invisible endpoint node are merged into the external edge statements unless their keys are shape or label.

#let src = ```dot
digraph { ext [style=invis, column=left, shape=none, label=skip]; ext -> a [id=0]; }
```
#edges(parse(src.text).first()).first().statements

Port and half-edge handling:

• DOT ports of the form node:port and node:port:compass are preserved on source/sink endpoint records. Numeric ports also assign explicit half-edge ids. Non-numeric ports are exposed only as port-label.

#let src = ```dot
digraph { a:left:e -> b:0:w [id=0]; }
```
#let e = edges(parse(src.text).first()).first()
#e.source.port-label
#e.sink.hedge

• Compass values are exposed as compass; valid DOT compass names include n, ne, e, se, s, sw, w, nw, c, and _.

#let src = ```dot
digraph { a:n -> b:sw [id=0]; }
```
#let e = edges(parse(src.text).first()).first()
#e.source.compass
#e.sink.compass

• Explicit half-edge ids from numeric ports must be unique and in bounds. They are retained for half-edge ordering and for join with key: "id"; query and eval records expose the resulting half-edge index as hedge.

#let src = ```dot
digraph { a:1 -> b:0 [id=0]; }
```
#let e = edges(parse(src.text).first()).first()
#e.source.hedge
#e.sink.hedge

Placement fields:

• pos="x,y" gives a starting coordinate; pos="x,y!" pins both axes.

#let src = ```dot
digraph { a [id=0, pos="0,0"]; b [id=1, pos="2,0!"]; a -> b; }
```
#let parsed = parse(src.text).first()
#nodes(parsed).map(n => n.pos)
#nodes(layout(parsed, steps: 10, seed: 1)).map(n => n.pos)

• pos="ref(node:<id>)+dx,dy!" and pos="ref(edge:<id>)+dx,dy!" reference explicit DOT node or edge ids, not names and not implicit parse order.

#let src = ```dot
digraph { a [id=0, pos="1,1!"]; b [id=1, pos="ref(node:0)+2,0!"]; a -> b [id=0, pos="ref(node:1)+0,1!"]; }
```
#let g = parse(src.text).first()
#nodes(g).at(1).pos
#edges(g).first().pos

• Axis form accepts x:<coord> and y:<coord> entries. ! applies to the individual axis, for example pos="x:2!,y:0".

#let src = ```dot
digraph { a [id=0, pos="x:2!,y:0"]; }
```
#nodes(parse(src.text).first()).first().pos

• Group coordinates use @name, @+name, or @-name in axis form and must be pinned with !, for example pos="x:@-left!,y:@row!".

#let src = ```dot
digraph { ext [style=invis]; ext -> a [id=0, pos="x:@-left!,y:@row!"]; }
```
#edges(layout(parse(src.text).first(), layout-algo: "tree")).first().pos

• pin accepts numeric point constraints, x:<coord>, y:<coord>, and grouped constraints such as x:@left, x:@+right, or @row.

#let src = ```dot
digraph { a -> b [id=0, pin="x:@+right"]; }
```
#edges(layout(parse(src.text).first(), layout-algo: "tree")).first().statements.at("pin", default: none)

#let a = ```dot
digraph {
a -> b -> c -> d -> a
a -> a
b -> d
c [particle="q"]
}
```
#let g = parse(a.text,default-node-data:(particle:"g")).at(0)
#nodes(g).map(n=>n.data.particle)

#let src = ```dot
digraph { a [label="#str(name)"]; }
```
#nodes(parse(src.text, eval-node-fields: "label").first()).first().data.label

#let src = ```dot
digraph { a -> b [id=0, label="#orientation"]; }
```
#edges(parse(src.text, eval-edge-fields: "label").first()).first().data.label

#let src = ```dot
digraph { a:left:e -> b [id=0, source="#port-label"]; }
```
#edges(parse(src.text, eval-source-fields: "statement").first()).first().source.data.statement

#let src = ```dot
digraph { a -> b:0:w [id=0, sink="#str(hedge)"]; }
```
#edges(parse(src.text, eval-sink-fields: "statement").first()).first().sink.data.statement

#let src = ```dot
digraph {
  title = "Strong graph";
}
```
#info(parse(src.text, eval-graph-fields: "title").first()).data.title

node

Create a graph node item for build.

A Typst label is the node name used by source, sink, and pos. The optional numeric id fixes the resulting graph node index. Extra named arguments are captured as node data fields, so node(<a>, label: [A], color: red) stores (label: [A], color: red). The default draw style uses data.label as the visible node label when present.

source

Create a source half-edge endpoint.

node may be a node name like <a> or a numeric node index. name gives the half-edge a Typst name; id is a numeric half-edge order/index override. Extra named arguments are captured as source data fields.

sink

Create a sink half-edge endpoint.

node may be a node name like <a> or a numeric node index. name gives the half-edge a Typst name; id is a numeric half-edge order/index override. Extra named arguments are captured as sink data fields.

edge

Create a graph edge item for build.

Positional arguments may contain one source, one sink, and optionally one Typst label used as the edge name. The numeric id chooses the edge order. Extra named arguments are captured as edge data fields, so edge(source(<a>), sink(<b>), weight: 3) stores (weight: 3). style is first-class drawing metadata: auto asks draw for its configured/default style, a dictionary or callback patches that style, and none hides the painted edge. The default draw style uses data.label as the visible edge label when present.

group

Create a grouped placement coordinate.

side: "+" keeps the solved coordinate non-negative and side: "-" keeps it non-positive. start supplies an initial value without fixing the coordinate; multiple starts for one group are averaged. Groups are layout constraints and therefore require pin placement, which is the pos default. Node and edge coordinates with the same group name and side share one axis coordinate throughout layout.

#group("right", side: "+", start: 4)

pin

Mark one coordinate as a layout constraint.

start

Mark one coordinate as an initial layout value only.

pos

Create a first-class graph placement.

The default mode: "pin" turns numeric coordinates into layout constraints and also makes the XY coordinates immediately drawable without a layout pass. Use start(value) for an individual coordinate that should only seed the layout, or pin(value) to pin an individual numeric coordinate when mode: "start" is used. Grouped coordinates are always layout constraints for their axis.

z is auxiliary depth for force-based layout only, in the same numeric layout units as x and y (not Typst lengths). Use pos(z: pin(2)) for a hard raw-depth pin or pos(z: start(2)) for a movable initial depth. A bare pos(z: 2) follows mode, defaulting to "pin". The global depth scale and flattening schedule may reduce effective depth to zero without changing a hard raw-depth pin. This is not a rendered third coordinate: node/edge output pos and drawing remain 2D. Statements retain the configured raw pin/seed, not the solved free depth, as "pos-z" (finite numeric text) and "pos-z-mode" ("pin" or "start"). Other layout backends do not use z.

Both build and map accept z placements on nodes and edge control points. A z-only placement leaves XY placement and constraints alone, including automatic edge midpoint seeds. Omitting z preserves existing depth metadata. Z groups, relative depth references, dz, and non-finite values are not supported; ref, dx, and dy continue to affect XY only.

#pos(x: group("right", side: "+"), y: start(10), z: pin(2))

map

Map graph records with native-data and structural patches. Position patches merge supplied axes: omitted coordinates retain their existing values, pin/start modes and coordinate groups.

node and edge accept either a callback for every record or a name-keyed dictionary. Dictionary keys are exact string names: a matches <a>, and "D1.0" matches the <D1.0> fragment produced by cut. Each entry is a constant patch dictionary, a callback, or none. Unlisted records and unnamed records are skipped by name-keyed dictionaries. Every supplied name must exist, even when its entry is none. Unknown names and invalid mapper, entry, or callback return types are errors. There are no numeric-ID keys, array selectors, wildcard/default selectors, or recursive merges. graph, source, and sink still accept only a callback or none.

The callbacks receive the same full decoded records in either form, plus a fields dictionary merging native dictionary data, statements, and direct record fields, with later sources taking precedence. A callback returns none to leave the record unchanged, (data: value) to set new native data, or structural fields such as pos, shift, spring-length, and statements to patch data seen by later layout calls. spring-length is validated as a positive finite multiplier and stored in the edge statements used by the layout engine. Structural patches are applied separately from native Typst data, so content and stored functions in the existing data value are preserved. Unchanged fields in a returned full record are not reapplied; this preserves partial XY placements when patching z or data. Source and sink callbacks may likewise patch statement, port-label, and compass before subgraph and layout operations run.

Constant patches and callback results use identical semantics. Node structural keys are pos, shift, and statements; edges also accept label-pos, label-angle, bend, and spring-length. With no data key, other keys shallow-merge into existing native dictionary data (or replace non-dictionary data with that patch). An explicit data key instead replaces native data, ignoring other non-structural keys; data: none leaves native data unchanged. Native Typst content and stored functions are preserved, not serialized or invoked. A mapper or entry of none, an empty name map, an empty patch, or a callback returning none leaves the corresponding records unchanged.

#let g = build({ node(<a>) })
#let g = map(g, node: node => (data: (label: [A])))
#nodes(g).first().data.label

#let g = build({
  node(<a>); node(<b>)
  edge(<D1>, source(<a>), sink(<b>), weight: 2)
})
#let g = map(g,
  node: (a: (label: [A]), b: none),
  edge: (D1: e => (weight: e.fields.weight + 1)),
)
#edge-data(g, <D1>).weight

style

Attach layout-relevant drawing style to a graph.

Node style is measured immediately and stored as layout-width / layout-height statements for later layout calls. Edge labels are measured as label-width / label-height statements for label placement. draw uses the stored node, edge, endpoint, and label styles by default.

eval-fields

Evaluate selected fields into native data entries.

Each selected field is read from the record’s merged fields dictionary, evaluated in a scope containing those fields, and written to data.<field>.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>), sink(<b>), statements: (mom: "p"))
}, default-edge-statements: (display-label: "$#mom$"))
#let g = eval-fields(g, eval-edge-fields: ("display-label",))
#edges(g).first().data.at("display-label")

info

Return graph metadata.

The result has name, global-statements, default-edge-statements, and default-node-statements.

#let g = build({ node(<a>) }, name: "demo")
#info(g).name

dot

Serialize a graph object to DOT.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>), sink(<b>))
}, name: "demo")
#dot(g).contains("digraph demo")

nodes

Return node records, optionally filtered by a subgraph object.

Node name values are Typst labels when present.

#let g = build({
  node(<a>)
  node(<b>)
})
#nodes(g).map(node => str(node.name)).join(", ")

edges

Return edge records, optionally filtered by a subgraph object.

Edge name values are Typst labels when present.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>, compass: "e"), sink(<b>))
})
#edges(g).len()

node-data

Return one named node’s native data.

name is a Typst label such as <a> or the corresponding string name.

#let g = build({ node(<a>, label: [A]) })
#node-data(g, <a>).label

edge-data

Return one named edge’s native data.

name is a Typst label such as <e> or the corresponding string name.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>), <e>, sink(<b>), label: [$p$])
})
#edge-data(g, <e>).label

update-node-data

Update one named node’s native data.

update may be a replacement data value or a function (data, node) => new-data.

#let g = build({ node(<a>) })
#let g = update-node-data(g, <a>, (label: [A]))
#nodes(g).first().data.label

update-edge-data

Update one named edge’s native data.

update may be a replacement data value or a function (data, edge) => new-data.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>), <e>, sink(<b>))
})
#let g = update-edge-data(g, <e>, (label: [$p$]))
#edges(g).first().data.label

cut

Open paired edges along a weighted directed half-edge cut.

left and right are disjoint subgraphs containing opposite halves of each cut edge. Their names identify boundary sides, not underlying source/sink flow or superficial drawing orientation. A half-edge annotation (winding: n) requests n same-direction seam passages; absent winding defaults to one. If both sides specify a winding they must agree. Net counts of cancelling recrossings are not a supported description of an opening.

The input is unchanged. Every cut edge yields source and sink stubs plus n - 1 middle segments on auxiliary, unpainted boundary nodes. Fragment names are <original.0> through <original.n> in underlying source-to-sink order. Unnamed edges use __linnest_cut_edge_ID as the prefix; name collisions are errors. Cut geometry is reset for re-layout, while physical data and orientation are retained. Arbitrary Typst data, including content and callbacks, is remapped without serialization. Generated middle endpoint hedges inherit the data of the opposite original hedge, corresponding to the joined boundary side.

Output node/edge/half-edge records have origin relative to the input graph. Edge origins contain (edge, name, segment, winding); uncut segments are none. Generated nodes have no original node. Boundary nodes and dangling cut edges also have boundary: (edge, node, hedge, side, crossing, data,
cut-data, origin), where data is the side’s hedge annotation and cut-data its subgraph-wide data. crossing counts from zero along underlying flow. Boundary hedge and origin describe the input to the cut that created that boundary, even after subsequent cuts; edge and node always locate its current anchor. This differs from each record’s immediate-input origin. The optional callback patches only endpoints created by this operation, exactly like map; earlier boundary placements and annotations are retained.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>), <e>, sink(<b>), label: [$k$])
})
#let left = subgraph.select(g, sink: (<e>,))
#let left = subgraph.with-data(g, left, hedge: (winding: 2))
#let right = subgraph.select(g, source: (<e>,))
#let opened = cut(g, left: left, right: right)
#edges(opened).len()

boundaries

Inspect all generated cut endpoints with their current solved positions.

Returns the boundary records described by cut plus pos. For a dangling endpoint, node is none and pos is its edge position; for a middle segment endpoint it is the auxiliary node position. This makes boundary annotations independent of their internal node/edge representation.

join

Join two graphs by matching dangling half-edge metadata on key.

Supported key values are "statement", "compass", "port-label", and "id". The join is partial: unmatched dangling half-edges remain. Matching identities must be unique within each flow, and node/edge names must not collide across the inputs. Native Typst data is preserved; when both sides provide a dictionary, right-only fields are retained and left-side fields take precedence.

#let left = build({
  node(<a>)
  edge(sink(<a>, statement: "j"))
})
#let right = build({
  node(<b>)
  edge(source(<b>, statement: "j"))
})
#edges(join(left, right, key: "statement")).len()

join-edges

Join two graphs by matching dangling edge records on an edge statement key.

This is distinct from graph.join: it matches edge-level statements rather than half-edge metadata. The same partial-join, collision, and data-merge rules apply.

cycles

Return subgraph objects for the graph’s cycle basis.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>), sink(<b>))
})
#cycles(g).len()

forests

Return subgraph objects for the graph’s spanning forests.

#let g = build({
  node(<a>)
  node(<b>)
  edge(source(<a>), sink(<b>))
})
#forests(g).len()