gg-render

gg-render

Render a gridgram diagram and surface any problems the user should know about.

Inputs to collect

• The diagram source. Preferred: a path to a .gg file. Also acceptable: inline .gg text (write it to a tempfile), or a TypeScript DiagramDef (the user should be on the TS side of the API in that case; see gg llm for the envelope schema).
• The desired output: svg (default), png, or json (the merged DiagramDef + diagnostics).
• Optional: --width, --cell-size, --frame, --icons <dir>, --alias name=dir.

Workflow

1. Locate or materialize the source. If the user pasted .gg text, write it to ./tmp.gg (or a path they specified).
2. Validate first. Always run:

   gg <input.gg> --format json --diagnostics --stdout > /tmp/gg-check.json 2>/tmp/gg-diag.json
   

   • Exit code 1 → parse error (bad syntax). Show the stderr verbatim.
   • Exit code 2 → integrity error (unknown node ref, region not 4-connected, etc.).
   • Exit code 3 → I/O or environment (missing sharp for PNG, missing file, etc.).
3. Check diagnostics. Even on exit 0, /tmp/gg-diag.json may contain warnings (unresolved icons, routing failures, collisions). Summarize them for the user.
4. Produce the final artifact:

   gg <input.gg> -o <output>.svg          # or .png, or .json
   

   Respect any width/scale/frame flags the user supplied.
5. Report the output path, the size (if PNG/SVG), and the diagnostics count. If diagnostics are non-empty, suggest concrete fixes (e.g. "icon tabler/serverr not found — did you mean tabler/server?").

Best practices

• Use tabler/<name> (outline) or tabler/filled/<name> for icons. Use the /gg-icons skill to search when unsure.
• Prefer A1 position strings (@A1) over tuples for human-readable source.
• Never hand-edit SVG output; rerender from .gg instead.