Go library and APIs

go get github.com/MarkovWangRR/iso-topology@latest

package main

import (
    "fmt"
    isotopo "github.com/MarkovWangRR/iso-topology"
)

func main() {
    yaml := []byte(`
canvas: {background: "#FAFBFC", grid: iso}
nodes:
  scene:
    shape: composite
    parts:
      - id: api
        shape: rectangle
        geom: {w: 120, d: 80, h: 30}
        label: API
      - id: db
        shape: cylinder
        offset: {wx: 200, wy: 0}
        geom: {w: 100, d: 100, h: 36}
        label: DB
    connectors:
      - {from: api, to: db, arrow: triangle}
`)
    // One-shot: validate + render any DSL text (yaml | json | d2) to one SVG.
    svg, issues, _ := isotopo.RenderSource("yaml", yaml)
    for _, i := range issues {
        fmt.Println(i.Severity, i.Path, i.Message)
    }
    fmt.Print(svg)
}

src := []byte(`# my diagram
nodes:
  scene:
    shape: composite
    layout: {mode: row, gap: 1}
    parts:
      - {id: api, shape: rectangle, geom: {w: 120, d: 80, h: 30}, label: API}
      - {id: db,  shape: cylinder,  geom: {w: 100, d: 100, h: 36}, label: DB}
`)

// Drag "api" by (+50, 0) world units. ApplyOp returns the rewritten DSL,
// a fresh SVG and validation issues; ApplyOpText returns only the new text.
op := isotopo.EditOp{Kind: "move", Target: "node", ID: "api", DWX: 50, DWY: 0}
newSrc, svg, issues, err := isotopo.ApplyOp("yaml", src, op)
_ = svg; _ = issues; _ = err
// newSrc still starts with "# my diagram" — comments survive.

// Apply only the text transform (e.g. you render separately, or with ELK):
newSrc, err := isotopo.ApplyOpText("yaml", src, op)

// 1. Parse input
isotopo.Parse(data []byte) (*Document, error)        // YAML or JSON auto-sniffed
isotopo.ParseYAML(data []byte) (*Document, error)
isotopo.ParseJSON(data []byte) (*Document, error)
isotopo.LoadInput(ctx, format string, data []byte, engine LayoutEngine) (*Document, error) // yaml|json|d2

// 2. For .d2 input: compile then translate
isotopo.CompileD2(ctx, src string, engine LayoutEngine) (*d2target.Diagram, error)
isotopo.Translate(diag *d2target.Diagram, opts *RenderOpts) *Document

// 3. Validate (optional)
isotopo.Validate(doc *Document) []Issue
isotopo.UnknownKeyIssues(data []byte) []Issue        // misspelled/unknown DSL keys

// 4. Render
isotopo.Render(n *Node, theme *Theme) string                          // single node, no canvas
isotopo.RenderWithCanvas(n, theme, canvas, anns) string                // scene with backdrop + callouts
                                                                       //   (canvas.Projection == "top" → flat plan view)
isotopo.RenderDocument(doc *Document) map[string]string                // every node → SVG
isotopo.RenderScene(doc *Document) SceneResult                        // SVG + routes + final screen labels
isotopo.RenderSceneWithInteraction(doc *Document) SceneResult         // same submitted scene + world interaction model
isotopo.RenderSceneWithReport(doc *Document) (SceneResult, RenderReport)
isotopo.RenderParts(doc *Document) map[string]string                   // atomic per-part SVGs
isotopo.NodeHTML(id, svg, yamlFragment string) string                  // self-contained viewer page for ONE node (svg + source)
isotopo.NodesIndexHTML(ids []string) string                            // gallery index page linking every per-node view
isotopo.RenderPlan(n, theme, canvas, anns) string                      // flat top-down plan view directly

isotopo.RenderSource(format string, src []byte) (svg string, issues []Issue, err error)
isotopo.ApplyOp(format string, src []byte, op EditOp) (newSrc []byte, svg string, issues []Issue, err error)
isotopo.ApplyOpText(format string, src []byte, op EditOp) (newSrc []byte, err error)

isotopo.EvaluatePlan(n, theme, canvas) *PlanReport          // plan-router routes
isotopo.EvaluateIso(n, theme, canvas) *PlanReport           // the engine's REAL routes
isotopo.EvaluatePlanText(format string, src []byte) (*PlanReport, error)
isotopo.EvaluateIsoText(format string, src []byte) (*PlanReport, error)
isotopo.RenderPlanAnnotated(n, theme, canvas) (svg string, report *PlanReport)  // plan view + red problem marks

// Document model
doc.Scene() *Node                       // resolves the topology-level composite
isotopo.PartIDs(doc) []string           // every renderable part id
isotopo.PartFragments(doc) map[string]*Document  // each part as a standalone doc
isotopo.MarshalFragmentYAML(d) ([]byte, error)

// Resolve what the renderer actually uses (cascade + layout) for a part —
// the basis of Studio's "effective value" hints.
isotopo.ResolvePartStyle(doc *Document, id string) *Style
isotopo.ResolvePartGeom(doc *Document, id string) (w, d, h float64, ok bool)
isotopo.ResolvePartOffset(doc *Document, id string) (wx, wy, wz float64, ok bool)

// Theme cascade
isotopo.ResolveStyle(theme, shape, preset string, override *Style) *Style
isotopo.MergeStyle(base, over *Style) *Style

// Iso lowering
isotopo.Flatten(n *Node, theme *Theme) (shape string, opts iso25d.ConvertOpts)

// Introspection
isotopo.CapabilityReport() Capabilities

import "github.com/MarkovWangRR/iso-topology/yamledit"

out, ok := yamledit.SetField(src, line, []string{"style","palette","top"}, "#FFF")

import "github.com/MarkovWangRR/iso-topology/iso25d"

svg := iso25d.Convert2DTo25D("cylinder", iso25d.ConvertOpts{
    Width: 100, Depth: 100, Height: 40,
    TopFill: "#FFF", LeftFill: "#888", RightFill: "#BBB",
})