graph

Documentation

Overview

Package graph defines flowgo's in-memory graph model and the .flowgo text-format parser/serializer.

The package is intentionally small: types with their JSON tags (which must match the wire format the editor consumes over /state and /save), Parse, and Serialize. Anything richer (validation, HTTP handlers, MCP tools) lives in the upstream binary or in downstream consumers.

Index

• Constants
• func NormalizeLabel(raw string) string
• func Serialize(g Graph) string
• type Box
• type Edge
• type Graph
  • func Parse(s string) (Graph, error)
• type Line
• type NamedMap
• type Stroke
• type Text

Constants

const MaxLabelLen = 500

MaxLabelLen mirrors MAX_LABEL_LEN in the JS editor. Box and text labels are clamped to this length on every entry path that produces new graph data — JS finish(), MCP add_box / update_box / add_text, any future ingestion. The validator flags anything longer in already-stored data.

Functions

func NormalizeLabel

func NormalizeLabel(raw string) string

NormalizeLabel collapses every run of non-newline whitespace to a single space, trims each line, drops fully-blank leading / trailing lines, and hard-caps to MaxLabelLen. Newlines are preserved — they render as hard line breaks in the editor and round-trip through the .flowgo file as a `\n` escape inside a quoted label. Mirrors normalizeLabel() in src/graph/label.ts.

The .flowgo text format is line-based, so a literal newline inside a label would corrupt the file; the serializer in graph.go handles the escape and the tokenizer decodes it on the way back in.

func Serialize

func Serialize(g Graph) string

Serialize emits the .flowgo text format. Empty maps are dropped — they get re-created on demand if a consumer navigates back to them.

Types

type Box

type Box struct {
	ID       string  `json:"id"`
	Label    string  `json:"label"`
	X        float64 `json:"x"`
	Y        float64 `json:"y"`
	Sides    int     `json:"sides,omitempty"`
	Palette  int     `json:"palette,omitempty"`
	Font     int     `json:"font,omitempty"`
	Rotation int     `json:"rotation,omitempty"`
	// Anchor marks this box as the map-level recenter target. At most
	// one box per map carries Anchor=true; the parser/serializer enforce
	// the invariant. Persisted in the .flowgo text format as a separate
	// per-map `anchor <id>` directive rather than a positional token.
	Anchor bool `json:"anchor,omitempty"`
}

Box is a node on a map. JSON tags are part of the public contract: they're consumed by the editor and any other process that exchanges graphs as JSON.

type Edge

type Edge struct {
	From       string `json:"from"`
	FromHandle string `json:"fromHandle,omitempty"`
	To         string `json:"to"`
	ToHandle   string `json:"toHandle,omitempty"`
}

Edge connects two boxes within the same map.

type Graph

type Graph struct {
	Maps []NamedMap `json:"maps"`
}

Graph is the full document — every map keyed by its path.

func Parse

func Parse(s string) (Graph, error)

Parse reads the .flowgo text format and returns the resulting Graph. Unknown directives produce an error rather than being silently dropped, so a downstream package init that depends on Parse fails loudly when the format gains a new directive.

type Line

type Line struct {
	ID string  `json:"id"`
	X1 float64 `json:"x1"`
	Y1 float64 `json:"y1"`
	X2 float64 `json:"x2"`
	Y2 float64 `json:"y2"`
}

Line is a static two-point segment.

type NamedMap

type NamedMap struct {
	Path    string   `json:"path"`
	Boxes   []Box    `json:"boxes"`
	Edges   []Edge   `json:"edges"`
	Texts   []Text   `json:"texts,omitempty"`
	Lines   []Line   `json:"lines,omitempty"`
	Strokes []Stroke `json:"strokes,omitempty"`
}

NamedMap is one canvas at a given path. Submap paths are slash- separated box ids: "/A/B" hangs off box A on "/" and box B on "/A".

type Stroke

type Stroke struct {
	ID     string      `json:"id"`
	Points [][]float64 `json:"points"`
}

Stroke is a freehand polyline (brush mode).

type Text

type Text struct {
	ID      string  `json:"id"`
	Label   string  `json:"label"`
	X       float64 `json:"x"`
	Y       float64 `json:"y"`
	Palette int     `json:"palette,omitempty"`
	Font    int     `json:"font,omitempty"`
}

Text is a free-floating annotation.