# Graph Layout agent guide

Stateless graph layout service: graph spec in, SVG and layout diagnostics out.
Origin: `https://graph-layout.jessald.excessivecode.com`. No auth, CORS open,
zero provider calls. Use explicit client timeouts (15 s is plenty for one graph).
Info Elements keeps saved diagrams, chat notes, annotation UI and the review
corpus; it calls this service for every layout.

## Render one graph

`POST /api/render/graph` with `{schema_version:1,title,containers,nodes,edges,layout?,theme?,annotations?,frame?}`.
Returns `{schema_version, renderer_version, svg, diagnostics, metering, annotations}`.

- Renderable layouts that fail quality checks still return 200 with
  `diagnostics.valid: false` and `quality_warning`; show the diagram with a
  visible warning instead of hiding it.
- Cycles are supported; cycle-closing edges use feedback lanes.
- Optional `frame: {width}` (180–3840 CSS px) asks for the readable narrow
  layout; `diagnostics.orientation` reports the chosen direction. Omit it for
  the canonical desktop layout.
- `theme` accepts `canvas`, `surface`, `surface_alt`, `text`, `muted`, `line`,
  `edge` as 6-digit hex, plus `font_family` of `system-ui` or `ui-monospace`.
  Painted text pairs must clear 3:1 contrast. Anything else is a 400.
- Invalid input returns 400 with `{error}`.

## Batch and comparison engines

- `POST /api/render/batch` `{cases:[{id,spec,frame?}]}` (1–250). `frame` may be
  a full renderer frame object. Returns per-case `{id,svg,diagnostics,render_error}`.
- `POST /api/shadow/elk` and `POST /api/shadow/dot|neato` `{cases:[{id,spec,frame}]}`:
  the same cases drawn by ELK or Graphviz, for comparison only. 504 on deadline.
- `POST /api/render/node-groups` `{nodes,edges,groups:[{id,label,members}]}`:
  experimental membership regions (ELK packing + libavoid routing). Limits 100
  nodes, 200 edges, 20 groups; 400 bad input, 502 worker failure, 504 timeout.

## Browser module

`GET /api/components/graph-layout.js` (ES module, Dagre bundled) for live graphs
the host draws itself: `layeredPositions`, `transitiveReduction`, `graphShape`,
`routeEdge`. Rebuild with `node scripts/build-graph-layout.mjs` (dev deps).

## Other

- `GET /api/corpus/cases` — curated layout evaluation graphs (reviewed in Info Elements `/demos`).
- `GET /api/render/graph/source` — source of the main layout helpers.
- `GET /api/version` — `renderer_version`; `GET /api/health`.