@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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Wesley Cormier
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.fr.md ADDED
@@ -0,0 +1,438 @@
1
+ # StandarGraph
2
+
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
+ > "Diagrammes déclaratifs à partir de JSON (graphes, séquences, machines à états, entité-relation et arbres), rendus en SVG, HTML interactif, PNG et PDF, avec WebGL au-delà de 2000 nœuds de graphe."
6
+
7
+ 📖 [English](./README.md) · Français
8
+
9
+ [Démarrage rapide](#-démarrage-rapide) · [Installation](#-installation) · [Fonctionnalités](#-fonctionnalités) · [Types de diagrammes](#-types-de-diagrammes) · [Thèmes](./docs/theming.md) · [Limites](#-limites) · [Cœur headless](./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
+ Les deux images ci-dessus sont produites par la CLI (`examples/architecture.json` et `examples/protocol.json`). Chacune renvoie vers un visualiseur interactif autonome : téléchargez le fichier `.html` et ouvrez-le dans un navigateur.
16
+
17
+ **Démo en ligne** : le [playground](https://miralabs-tech.github.io/standargraph/) affiche la syntaxe texte ou le JSON pendant la frappe, hors ligne une fois chargé, et chaque exemple a une page interactive : [architecture](https://miralabs-tech.github.io/standargraph/examples/architecture.html), [protocol](https://miralabs-tech.github.io/standargraph/examples/protocol.html).
18
+
19
+ ---
20
+
21
+ ## 🧠 Qu'est-ce que StandarGraph ?
22
+
23
+ Vous décrivez un diagramme dans un document JSON (`version: 1`, `kind` parmi `"graph"`, `"sequence"`, `"state"`, `"er"` ou `"tree"`), et StandarGraph le met en page et le rend. Les nœuds, arêtes et groupes peuvent porter des métadonnées facultatives : provenance (source, confiance, outil), couverture et fraîcheur, pour qu'un diagramme produit par un outil ou un agent dise à quel point on peut s'y fier.
24
+
25
+ La mise en page et la vue (caméra, hit testing, culling, niveau de détail, survol, sélection, recherche) forment un cœur headless qui ne touche jamais au DOM. Des adaptateurs se posent dessus : un rendu SVG, une page HTML interactive, et un rendu WebGL basé sur [Sigma.js](https://www.sigmajs.org) pour les grands graphes.
26
+
27
+ Les sorties sont le SVG, une page HTML en un seul fichier qui fonctionne hors ligne (polices et runtime embarqués, aucun accès réseau), le PNG et le PDF. Le PNG et le PDF sont rendus sans navigateur.
28
+
29
+ **Statut : 1.1.0.**
30
+
31
+ ---
32
+
33
+ ## 🚀 Démarrage rapide
34
+
35
+ Un document de graphe minimal, `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 et graph.html à côté du fichier d'entrée
55
+ standargraph export graph.json --format svg,html,png,pdf --out out --theme dark
56
+ standargraph export graph.json --renderer webgl # force la page WebGL
57
+ standargraph export graph.json --markdown # affiche aussi un extrait Markdown d'aperçu
58
+ standargraph export graph.json --format mermaid # graph.mmd, pour le Markdown de GitHub (voir docs/mermaid.md)
59
+ standargraph layout graph.json # graph.positioned.json : chaque nœud reçoit sa position calculée
60
+ standargraph convert graph.json # graph.sg, le même document en syntaxe texte
61
+ standargraph convert graph.sg --to json --out out/graph.json
62
+ ```
63
+
64
+ Chaque commande lit du JSON ou la [syntaxe texte](#syntaxe-texte) : le format est détecté par le contenu, jamais par l'extension du fichier. `validate` sort avec le code 0 quand le document est valide, 1 avec une ligne `chemin: message` par erreur JSON (ou une ligne `fichier:ligne:col: message [code]` par erreur de texte) sinon, 2 quand le fichier n'est pas lisible. `layout` écrit toujours du JSON. `convert` écrit l'autre format que celui de l'entrée, sauf si `--to json|text` en décide autrement, et sort avec le code 2 et `Output would overwrite the input` quand la sortie est le fichier d'entrée.
65
+
66
+ | Option | Rôle |
67
+ | --- | --- |
68
+ | `--format <liste>` | Liste séparée par des virgules : `svg`, `html`, `png`, `pdf`, `mermaid` (défaut `svg,html`) ; `mermaid` écrit `<base>.mmd` et affiche ses avertissements sur stderr |
69
+ | `--out <dir>` | Dossier de sortie (défaut : le dossier du fichier d'entrée) |
70
+ | `--name <base>` | Nom de base des sorties (défaut : le nom du fichier d'entrée sans `.json` ni `.sg`) |
71
+ | `--theme <thème>` | `auto` (défaut), un nom de palette (`light`, `dark`, `nord`, `solarized-light`, `solarized-dark`, `high-contrast`) ou un fichier de thème `.json`, voir [docs/theming.md](./docs/theming.md) |
72
+ | `--no-palette` | Coupe la couleur automatique par `type` d'élément |
73
+ | `--scale <n>` | Facteur d'échelle du PNG (défaut 2) |
74
+ | `--renderer <nom>` | Rendu HTML : `auto`, `svg` ou `webgl` (défaut `auto`) |
75
+ | `--markdown` | Affiche `[![titre](base.svg)](base.html)`, un extrait Markdown qui lie l'aperçu SVG à la page HTML ; avec `mermaid` dans `--format`, un bloc de code `mermaid` suit |
76
+
77
+ ### JavaScript
78
+
79
+ Chaque sous-chemin est un point d'entrée distinct de `@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
+ Tous les formats en un appel, depuis `/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 est une chaîne, out.png et out.pdf sont des Uint8Array
102
+ ```
103
+
104
+ Du texte Mermaid pour le Markdown de GitHub, depuis `/mermaid` (`formats: ["mermaid"]` dans `exportDocument()` renvoie le même texte sous forme de chaîne, sans les avertissements) :
105
+
106
+ ```ts
107
+ import { toMermaid } from "@standarx/graph/mermaid";
108
+
109
+ const { text, warnings } = toMermaid(graphDocument);
110
+ ```
111
+
112
+ Monter un graphe interactif dans une page (`mount(container, document, { theme, title, renderer })`). Quand chaque nœud a une `position`, ELK est ignoré ; sinon la mise en page tourne dans un Web Worker et le thread principal reste libre. Plusieurs instances peuvent coexister sur une 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
+ Pipelines Markdown, avec le plugin remark (il transforme les blocs de code ` ```standargraph ` et ` ```sg ` contenant un document JSON ou la syntaxe texte en SVG en ligne, lié à une page HTML autonome quand `outDir` est défini) :
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
+ Le cœur headless, pour votre propre rendu (voir [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
+ Les fonctions d'éditeur de la syntaxe texte, sans dépendance à un serveur de langage (voir [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
+ ## 🧩 Types de diagrammes
155
+
156
+ Chaque document porte `version: 1` et un `kind`. Les fichiers de [examples](./examples) sont des documents complets pour chaque type.
157
+
158
+ ### `graph` et `sequence`
159
+
160
+ `graph` contient des `nodes`, des `edges` et des `groups` imbriqués ; `sequence` contient des `participants` et des `messages`. Voir le démarrage rapide plus haut, ainsi que `examples/architecture.json` et `examples/protocol.json`.
161
+
162
+ ### `state`
163
+
164
+ Des états, des pseudo-états facultatifs (`initial`, `final`, `choice`, `fork`, `join`, `history`), des états composites par `parent`, et des transitions avec `event`, `guard` et `action`. Extrait de `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
+ Des entités à attributs (`keys` : `pk`, `fk`, `uk` ; `nullable` ; `note`) et des relations dessinées avec des cardinalités en pattes de corbeau (`one`, `zero-or-one`, `one-or-more`, `zero-or-more`). Extrait de `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
+ Une liste plate de nœuds liés par `parent`, mise en page en arbre « tidy » (`"layout": "tree"`, par défaut, avec une `direction`) ou en mindmap à deux côtés autour de la racine (`"layout": "mindmap"`). Extrait de `examples/repo-tree.json` et `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
+ ### Formes
239
+
240
+ `shape` sur un nœud `graph` ou `tree` vaut `box` (par défaut), `rect`, `pill`, `diamond`, `circle`, `ellipse`, `hexagon`, `parallelogram`, `cylinder`, `document` ou `subroutine`. Les arêtes s'arrêtent sur le contour de la forme : un flowchart est donc un `graph` avec des formes (`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
+ Les formes sont dans le document ; les couleurs n'y sont jamais. Elles viennent du thème.
260
+
261
+ ### Syntaxe texte
262
+
263
+ Chaque type se laisse aussi écrire en texte brut, dans des fichiers nommés `.sg` par convention. Un graphe en forme à symboles :
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
+ Le même graphe en forme à mots, où `to`, `with`, `async`, `reply` et `via` remplacent les opérateurs et `do` ... `end` remplace les accolades :
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
+ Les deux formes se lisent comme le même document. `examples/` contient un jumeau `.sg` de chaque exemple JSON. Le sous-chemin `/text` exporte `parse`, `print`, `canonicalize`, `sniff` et `loadSource` ; une chaîne passée à `mount()` ou à `exportDocument()` passe par `loadSource`, et `standargraph convert` transforme un format en l'autre. Dans un Markdown, un bloc ` ```sg ` (ou ` ```standargraph `) contient l'un ou l'autre format :
294
+
295
+ ````md
296
+ ```sg
297
+ graph "Release flow"
298
+
299
+ build -> check
300
+ ```
301
+ ````
302
+
303
+ #### Coloration syntaxique
304
+
305
+ Le paquet livre une grammaire TextMate (`@standarx/graph/grammars/standargraph.tmLanguage.json`, scope `source.standargraph`), un `language-configuration.json` et `highlight(source)` dans le sous-chemin `/text`, qui renvoie des jetons typés avec les types de jetons sémantiques du LSP. La démo en ligne colore son éditeur avec `highlight()`. Une extension VS Code les consommera depuis son propre dépôt. Voir [docs/syntax-highlighting.md](./docs/syntax-highlighting.md) (en anglais).
306
+
307
+ ### Thèmes
308
+
309
+ Un thème est un ensemble de jetons de couleur plus des couleurs facultatives par `type` de nœud, donné par `--theme <fichier.json>` dans la CLI ou par l'option `theme` de l'API. Six palettes sont prêtes à l'emploi, en `theme: "nord"` ou `--theme nord` : `light`, `dark`, `nord`, `solarized-light`, `solarized-dark` et `high-contrast`, chacune avec un contraste d'au moins 4,5:1 pour son texte.
310
+
311
+ - Un élément typé sans couleur propre en reçoit une de la palette du thème, choisie par un hachage stable de son `type`. `palette: false` dans le thème, ou `--no-palette`, la coupe, et une entrée de `types` l'emporte toujours.
312
+ - Avec `"auto"` ou une paire `{ light, dark }`, la page interactive et `mount()` affichent dans la barre d'outils un bouton qui fait défiler `auto`, `light` et `dark`, gardé dans `localStorage`.
313
+ - La démo en ligne a un panneau de thème : une palette, les jetons, une couleur par type, et un `theme.json` à télécharger pour `--theme`.
314
+
315
+ Voir [docs/theming.md](./docs/theming.md) (en anglais).
316
+
317
+ ### GitHub Action
318
+
319
+ L'action composite à la racine du dépôt rend vos fichiers `.sg` avec la CLI publiée. Elle ne commite ni ne pousse jamais.
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
+ | Entrée | Défaut | Rôle |
330
+ | --- | --- | --- |
331
+ | `files` | `**/*.sg` | Fichiers à rendre |
332
+ | `formats` | `svg` | Formats d'export |
333
+ | `theme` | `light` | Thème du rendu |
334
+ | `out` | vide (à côté du source) | Dossier de sortie |
335
+ | `version` | la version du paquet de la ref de l'action | Version npm de `@standarx/graph` lancée |
336
+ | `mode` | `write` | `write` rend ; `check` rend puis échoue, en listant les fichiers, si une sortie diffère de l'arbre de travail ou manque |
337
+ | `cli-path` | vide | Chemin d'un `dist/cli.js` construit localement, utilisé à la place du paquet npm (CI de ce dépôt) |
338
+
339
+ [docs/diagrams-workflow.yml](./docs/diagrams-workflow.yml) est un workflow d'exemple qui rend à chaque push et commite le résultat avec de simples commandes `git`. Copiez-le dans `.github/workflows/diagrams.yml`.
340
+
341
+ ---
342
+
343
+ ## 📦 Installation
344
+
345
+ ```sh
346
+ npm install @standarx/graph
347
+ bun add @standarx/graph
348
+ ```
349
+
350
+ Node >= 20. La CLI est le binaire `standargraph`. Une fois le paquet installé, `npx standargraph` ou `bunx standargraph` la lance ; sans installation, nommez le paquet :
351
+
352
+ ```sh
353
+ npx @standarx/graph export graph.json
354
+ bunx @standarx/graph export graph.json
355
+ npm install -g @standarx/graph # puis : standargraph export graph.json
356
+ ```
357
+
358
+ ---
359
+
360
+ ## ✨ Fonctionnalités
361
+
362
+ - **Format v1** : documents JSON de cinq types, `graph` (nœuds, arêtes, groupes imbriqués, `position` fixe facultative), `sequence` (participants, messages), `state`, `er` et `tree` (voir [Types de diagrammes](#-types-de-diagrammes)), validés par un [JSON Schema](./schema/graph-document.v1.json) publié, avec un `validate()` qui renvoie une erreur par problème et son chemin.
363
+ - **Métadonnées** : provenance (`confirmed`, `inferred`, `unknown`), couverture et fraîcheur sur les documents, nœuds, arêtes et groupes ; les éléments à faible confiance sont dessinés atténués.
364
+ - **Mise en page** : layout ELK en couches pour les graphes, les groupes, les machines à états et les diagrammes entité-relation, layout dédié aux diagrammes de séquence, layout arbre ou mindmap pour les arbres, texte mesuré avec les métriques d'Inter embarquées pour que SVG et HTML s'accordent.
365
+ - **Formes** : 11 formes de nœud sur les nœuds `graph` et `tree`, dessinées en SVG et coupées au contour par les arêtes (voir [Formes](#formes)).
366
+ - **Thèmes** : six palettes nommées, une couleur automatique par `type` de nœud, un sélecteur clair, sombre et auto, des jetons de couleur et des couleurs par `type` de nœud, un seul objet pour le SVG, le HTML, le PNG et le PDF, option `--theme <nom|fichier.json>` (voir [docs/theming.md](./docs/theming.md), en anglais).
367
+ - **Rendus** : SVG, HTML interactif (déplacement, zoom, survol, sélection, recherche, panneau, clavier, thèmes clair et sombre), et WebGL via Sigma.js.
368
+ - **WebGL au-delà de 2000 nœuds** : l'export HTML d'un `graph` bascule automatiquement en WebGL au-delà de 2000 nœuds (`--renderer` force le choix). Sur la porte v1, 10 000 nœuds en WebGL tiennent une médiane de 303 FPS (p5 285,7) plafonnée par le rafraîchissement de l'écran, et une médiane de 58,1 FPS (p5 54,3) sans plafond, sur un Intel Core i7-14700KF avec une NVIDIA GeForce RTX 4070 Ti SUPER dans Microsoft Edge 157. Détails dans [docs/bench.md](./docs/bench.md).
369
+ - **HTML hors ligne en un fichier** : polices et runtime embarqués, rien n'est téléchargé.
370
+ - **Export** : SVG, HTML, PNG et PDF depuis la CLI ou `exportDocument()`, PNG et PDF sans navigateur (resvg WASM et PDFKit).
371
+ - **Cœur headless** : contrôleur de vue avec caméra, hit testing, culling, niveau de détail et surbrillance, utilisable dans Node, Bun, un worker ou un navigateur.
372
+ - **Syntaxe texte** : chaque type en texte brut (`.sg`), en forme à symboles ou à mots, avec des erreurs en ligne et colonne, `print()` pour revenir au texte et `standargraph convert` entre les deux formats (voir [Syntaxe texte](#syntaxe-texte)).
373
+ - **Export Mermaid** : chaque type en texte Mermaid avec `toMermaid()` ou `--format mermaid`, les pertes étant signalées par des avertissements (voir [docs/mermaid.md](./docs/mermaid.md), en anglais).
374
+ - **Intégration** : `mount()` pour les applications, avec un worker de mise en page à la demande, et un plugin remark pour le Markdown.
375
+
376
+ ---
377
+
378
+ ## 🚧 Limites
379
+
380
+ - **La mise en page des grands graphes est lente.** ELK met en page 10 000 nœuds en environ 44 s (5 000 nœuds : 13 s, 2 000 : 3,7 s ; voir [docs/bench.md](./docs/bench.md)). Le rendu n'est pas le goulot. Une mise en page plus rapide pour les grands graphes arrive bientôt.
381
+ - **Précalculez les positions des grands graphes.** Dès que chaque nœud a une `position`, ELK est ignoré par `layout()`, `mount()` et les exports. `standargraph export` calcule la mise en page une fois et la page HTML qu'il écrit porte le résultat : l'ouvrir ne remet jamais rien en page. Pour garder les positions dans vos documents, lancez `standargraph layout graph.json` (ou `--out <fichier>`) : la commande écrit le même document avec une `position` sur chaque nœud, qui s'affiche ensuite sans ELK.
382
+
383
+ - La sortie du plugin remark ne s'affiche pas sur GitHub. Dans un README, utilisez le SVG écrit par la CLI, lié à sa page HTML (`--markdown` affiche l'extrait).
384
+ - Le rendu WebGL ne dessine ni les légendes de type de nœud, ni les libellés d'arêtes, ni les pointes de flèche, et les diagrammes `sequence`, `state`, `er` et `tree` sont toujours dessinés en SVG.
385
+
386
+ ---
387
+
388
+ ## 📚 Documentation
389
+
390
+ - [Cœur headless et adaptateurs](./docs/headless.md) (anglais)
391
+ - [Thèmes](./docs/theming.md) (anglais)
392
+ - [Coloration syntaxique de `.sg`](./docs/syntax-highlighting.md) (anglais)
393
+ - [Service de langage pour `.sg`](./docs/language-service.md) (anglais)
394
+ - [Export Mermaid](./docs/mermaid.md) (anglais)
395
+ - [Benchmark et temps de mise en page](./docs/bench.md) (anglais)
396
+ - [JSON Schema du format v1](./schema/graph-document.v1.json)
397
+ - [Exemples](./examples)
398
+ - [Changelog](./CHANGELOG.md) (anglais)
399
+
400
+ ---
401
+
402
+ ## 🛠️ Build et tests
403
+
404
+ ```sh
405
+ bun install
406
+ bun run typecheck
407
+ bun test
408
+ bun run build
409
+ bun run smoke # le paquet empaqueté, sous Node
410
+ STANDARGRAPH_BROWSER_CHANNEL=msedge bun run test:browser # Playwright, indiquez le canal d'un navigateur installé
411
+ bun run bench # benchmark (Microsoft Edge, avec fenêtre)
412
+ bun run runtime # régénère les runtimes HTML et WebGL embarqués
413
+ bun run site # construit le site GitHub Pages dans site-dist/
414
+ ```
415
+
416
+ La CI épingle bun 1.4.2 pour que les bundles générés correspondent à ceux versionnés ; utilisez la même version avant de lancer `bun run runtime`.
417
+
418
+ ---
419
+
420
+ ## 🤝 Contribuer
421
+
422
+ Les issues et pull requests sont les bienvenues sur [github.com/miralabs-tech/standargraph](https://github.com/miralabs-tech/standargraph). Lancez typecheck, tests, build et smoke test avant d'ouvrir une pull request.
423
+
424
+ ---
425
+
426
+ ## ❤️ Soutien
427
+
428
+ Si StandarGraph vous aide :
429
+
430
+ 👉 [Mettre une étoile](https://github.com/miralabs-tech/standargraph) · [Ouvrir une issue](https://github.com/miralabs-tech/standargraph/issues)
431
+
432
+ ---
433
+
434
+ ## 📜 Licence
435
+
436
+ [MIT](./LICENSE) - Copyright (c) 2026 Wesley Cormier.
437
+
438
+ Les composants tiers gardent leurs propres licences : voir [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) et les textes dans [licenses/](./licenses) (elkjs est EPL-2.0 OU GPL-3.0-or-later, resvg est MPL-2.0, Inter est SIL OFL 1.1).