graph

type ArrowDirection string

type BackLink struct {
	// Name is the display name for the parent.
	Name string
	// URL is the relative path to the parent diagram.
	URL string
}

type BreadcrumbItem struct {
	// Name is the display name.
	Name string
	// URL is the relative path (empty for current level).
	URL string
}

type Cluster struct {
	// ID is the cluster identifier.
	ID string
	// Label is the cluster label (parent unit info).
	Label *Label
	// Nodes are the nodes inside this cluster.
	Nodes []*Node
	// Clusters are nested clusters inside this cluster (for all-expanded mode).
	Clusters []*Cluster
	// Style contains cluster styling attributes.
	Style *NodeStyle
	// Type is the unit type for HTML label dispatch.
	Type model.UnitType
	// IsExternal indicates if this cluster represents an external unit.
	IsExternal bool
	// ExploreURL is the relative drill-down path for a collapsed container
	// cluster (CTX-03) — the cluster-side analog of Node.ExploreURL. Empty for
	// expanded or leaf clusters.
	ExploreURL string
	// ReferenceURL is the external docs URL (📖) of the unit this cluster
	// renders — the cluster-side analog of Node.ReferenceURL. Empty if none.
	// When both it and ExploreURL apply, the EXTERNAL reference wins the
	// cluster's single URL slot (same ARCHITECTURE-v1.10 §6 (6) Option A
	// precedence nodes use).
	ReferenceURL string
}

type Edge struct {
	// Source is the source node ID.
	Source string
	// Target is the target node ID.
	Target string
	// Name is the unique, model-derived, flag-independent cgraph edge
	// identifier assigned by the builder (quick 260831-01u BUG-3):
	// "{source}_to_{target}_{n}" with a per-(source, target) sequence number
	// from the PRE-dedup link walk, sanitized to [A-Za-z0-9_]. The converter
	// uses it verbatim as the cgraph edge name so every builder Edge maps to
	// its own drawn edge regardless of which flags suppressed which
	// attributes (empty for hand-built graphs — the renderer falls back to
	// its legacy name construction).
	Name string
	// Label contains edge label information.
	Label *EdgeLabel
	// Style is the line style (solid, dashed, dotted).
	Style string
	// ArrowHead is the arrow direction.
	ArrowHead ArrowDirection
	// Color is the edge line and label color (from source unit's border color or explicit override).
	Color string
	// MinLen is the minimum length (minlen attribute) for the edge.
	MinLen int
	// NoConstraint excludes the edge from rank computation (constraint=false),
	// so its endpoints may end up on the same rank. Set from link.Rank == "equal".
	NoConstraint bool
	// RankReverse flips the edge's layout ranking (link.Rank == "reverse"):
	// Source/Target stay logical; the renderer swaps the endpoints at emission
	// and inverts the dir attribute so the visual arrow still points at Target.
	RankReverse bool
	// PenWidth is the edge line width. 0 means the renderer applies the default
	// (1.0 in resolved views, 2.0 in --expanded mode).
	PenWidth float64
}

type EdgeLabel struct {
	// Technology appears in brackets (e.g., [HTTP]).
	Technology string
	// Description describes the relationship.
	Description string
	// Position is where the label appears (middle, head, tail).
	Position string
}

type Graph struct {
	// Title is the diagram title.
	Title string
	// Direction is the layout direction (default: "TB" for top-to-bottom).
	Direction string
	// EdgeStyle is the edge routing style (straight, spline, square).
	EdgeStyle string
	// Opts carries the suppression switches (--plain + granular flags),
	// copied at graph construction by BuildGraph, BuildExpandedGraph and
	// BuildGraphWithPath.
	Opts RenderOpts
	// Nodes are all top-level nodes in the graph.
	Nodes []*Node
	// Edges are all edges connecting nodes.
	Edges []*Edge
	// Clusters are subgraph clusters for expanded units.
	Clusters []*Cluster
	// Legend contains legend information for the diagram.
	Legend *Legend
	// Navigation contains breadcrumb and back-link info (nil for C1).
	Navigation *Navigation
}

type Label struct {
	// Name is the primary name (with [+] indicator if expandable).
	Name string
	// Technology is the technology string (optional).
	Technology string
	// Description is the description text (optional).
	Description string
	// Icon is the emoji/icon prefix (optional).
	Icon string
}

type Legend struct {
	Entries []LegendEntry
}

type LegendEntry struct {
	// Label explains the row (e.g. "container", "read").
	Label string
	// Color is the colour the row documents (element border/label colour or
	// link-kind colour). Empty falls back to the muted secondary grey.
	Color string
}

type Navigation struct {
	// BackLink is the parent back-link (nil for C1 root).
	BackLink *BackLink
	// Breadcrumbs is the breadcrumb trail from root to current.
	Breadcrumbs []BreadcrumbItem
}

type Node struct {
	// ID is a unique identifier (the unit's full path).
	ID string
	// Label contains the formatted label parts.
	Label *Label
	// Shape is the node shape (determined by type).
	Shape Shape
	// Type is the unit type (used for special rendering like Person HTML labels).
	Type model.UnitType
	// Style contains visual styling attributes.
	Style *NodeStyle
	// IsExternal indicates if this is an external boundary node.
	IsExternal bool
	// IsInCluster indicates if this node is inside a cluster.
	IsInCluster bool
	// ExploreURL is the relative path for drill-down (empty if not expandable).
	ExploreURL string
	// ReferenceURL is the external docs URL (📖), empty if none.
	ReferenceURL string
}

type NodeStyle struct {
	// FillColor is the background color.
	FillColor string
	// BorderColor is the border color.
	BorderColor string
	// FontColor is the text color.
	FontColor string
	// BorderStyle is "solid" or "dashed".
	BorderStyle string
	// BorderWidth is the penwidth attribute emitted on this style; 0 means the
	// renderer default (no attribute emitted). Mirrors Edge.PenWidth (D-02).
	BorderWidth float64
}

type RenderOpts struct {
	// Plain mirrors View.Plain (--plain): author-custom formatting is ignored
	// and units/edges fall back to defaults.
	Plain bool
	// NoColors mirrors View.NoColors (--no-colors): author + kind colouring
	// suppressed, source-border default retained.
	NoColors bool
	// NoStyles mirrors View.NoStyles (--no-styles): line/border styles
	// suppressed.
	NoStyles bool
	// NoLength mirrors View.NoLength (--no-length): minlen suppressed.
	NoLength bool
	// NoRank mirrors View.NoRank (--no-rank): rank hints suppressed.
	NoRank bool
	// NoLabels mirrors View.NoLabels (--no-labels, BUG-2 — supersedes the
	// phase-38 LBL-01 pin): EDGE label text only; node, cluster and legend
	// labels are unaffected.
	NoLabels bool
}

type Shape string