@standarx/graph 0.0.0-stage โ†’ 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/LICENSE +21 -0
  2. package/README.fr.md +438 -0
  3. package/README.md +437 -2
  4. package/THIRD_PARTY_NOTICES.md +22 -0
  5. package/assets/fonts/Inter-Regular.ttf +0 -0
  6. package/assets/fonts/Inter-SemiBold.ttf +0 -0
  7. package/assets/fonts/OFL.txt +92 -0
  8. package/dist/adapter-0bggwh8x.js +393 -0
  9. package/dist/cli-4m00785g.js +20 -0
  10. package/dist/cli-5v9761s9.js +330 -0
  11. package/dist/cli-9f1pdw5q.js +462 -0
  12. package/dist/cli-a4ax1vkc.js +172 -0
  13. package/dist/cli-abzdy8pn.js +1144 -0
  14. package/dist/cli-gh5166k6.js +1565 -0
  15. package/dist/cli-m29a3wgx.js +579 -0
  16. package/dist/cli-mzmjkk5v.js +11 -0
  17. package/dist/cli-nhmh6yxk.js +2485 -0
  18. package/dist/cli-nyckgf1t.js +4 -0
  19. package/dist/cli-sfdqkbd1.js +433 -0
  20. package/dist/cli-txrzzr2q.js +0 -0
  21. package/dist/cli-vecew2na.js +709 -0
  22. package/dist/cli-wt9dmbhm.js +560 -0
  23. package/dist/cli-ywgtv1cg.js +39 -0
  24. package/dist/cli-z3ccx2y4.js +141 -0
  25. package/dist/cli.d.ts +2 -0
  26. package/dist/cli.js +413 -0
  27. package/dist/core/index.d.ts +6 -0
  28. package/dist/core/index.js +91 -0
  29. package/dist/core/spatial.d.ts +16 -0
  30. package/dist/core/threshold.d.ts +1 -0
  31. package/dist/core/view.d.ts +80 -0
  32. package/dist/export/index.d.ts +18 -0
  33. package/dist/export/index.js +170 -0
  34. package/dist/export/pdf.d.ts +5 -0
  35. package/dist/export/png.d.ts +4 -0
  36. package/dist/format/index.d.ts +4 -0
  37. package/dist/format/index.js +69 -0
  38. package/dist/format/json-schema.d.ts +2 -0
  39. package/dist/format/schema.d.ts +787 -0
  40. package/dist/format/semantic/er.d.ts +3 -0
  41. package/dist/format/semantic/graph.d.ts +3 -0
  42. package/dist/format/semantic/sequence.d.ts +3 -0
  43. package/dist/format/semantic/shared.d.ts +14 -0
  44. package/dist/format/semantic/state.d.ts +3 -0
  45. package/dist/format/semantic/tree.d.ts +3 -0
  46. package/dist/format/transition-label.d.ts +2 -0
  47. package/dist/format/validate.d.ts +11 -0
  48. package/dist/html/index.d.ts +3 -0
  49. package/dist/html/index.js +125 -0
  50. package/dist/html/layout-worker.d.ts +1 -0
  51. package/dist/html/layout-worker.generated.d.ts +1 -0
  52. package/dist/html/mount.d.ts +12 -0
  53. package/dist/html/page.d.ts +14 -0
  54. package/dist/html/render.d.ts +7 -0
  55. package/dist/html/runtime.d.ts +1 -0
  56. package/dist/html/runtime.generated.d.ts +1 -0
  57. package/dist/html/shell.d.ts +10 -0
  58. package/dist/html/svg-adapter.d.ts +8 -0
  59. package/dist/html/ui.d.ts +34 -0
  60. package/dist/language/actions.d.ts +3 -0
  61. package/dist/language/analysis.d.ts +38 -0
  62. package/dist/language/complete.d.ts +3 -0
  63. package/dist/language/diagnostics.d.ts +14 -0
  64. package/dist/language/docs.d.ts +11 -0
  65. package/dist/language/format.d.ts +17 -0
  66. package/dist/language/hover.d.ts +3 -0
  67. package/dist/language/index.d.ts +8 -0
  68. package/dist/language/index.js +1560 -0
  69. package/dist/language/navigation.d.ts +9 -0
  70. package/dist/language/positions.d.ts +7 -0
  71. package/dist/language/symbols.d.ts +3 -0
  72. package/dist/language/types.d.ts +46 -0
  73. package/dist/layout/elk.d.ts +35 -0
  74. package/dist/layout/er.d.ts +3 -0
  75. package/dist/layout/font-metrics.d.ts +9 -0
  76. package/dist/layout/graph.d.ts +3 -0
  77. package/dist/layout/index.d.ts +5 -0
  78. package/dist/layout/index.js +16 -0
  79. package/dist/layout/measure.d.ts +10 -0
  80. package/dist/layout/sequence.d.ts +3 -0
  81. package/dist/layout/shapes.d.ts +16 -0
  82. package/dist/layout/shared.d.ts +31 -0
  83. package/dist/layout/state.d.ts +3 -0
  84. package/dist/layout/tree.d.ts +3 -0
  85. package/dist/layout/types.d.ts +198 -0
  86. package/dist/layout-worker.generated-xsmtzrfj.js +34 -0
  87. package/dist/mermaid/common.d.ts +36 -0
  88. package/dist/mermaid/er.d.ts +3 -0
  89. package/dist/mermaid/graph.d.ts +4 -0
  90. package/dist/mermaid/index.d.ts +6 -0
  91. package/dist/mermaid/index.js +6 -0
  92. package/dist/mermaid/mindmap.d.ts +3 -0
  93. package/dist/mermaid/sequence.d.ts +3 -0
  94. package/dist/mermaid/state.d.ts +3 -0
  95. package/dist/remark/index.d.ts +9 -0
  96. package/dist/remark/index.js +102 -0
  97. package/dist/shared/errors.d.ts +6 -0
  98. package/dist/shared/package-root.d.ts +5 -0
  99. package/dist/svg/escape.d.ts +1 -0
  100. package/dist/svg/index.d.ts +3 -0
  101. package/dist/svg/index.js +25 -0
  102. package/dist/svg/render.d.ts +9 -0
  103. package/dist/svg/theme.d.ts +62 -0
  104. package/dist/svg-adapter-gq5vmp6q.js +227 -0
  105. package/dist/text/build.d.ts +10 -0
  106. package/dist/text/canonical.d.ts +10 -0
  107. package/dist/text/errors.d.ts +33 -0
  108. package/dist/text/highlight.d.ts +13 -0
  109. package/dist/text/index.d.ts +33 -0
  110. package/dist/text/index.js +25 -0
  111. package/dist/text/lexer.d.ts +29 -0
  112. package/dist/text/parser.d.ts +160 -0
  113. package/dist/text/print.d.ts +6 -0
  114. package/dist/text/slug.d.ts +1 -0
  115. package/dist/text/syntax.d.ts +8 -0
  116. package/dist/version.d.ts +1 -0
  117. package/dist/webgl/adapter.d.ts +4 -0
  118. package/dist/webgl/index.d.ts +7 -0
  119. package/dist/webgl/index.js +15 -0
  120. package/dist/webgl/runtime.d.ts +1 -0
  121. package/dist/webgl/runtime.generated.d.ts +1 -0
  122. package/grammars/standargraph.tmLanguage.json +599 -0
  123. package/language-configuration.json +35 -0
  124. package/licenses/EPL-2.0.txt +277 -0
  125. package/licenses/MPL-2.0.txt +373 -0
  126. package/package.json +133 -4
  127. package/schema/graph-document.v1.json +1737 -0
package/README.md CHANGED
@@ -1,3 +1,438 @@
1
- # Temporary Holding Version
1
+ # StandarGraph
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/miralabs-tech/standargraph/actions/workflows/ci.yml/badge.svg)](https://github.com/miralabs-tech/standargraph/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@standarx/graph)](https://www.npmjs.com/package/@standarx/graph) [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE) [![node](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
4
+
5
+ > "Declarative diagrams from JSON (graphs, sequences, state machines, entity-relation and trees), rendered to SVG, interactive HTML, PNG and PDF, with WebGL beyond 2000 graph nodes."
6
+
7
+ ๐Ÿ“– English ยท [Franรงais](./README.fr.md)
8
+
9
+ [Quickstart](#-quickstart) ยท [Install](#-install) ยท [Features](#-features) ยท [Diagram kinds](#-diagram-kinds) ยท [Theming](./docs/theming.md) ยท [Limits](#-limits) ยท [Headless core](./docs/headless.md) ยท [Benchmark](./docs/bench.md) ยท [Changelog](./CHANGELOG.md)
10
+
11
+ [![Settings page flow](./docs/assets/architecture.svg)](./docs/assets/architecture.html)
12
+
13
+ [![OAuth 2.0 authorization code flow with PKCE](./docs/assets/protocol.svg)](./docs/assets/protocol.html)
14
+
15
+ Both images above come from the CLI (`examples/architecture.json` and `examples/protocol.json`). Each links to a self-contained interactive viewer: download the `.html` file and open it in a browser.
16
+
17
+ **Live demo**: the [playground](https://miralabs-tech.github.io/standargraph/) renders the text syntax or JSON as you type, offline once loaded, and every example has an interactive page: [architecture](https://miralabs-tech.github.io/standargraph/examples/architecture.html), [protocol](https://miralabs-tech.github.io/standargraph/examples/protocol.html).
18
+
19
+ ---
20
+
21
+ ## ๐Ÿง  What is StandarGraph?
22
+
23
+ You describe a diagram in a JSON document (`version: 1`, `kind` one of `"graph"`, `"sequence"`, `"state"`, `"er"` or `"tree"`), and StandarGraph lays it out and renders it. Nodes, edges and groups can carry optional metadata: provenance (source, confidence, tool), coverage and freshness, so a diagram produced by a tool or an agent says how far it can be trusted.
24
+
25
+ The layout and the view (camera, hit testing, culling, level of detail, hover, selection, search) form a headless core that never touches the DOM. Adapters sit on top of it: an SVG renderer, an interactive HTML page, and a WebGL renderer built on [Sigma.js](https://www.sigmajs.org) for large graphs.
26
+
27
+ Outputs are SVG, a single-file HTML page that works offline (fonts and runtime embedded, no network), PNG and PDF. PNG and PDF are rendered without a browser.
28
+
29
+ **Status: 1.1.0.**
30
+
31
+ ---
32
+
33
+ ## ๐Ÿš€ Quickstart
34
+
35
+ A minimal graph document, `graph.json`:
36
+
37
+ ```json
38
+ {
39
+ "version": 1,
40
+ "kind": "graph",
41
+ "title": "Hello",
42
+ "nodes": [
43
+ { "id": "a", "label": "Client" },
44
+ { "id": "b", "label": "Server" }
45
+ ],
46
+ "edges": [{ "from": "a", "to": "b", "label": "requests", "directed": true }]
47
+ }
48
+ ```
49
+
50
+ ### CLI
51
+
52
+ ```sh
53
+ standargraph validate graph.json
54
+ standargraph export graph.json # graph.svg and graph.html next to the input
55
+ standargraph export graph.json --format svg,html,png,pdf --out out --theme dark
56
+ standargraph export graph.json --renderer webgl # force the WebGL page
57
+ standargraph export graph.json --markdown # also print a Markdown preview snippet
58
+ standargraph export graph.json --format mermaid # graph.mmd, for GitHub Markdown (see docs/mermaid.md)
59
+ standargraph layout graph.json # graph.positioned.json: every node gets its computed position
60
+ standargraph convert graph.json # graph.sg, the same document in the text syntax
61
+ standargraph convert graph.sg --to json --out out/graph.json
62
+ ```
63
+
64
+ Every command reads JSON or the [text syntax](#text-syntax): the format is detected from the content, never from the file extension. `validate` exits 0 when the document is valid, 1 with one `path: message` line per JSON error (or one `file:line:col: message [code]` line per text error) otherwise, 2 when the file cannot be read. `layout` always writes JSON. `convert` writes the other format than the input unless `--to json|text` says otherwise, and exits 2 with `Output would overwrite the input` when the output is the input file.
65
+
66
+ | Option | Meaning |
67
+ | --- | --- |
68
+ | `--format <list>` | Comma-separated: `svg`, `html`, `png`, `pdf`, `mermaid` (default `svg,html`); `mermaid` writes `<base>.mmd` and prints its warnings on stderr |
69
+ | `--out <dir>` | Output directory (default: the input file directory) |
70
+ | `--name <base>` | Output base name (default: the input file name without `.json` or `.sg`) |
71
+ | `--theme <theme>` | `auto` (default), a palette name (`light`, `dark`, `nord`, `solarized-light`, `solarized-dark`, `high-contrast`) or a `.json` theme file, see [docs/theming.md](./docs/theming.md) |
72
+ | `--no-palette` | Turn off the automatic color per item `type` |
73
+ | `--scale <n>` | PNG scale factor (default 2) |
74
+ | `--renderer <name>` | HTML renderer: `auto`, `svg` or `webgl` (default `auto`) |
75
+ | `--markdown` | Print `[![title](base.svg)](base.html)`, a Markdown snippet linking the SVG preview to the HTML page; with `mermaid` in `--format`, a fenced `mermaid` code block follows |
76
+
77
+ ### JavaScript
78
+
79
+ Every subpath is a separate entry point of `@standarx/graph`.
80
+
81
+ ```ts
82
+ import { validate } from "@standarx/graph/format";
83
+ import { layout } from "@standarx/graph/layout";
84
+ import { renderSvg } from "@standarx/graph/svg";
85
+ import { renderHtml } from "@standarx/graph/html";
86
+
87
+ const result = validate(JSON.parse(text));
88
+ if (!result.ok) throw new Error(result.errors.map((e) => `${e.path}: ${e.message}`).join("\n"));
89
+
90
+ const scene = await layout(result.document);
91
+ const svg = renderSvg(scene, { theme: "light" });
92
+ const html = renderHtml(result.document, scene, { theme: "auto", renderer: "auto" });
93
+ ```
94
+
95
+ All formats in one call, from `/export`:
96
+
97
+ ```ts
98
+ import { exportDocument } from "@standarx/graph/export";
99
+
100
+ const out = await exportDocument(graphDocument, { formats: ["svg", "png", "pdf"], theme: "light", scale: 2 });
101
+ // out.svg is a string, out.png and out.pdf are Uint8Array
102
+ ```
103
+
104
+ Mermaid text for GitHub Markdown, from `/mermaid` (`formats: ["mermaid"]` in `exportDocument()` returns the same text as a string, without the warnings):
105
+
106
+ ```ts
107
+ import { toMermaid } from "@standarx/graph/mermaid";
108
+
109
+ const { text, warnings } = toMermaid(graphDocument);
110
+ ```
111
+
112
+ Mount an interactive graph in a page (`mount(container, document, { theme, title, renderer })`). When every node has a `position`, ELK is skipped; otherwise the layout runs in a Web Worker and the main thread stays free. Several instances can live on one page:
113
+
114
+ ```ts
115
+ import { mount } from "@standarx/graph/html";
116
+
117
+ const { view, destroy } = await mount(document.getElementById("graph")!, graphDocument, { renderer: "auto" });
118
+ ```
119
+
120
+ Markdown pipelines, with the remark plugin (it turns ` ```standargraph ` and ` ```sg ` code blocks holding a JSON document or the text syntax into an inline SVG, linked to a standalone HTML page when `outDir` is set):
121
+
122
+ ```ts
123
+ import { unified } from "unified";
124
+ import remarkParse from "remark-parse";
125
+ import { remarkStandargraph } from "@standarx/graph/remark";
126
+
127
+ unified().use(remarkParse).use(remarkStandargraph, { outDir: "public/diagrams", publicPath: "/diagrams", theme: "auto" });
128
+ ```
129
+
130
+ The headless core, for your own renderer (see [docs/headless.md](./docs/headless.md)):
131
+
132
+ ```ts
133
+ import { createView, layout } from "@standarx/graph/core";
134
+
135
+ const view = createView(await layout(graphDocument));
136
+ view.setViewport(1280, 800);
137
+ view.fit();
138
+ view.subscribe(() => draw(view));
139
+ ```
140
+
141
+ The editor features of the text syntax, with no language server dependency (see [docs/language-service.md](./docs/language-service.md)):
142
+
143
+ ```ts
144
+ import { codeActions, complete, diagnostics, format } from "@standarx/graph/language";
145
+
146
+ const items = complete(source, { line: 2, character: 3 });
147
+ const edits = format(source);
148
+ const problems = diagnostics(source);
149
+ const fixes = codeActions(source, problems[0].range);
150
+ ```
151
+
152
+ ---
153
+
154
+ ## ๐Ÿงฉ Diagram kinds
155
+
156
+ Every document has `version: 1` and a `kind`. The files in [examples](./examples) are complete documents for each kind.
157
+
158
+ ### `graph` and `sequence`
159
+
160
+ `graph` holds `nodes`, `edges` and nested `groups`; `sequence` holds `participants` and `messages`. See the quickstart above and `examples/architecture.json` and `examples/protocol.json`.
161
+
162
+ ### `state`
163
+
164
+ States, optional pseudo-states (`initial`, `final`, `choice`, `fork`, `join`, `history`), composite states through `parent`, and transitions with `event`, `guard` and `action`. From `examples/order-state.json`:
165
+
166
+ ```json
167
+ {
168
+ "version": 1,
169
+ "kind": "state",
170
+ "title": "Order lifecycle",
171
+ "direction": "right",
172
+ "states": [
173
+ { "id": "__initial", "pseudo": "initial" },
174
+ { "id": "pending", "label": "Pending", "actions": ["entry / reserve stock"] },
175
+ { "id": "paid", "label": "Paid" },
176
+ { "id": "__final", "pseudo": "final" }
177
+ ],
178
+ "transitions": [
179
+ { "from": "__initial", "to": "pending" },
180
+ { "from": "pending", "to": "paid", "event": "payment received" },
181
+ { "from": "paid", "to": "__final" }
182
+ ]
183
+ }
184
+ ```
185
+
186
+ ### `er`
187
+
188
+ Entities with attributes (`keys`: `pk`, `fk`, `uk`; `nullable`; `note`) and relations drawn with crow's foot cardinalities (`one`, `zero-or-one`, `one-or-more`, `zero-or-more`). From `examples/shop-er.json`:
189
+
190
+ ```json
191
+ {
192
+ "version": 1,
193
+ "kind": "er",
194
+ "title": "Shop orders",
195
+ "entities": [
196
+ {
197
+ "id": "customer",
198
+ "label": "Customer",
199
+ "attributes": [
200
+ { "name": "id", "type": "uuid", "keys": ["pk"] },
201
+ { "name": "email", "type": "varchar(255)", "keys": ["uk"] }
202
+ ]
203
+ },
204
+ {
205
+ "id": "order",
206
+ "label": "Order",
207
+ "attributes": [
208
+ { "name": "id", "type": "uuid", "keys": ["pk"] },
209
+ { "name": "customer_id", "type": "uuid", "keys": ["fk"] }
210
+ ]
211
+ }
212
+ ],
213
+ "relations": [
214
+ { "from": "customer", "to": "order", "fromCardinality": "one", "toCardinality": "zero-or-more", "label": "places" }
215
+ ]
216
+ }
217
+ ```
218
+
219
+ ### `tree`
220
+
221
+ A flat list of nodes linked by `parent`, laid out as a tidy tree (`"layout": "tree"`, the default, with a `direction`) or as a two-sided mindmap around the root (`"layout": "mindmap"`). From `examples/repo-tree.json` and `examples/roadmap-mindmap.json`:
222
+
223
+ ```json
224
+ {
225
+ "version": 1,
226
+ "kind": "tree",
227
+ "title": "Repository layout",
228
+ "layout": "mindmap",
229
+ "nodes": [
230
+ { "id": "repo", "label": "standargraph", "shape": "pill" },
231
+ { "id": "src", "label": "src", "parent": "repo" },
232
+ { "id": "format", "label": "format", "parent": "src" },
233
+ { "id": "tests", "label": "tests", "parent": "repo" }
234
+ ]
235
+ }
236
+ ```
237
+
238
+ ### Shapes
239
+
240
+ `shape` on a `graph` or `tree` node is one of `box` (the default), `rect`, `pill`, `diamond`, `circle`, `ellipse`, `hexagon`, `parallelogram`, `cylinder`, `document` and `subroutine`. Edges end on the outline of the shape, so a flowchart is a `graph` with shapes (`examples/deploy-flowchart.json`):
241
+
242
+ ```json
243
+ {
244
+ "version": 1,
245
+ "kind": "graph",
246
+ "direction": "down",
247
+ "nodes": [
248
+ { "id": "build", "label": "Build image", "shape": "rect" },
249
+ { "id": "green", "label": "Green?", "shape": "diamond" },
250
+ { "id": "done", "label": "Live", "shape": "pill" }
251
+ ],
252
+ "edges": [
253
+ { "from": "build", "to": "green", "directed": true },
254
+ { "from": "green", "to": "done", "label": "yes", "directed": true }
255
+ ]
256
+ }
257
+ ```
258
+
259
+ Shapes live in the document; colors never do. They come from the theme.
260
+
261
+ ### Text syntax
262
+
263
+ Every kind can also be written as plain text, in files conventionally named `.sg`. A graph in the symbol form:
264
+
265
+ ```
266
+ graph "Release flow" [direction=right]
267
+
268
+ live "Live" [shape=pill]
269
+ group ci "CI" {
270
+ build "Build image" [shape=rect]
271
+ check "Green?" [shape=diamond]
272
+ }
273
+
274
+ build -> check
275
+ check -> live "yes"
276
+ ```
277
+
278
+ The same graph in the word form, where `to`, `with`, `async`, `reply` and `via` replace the operators and `do` ... `end` replaces the braces:
279
+
280
+ ```
281
+ graph "Release flow" [direction=right]
282
+
283
+ live "Live" [shape=pill]
284
+ group ci "CI" do
285
+ build "Build image" [shape=rect]
286
+ check "Green?" [shape=diamond]
287
+ end
288
+
289
+ build to check
290
+ check to live "yes"
291
+ ```
292
+
293
+ Both forms read to the same document. `examples/` holds a `.sg` twin of every JSON example. The `/text` subpath exports `parse`, `print`, `canonicalize`, `sniff` and `loadSource`; a string passed to `mount()` or `exportDocument()` goes through `loadSource`, and `standargraph convert` turns one format into the other. In Markdown, a ` ```sg ` fence (or ` ```standargraph `) holds either format:
294
+
295
+ ````md
296
+ ```sg
297
+ graph "Release flow"
298
+
299
+ build -> check
300
+ ```
301
+ ````
302
+
303
+ #### Syntax highlighting
304
+
305
+ The package ships a TextMate grammar (`@standarx/graph/grammars/standargraph.tmLanguage.json`, scope `source.standargraph`), a `language-configuration.json` and `highlight(source)` in the `/text` subpath, which returns tokens typed with the LSP semantic token types. The online demo colors its editor with `highlight()`. A VS Code extension will consume these files from its own repository. See [docs/syntax-highlighting.md](./docs/syntax-highlighting.md).
306
+
307
+ ### Theming
308
+
309
+ A theme is a set of color tokens plus optional colors per node `type`, given as `--theme <file.json>` on the CLI or as the `theme` option of the API. Six palettes come ready to use, as `theme: "nord"` or `--theme nord`: `light`, `dark`, `nord`, `solarized-light`, `solarized-dark` and `high-contrast`, each with a contrast of at least 4.5:1 for its text.
310
+
311
+ - A typed item with no color of its own gets one from the palette of the theme, chosen by a stable hash of its `type`. `palette: false` in the theme, or `--no-palette`, turns it off, and a `types` entry always wins.
312
+ - With `"auto"` or a `{ light, dark }` pair, the interactive page and `mount()` show a toolbar button that cycles `auto`, `light` and `dark`, kept in `localStorage`.
313
+ - The online demo has a theme panel: a palette, the tokens, a color per type, and a `theme.json` to download for `--theme`.
314
+
315
+ See [docs/theming.md](./docs/theming.md).
316
+
317
+ ### GitHub Action
318
+
319
+ The composite action at the root of the repository renders your `.sg` files with the published CLI and never commits or pushes.
320
+
321
+ ```yaml
322
+ - uses: actions/checkout@v4
323
+ - uses: miralabs-tech/standargraph@v1
324
+ with:
325
+ files: "docs/**/*.sg"
326
+ mode: check
327
+ ```
328
+
329
+ | Input | Default | Meaning |
330
+ | --- | --- | --- |
331
+ | `files` | `**/*.sg` | Files to render |
332
+ | `formats` | `svg` | Export formats |
333
+ | `theme` | `light` | Theme of the render |
334
+ | `out` | empty (next to the source) | Output directory |
335
+ | `version` | the package version of the action ref | npm version of `@standarx/graph` to run |
336
+ | `mode` | `write` | `write` renders; `check` renders and fails, listing the files, when an output differs from the working tree or is missing |
337
+ | `cli-path` | empty | Path of a locally built `dist/cli.js`, used instead of the npm package (CI of this repository) |
338
+
339
+ [docs/diagrams-workflow.yml](./docs/diagrams-workflow.yml) is an example workflow that renders on push and commits the result with plain `git` commands. Copy it to `.github/workflows/diagrams.yml`.
340
+
341
+ ---
342
+
343
+ ## ๐Ÿ“ฆ Install
344
+
345
+ ```sh
346
+ npm install @standarx/graph
347
+ bun add @standarx/graph
348
+ ```
349
+
350
+ Node >= 20. The CLI is the `standargraph` binary. Once the package is installed, `npx standargraph` or `bunx standargraph` runs it; without installing, name the package:
351
+
352
+ ```sh
353
+ npx @standarx/graph export graph.json
354
+ bunx @standarx/graph export graph.json
355
+ npm install -g @standarx/graph # then: standargraph export graph.json
356
+ ```
357
+
358
+ ---
359
+
360
+ ## โœจ Features
361
+
362
+ - **Format v1**: JSON documents of five kinds, `graph` (nodes, edges, nested groups, optional fixed `position`), `sequence` (participants, messages), `state`, `er` and `tree` (see [Diagram kinds](#-diagram-kinds)), validated against a published [JSON Schema](./schema/graph-document.v1.json), with a `validate()` that returns one error per problem and its path.
363
+ - **Metadata**: provenance (`confirmed`, `inferred`, `unknown`), coverage and freshness on documents, nodes, edges and groups; low-confidence items are drawn muted.
364
+ - **Layout**: ELK layered layout for graphs, groups, state machines and entity-relation diagrams, a dedicated layout for sequence diagrams, a tidy or mindmap layout for trees, text measured with embedded Inter metrics so SVG and HTML agree.
365
+ - **Shapes**: 11 node shapes on `graph` and `tree` nodes, drawn in SVG and cut at the outline by the edges (see [Shapes](#shapes)).
366
+ - **Theming**: six named palettes, an automatic color per node `type`, a light, dark and auto switch, color tokens and colors per node `type`, one object for SVG, HTML, PNG and PDF, a `--theme <name|file.json>` option (see [docs/theming.md](./docs/theming.md)).
367
+ - **Renderers**: SVG, interactive HTML (pan, zoom, hover, selection, search, panel, keyboard, light and dark themes), and WebGL through Sigma.js.
368
+ - **WebGL above 2000 nodes**: the HTML export of a `graph` switches to WebGL automatically past 2000 nodes (`--renderer` overrides it). On the v1 gate, 10 000 nodes in WebGL hold a median of 303 FPS (p5 285.7) with the display refresh as the cap, and a median of 58.1 FPS (p5 54.3) uncapped, on an Intel Core i7-14700KF with an NVIDIA GeForce RTX 4070 Ti SUPER in Microsoft Edge 157. Details in [docs/bench.md](./docs/bench.md).
369
+ - **Offline single-file HTML**: fonts and runtime are embedded, nothing is fetched.
370
+ - **Export**: SVG, HTML, PNG and PDF from the CLI or `exportDocument()`, PNG and PDF without a browser (resvg WASM and PDFKit).
371
+ - **Headless core**: view controller with camera, hit testing, culling, level of detail and highlight, usable in Node, Bun, a worker or a browser.
372
+ - **Text syntax**: every kind as plain text (`.sg`), in a symbol or a word form, with line and column errors, `print()` back to text and `standargraph convert` between the two formats (see [Text syntax](#text-syntax)).
373
+ - **Mermaid export**: every kind as Mermaid text with `toMermaid()` or `--format mermaid`, with the losses reported as warnings (see [docs/mermaid.md](./docs/mermaid.md)).
374
+ - **Embedding**: `mount()` for applications, with an on-demand layout worker, and a remark plugin for Markdown.
375
+
376
+ ---
377
+
378
+ ## ๐Ÿšง Limits
379
+
380
+ - **Layout of large graphs is slow.** ELK lays out 10 000 nodes in about 44 s (5 000 nodes: 13 s, 2 000: 3.7 s; see [docs/bench.md](./docs/bench.md)). Rendering is not the bottleneck. A faster layout for large graphs is coming soon.
381
+ - **Precompute positions for large graphs.** Once every node has a `position`, ELK is skipped by `layout()`, `mount()` and the exports. `standargraph export` runs the layout once and the HTML page it writes carries the result: opening it never lays anything out again. To keep positions in your documents, run `standargraph layout graph.json` (or `--out <file>`): it writes the same document with a `position` on every node, which then renders without ELK.
382
+
383
+ - The remark plugin output does not render on GitHub. In a README, use the SVG written by the CLI, linked to its HTML page (`--markdown` prints the snippet).
384
+ - Node type captions, edge labels and arrowheads are not drawn by the WebGL renderer, and `sequence`, `state`, `er` and `tree` diagrams are always drawn as SVG.
385
+
386
+ ---
387
+
388
+ ## ๐Ÿ“š Documentation
389
+
390
+ - [Headless core and adapters](./docs/headless.md)
391
+ - [Theming](./docs/theming.md)
392
+ - [Syntax highlighting for `.sg`](./docs/syntax-highlighting.md)
393
+ - [Language service for `.sg`](./docs/language-service.md)
394
+ - [Mermaid export](./docs/mermaid.md)
395
+ - [Benchmark and layout times](./docs/bench.md)
396
+ - [JSON Schema of the format v1](./schema/graph-document.v1.json)
397
+ - [Examples](./examples)
398
+ - [Changelog](./CHANGELOG.md)
399
+
400
+ ---
401
+
402
+ ## ๐Ÿ› ๏ธ Build & tests
403
+
404
+ ```sh
405
+ bun install
406
+ bun run typecheck
407
+ bun test
408
+ bun run build
409
+ bun run smoke # the packed package, under Node
410
+ STANDARGRAPH_BROWSER_CHANNEL=msedge bun run test:browser # Playwright, set the channel of an installed browser
411
+ bun run bench # benchmark (Microsoft Edge, headed)
412
+ bun run runtime # regenerate the embedded HTML and WebGL runtimes
413
+ bun run site # build the GitHub Pages site into site-dist/
414
+ ```
415
+
416
+ CI pins bun 1.4.2 so that the generated bundles match the committed ones; use the same version before running `bun run runtime`.
417
+
418
+ ---
419
+
420
+ ## ๐Ÿค Contributing
421
+
422
+ Issues and pull requests are welcome at [github.com/miralabs-tech/standargraph](https://github.com/miralabs-tech/standargraph). Run typecheck, tests, build and smoke test before opening a pull request.
423
+
424
+ ---
425
+
426
+ ## โค๏ธ Support
427
+
428
+ If StandarGraph helps you:
429
+
430
+ ๐Ÿ‘‰ [Star the repo](https://github.com/miralabs-tech/standargraph) ยท [Open an issue](https://github.com/miralabs-tech/standargraph/issues)
431
+
432
+ ---
433
+
434
+ ## ๐Ÿ“œ License
435
+
436
+ [MIT](./LICENSE) - Copyright (c) 2026 Wesley Cormier.
437
+
438
+ Third-party components keep their own licenses: see [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) and the texts in [licenses/](./licenses) (elkjs is EPL-2.0 OR GPL-3.0-or-later, resvg is MPL-2.0, Inter is SIL OFL 1.1).
@@ -0,0 +1,22 @@
1
+ # Third-party notices
2
+
3
+ Runtime dependencies and bundled assets, with the license each package declares.
4
+
5
+ | Component | Version | License |
6
+ | --- | --- | --- |
7
+ | elkjs | 0.12.1 | EPL-2.0 OR GPL-3.0-or-later (`licenses/EPL-2.0.txt`) |
8
+ | @sinclair/typebox | 0.34.52 | MIT |
9
+ | @resvg/resvg-wasm | 2.6.2 | MPL-2.0 (`licenses/MPL-2.0.txt`) |
10
+ | pdfkit | 0.20.2 | MIT |
11
+ | svg-to-pdfkit | 0.1.8 | MIT |
12
+ | sigma | 4.0.6 | MIT |
13
+ | graphology | 0.26.0 | MIT |
14
+ | graphology-utils (via sigma) | 2.5.2 | MIT |
15
+ | events (via sigma and graphology) | 3.3.0 | MIT |
16
+ | Inter (`assets/fonts/`) | โ€” | SIL OFL 1.1 (`assets/fonts/OFL.txt`) |
17
+
18
+ ## Where each component ends up
19
+
20
+ - The self-contained HTML pages written by the CLI embed sigma, graphology and their MIT dependencies in the WebGL page only (`--renderer webgl`, or `auto` above the node threshold), and Inter in every page. They never embed ELK: positions are computed by the CLI before the page is written, so the pages carry no ELK notice.
21
+ - `mount` (`@standarx/graph/html`) runs the layout of a document without positions in a Web Worker. The worker source is an inline bundle of the layout code and elkjs, shipped inside the `mount` module and loaded from a Blob URL. Applications that bundle `mount` therefore ship elkjs (EPL-2.0 OR GPL-3.0-or-later) in their own bundle and take on its notice, as they do with any use of `@standarx/graph/layout`.
22
+ - playwright-core 1.65.1 (Apache-2.0) is a development dependency of the benchmark in `bench/` and is not part of the published package.
Binary file
Binary file
@@ -0,0 +1,92 @@
1
+ Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
2
+
3
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
4
+ This license is copied below, and is also available with a FAQ at:
5
+ http://scripts.sil.org/OFL
6
+
7
+ -----------------------------------------------------------
8
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
9
+ -----------------------------------------------------------
10
+
11
+ PREAMBLE
12
+ The goals of the Open Font License (OFL) are to stimulate worldwide
13
+ development of collaborative font projects, to support the font creation
14
+ efforts of academic and linguistic communities, and to provide a free and
15
+ open framework in which fonts may be shared and improved in partnership
16
+ with others.
17
+
18
+ The OFL allows the licensed fonts to be used, studied, modified and
19
+ redistributed freely as long as they are not sold by themselves. The
20
+ fonts, including any derivative works, can be bundled, embedded,
21
+ redistributed and/or sold with any software provided that any reserved
22
+ names are not used by derivative works. The fonts and derivatives,
23
+ however, cannot be released under any other type of license. The
24
+ requirement for fonts to remain under this license does not apply
25
+ to any document created using the fonts or their derivatives.
26
+
27
+ DEFINITIONS
28
+ "Font Software" refers to the set of files released by the Copyright
29
+ Holder(s) under this license and clearly marked as such. This may
30
+ include source files, build scripts and documentation.
31
+
32
+ "Reserved Font Name" refers to any names specified as such after the
33
+ copyright statement(s).
34
+
35
+ "Original Version" refers to the collection of Font Software components as
36
+ distributed by the Copyright Holder(s).
37
+
38
+ "Modified Version" refers to any derivative made by adding to, deleting,
39
+ or substituting -- in part or in whole -- any of the components of the
40
+ Original Version, by changing formats or by porting the Font Software to a
41
+ new environment.
42
+
43
+ "Author" refers to any designer, engineer, programmer, technical
44
+ writer or other person who contributed to the Font Software.
45
+
46
+ PERMISSION AND CONDITIONS
47
+ Permission is hereby granted, free of charge, to any person obtaining
48
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
49
+ redistribute, and sell modified and unmodified copies of the Font
50
+ Software, subject to the following conditions:
51
+
52
+ 1) Neither the Font Software nor any of its individual components,
53
+ in Original or Modified Versions, may be sold by itself.
54
+
55
+ 2) Original or Modified Versions of the Font Software may be bundled,
56
+ redistributed and/or sold with any software, provided that each copy
57
+ contains the above copyright notice and this license. These can be
58
+ included either as stand-alone text files, human-readable headers or
59
+ in the appropriate machine-readable metadata fields within text or
60
+ binary files as long as those fields can be easily viewed by the user.
61
+
62
+ 3) No Modified Version of the Font Software may use the Reserved Font
63
+ Name(s) unless explicit written permission is granted by the corresponding
64
+ Copyright Holder. This restriction only applies to the primary font name as
65
+ presented to the users.
66
+
67
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
68
+ Software shall not be used to promote, endorse or advertise any
69
+ Modified Version, except to acknowledge the contribution(s) of the
70
+ Copyright Holder(s) and the Author(s) or with their explicit written
71
+ permission.
72
+
73
+ 5) The Font Software, modified or unmodified, in part or in whole,
74
+ must be distributed entirely under this license, and must not be
75
+ distributed under any other license. The requirement for fonts to
76
+ remain under this license does not apply to any document created
77
+ using the Font Software.
78
+
79
+ TERMINATION
80
+ This license becomes null and void if any of the above conditions are
81
+ not met.
82
+
83
+ DISCLAIMER
84
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
85
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
86
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
87
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
88
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
89
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
90
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
91
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
92
+ OTHER DEALINGS IN THE FONT SOFTWARE.