@r0kshan/cairn 1.0.0-RC12 → 1.0.0-RC14

package/README.md

@@ -17,6 +17,7 @@ Cairn is an [Elkjs (Eclipse Layout Kernel)](https://github.com/kieler/elkjs) bas
 - [Preview](#preview)
 - [Installation](#installation)
 - [Commands](#commands)
+- [License](#license)
 - [More](#more)
 
 ## Why cairn?
@@ -32,6 +33,7 @@ Furthermore, complexe software architecture with many flows and component genera
 | **Spacial optimization** | Cairn aims to optimize space as much as possible (Still working on improving this functionnality) |
 | **Typed diagrams with validation.** | Each view defines its element kinds and rules; `cairn validate` reports syntax, schema, and completeness issues as source-located, coded diagnostics, with a JSON mode for CI. |
 | **Flow matrix.** | `cairn matrix` exports the flow matrix as CSV, Markdown, or SVG — from any view, with the columns that view can fill. In infrastructure it splits protocol from port and annotates endpoints that sit in a network zone; headers localise via `style { lang: fr }`. The same table is available to embedders through `compile(source, { matrix: true })`. |
+| **Author-controlled positioning.** | Layout is automatic, with three opt-in overrides for when it gets a diagram wrong: `order: 2` sequences a top-level element along the disposition's own reading direction (left to right in `wide`, top to bottom in `tall`) and sorts siblings inside a container, `A.right -> B.left` pins which side of an element a flow leaves and arrives on, and the arrow glyph carries the line style (`->` solid, `-->` dashed, `..>` dotted). |
 | **Enterprise-view extras.** | Business objects on flows, an auto-generated legend, and a numbered-flow table via `flow-text: numbered`. |
 | **French or English output.** | `style { lang: fr }` localizes band titles, legend, and matrix headers while keeping keywords English for portable sources (open to adding other languages if you find this usefull) |
 | **In-built themes and customizable colours** | Whether using the default or a chosen in-built theme, element colours can be overriden  for all elements of a given kind in the `style` block |
@@ -56,15 +58,10 @@ As a result here's a comparaison of the same diagram done with D2 (ELK Layout) v
     </tr>
     <tr>
       <td>I encountered overlapping issues for which I couldn't find a workaround</td>
-      <td>The overlapping issues have been addressed. A caveat remains: the long-distance arrow can affect readability (still working on improvements)</td>
+      <td>The overlapping labels have been addressed.</td>
     </tr>
     </table>
 
-## Known limitations I'm working on
-
-* While Cairn ensures 0 label overlap, flows on large diagrams still take a longer than neccessary route to the target element - issue [#26](https://github.com/R0kshan/cairn/issues/26) created to adress this
-* At the moment Cairn doesn't give the user the possibility to control positioning - issue [#8](https://github.com/R0kshan/cairn/issues/8) created to adress this
-
 ## Usage
 
 Either use the cli or the [ playground](https://cairn-psi-five.vercel.app/).
@@ -87,6 +84,25 @@ Every image below is rendered by cairn CLI from a `.cairn` source in [`examples/
 <p align="center"><img src="examples/application-medium.svg" alt="Medium application view" width="760"></p>
 <p align="center"><img src="examples/application-large.svg" alt="Large application view" width="760"></p>
 
+#### Technology logos
+
+```cairn
+application STOREFRONT "Storefront" { logo: nextdotjs
+  module WEB "Web client" { logo: react }
+}
+queue EVENTS "Order events" { logo: apachekafka }
+datastore ORDER_DB "Order store" { logo: postgresql }
+module BILLING "Billing" { logo: "./logos/acme.svg" }
+```
+
+<p align="center"><img src="examples/application-tech-stack.svg" alt="Application view with technology logos" width="760"></p>
+
+Six of the 37 built-in logos keep their own licence rather than simple-icons'
+CC0-1.0. A diagram that draws one embeds that artwork, so the SVG carries an
+attribution comment naming the mark, its source and its licence — keep it in
+the file, and check that an SVG optimiser is not set to strip comments. The
+other 31 add nothing. See [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).
+
 ### Infrastructure view diagram examples from small to large
 
 <p align="center"><img src="examples/infrastructure-small.svg" alt="Small infrastructure view" width="760"></p>
@@ -103,7 +119,7 @@ Colours are resolved at three levels — most specific wins. From lowest to high
 
 1. **Theme defaults** — per-kind colours defined by the selected theme (fill, stroke, text for each element kind).
 2. **Diagram-level per-kind overrides** — override colours for all elements of a given kind in the `style` block:
-   ```
+   ```cairn
    style {
      fill actor-group: #eef4fb
      stroke actor-group: #7a9cc4 dashed
@@ -112,12 +128,12 @@ Colours are resolved at three levels — most specific wins. From lowest to high
    }
    ```
 3. **Inline per-element styles** — override colour for a single element:
-   ```
+   ```cairn
    block API "API gateway" { style { fill: #e8f5e9  stroke: #2e7d32  text: #1b5e20 } }
    ```
 
 Flows can also be coloured inline:
-```
+```cairn
 COM_CTR -> OBS : "Alerts…" { label: above  stroke: dashed #a33  text: #a33 }
 ```
 
@@ -125,11 +141,89 @@ See [`examples/colors-custom.cairn`](examples/colors-custom.cairn) for a full ex
 
 <p align="center"><img src="examples/colors-custom.svg" alt="Custom colours" width="620"></p>
 
+### Positioning and flow line styles
+
+**Line style** — carried by the arrow glyph:
+
+```cairn
+TRIAGE -> TASKS (MQ, JSON)                 # solid — the default
+SCORING --> REINSURER (SFTP, CSV)          # dashed
+TRIAGE ..> REINSURER (API_REST, JSON)      # dotted
+```
+
+**Attachment sides** — pin either endpoint, or both, with `left`, `right`,
+`top` or `bottom`:
+
+```cairn
+FORM.right -> TRIAGE.left (API_REST, JSON)   # both ends pinned
+SCORING -> TASKS.right (MQ, JSON)            # only the arrival pinned
+SCORING.top -> TRIAGE.top (API_REST, JSON)   # a backward flow, pinned both ends
+```
+
+<p align="center"><img src="examples/positioning-sides.svg" alt="Flow attachment sides" width="760"></p>
+
+**Element ordering** — `order:` is a statement in the element's own body, not a
+`style` entry. Lower comes first along the disposition's reading direction: left
+to right in `wide`/`slide`, top to bottom in `tall`/`page`. From
+[`examples/placement/reading-order.cairn`](examples/placement/reading-order.cairn):
+
+```cairn
+application BACKEND_L1 "Line 1 backend" {
+  order: 1
+  module MSG_L1 "Messaging\nhandler"
+}
+application BACKEND_L2 "Line 2 backend" {
+  order: 2
+  module MSG_L2 "Messaging\nhandler"
+}
+```
+
+<p align="center"><img src="examples/placement/reading-order.svg" alt="Top-level elements sequenced by order:" width="620"></p>
+
+Inside a container the axis flips: `order:` sorts the siblings sharing a layer —
+top to bottom in `wide`, left to right in `tall`. From
+[`examples/positioning.cairn`](examples/positioning.cairn):
+
+```cairn
+actor-group STAFF "Payment actors" {
+  actor OPERATOR "Payment operator" { order: 1 }
+  actor AUDITOR "Compliance auditor" { order: 2 }
+}
+```
+
+<p align="center"><img src="examples/positioning.svg" alt="Element ordering, pinned sides and arrow glyphs" width="760"></p>
+
+More examples: [`examples/placement/`](examples/placement/) shows one shape four
+ways (`baseline.cairn`, `sides.cairn`, `reading-order.cairn`,
+`flow-label.cairn`), and [`examples/dispositions/`](examples/dispositions/) ships
+the attachment-sides file as `wide`, `tall`, `slide` and `page` variants.
+
+**Label position** — this one *is* style, so it lives in the `style` block and
+resolves at the usual three levels (view default, diagram, inline per flow). From
+[`examples/placement/flow-label.cairn`](examples/placement/flow-label.cairn):
+
+```cairn
+style {
+  flow-label: above     # on-line (default) | above | below
+}
+
+AGENT  -> RECEIVE : "File a claim"                            # above, from the style block
+ASSIGN -> SETTLE  : "Request settlement" { label: below }     # overridden per flow
+TRACE  -> STORE   : "Archive the trace" { label: on-line }    # back to the default
+```
+
+<p align="center"><img src="examples/placement/flow-label.svg" alt="Flow label positions" width="760"></p>
+
+`on-line` centres the text on the run behind a halo; `above`/`below` lift it clear
+by a fixed offset first. Either way the label is settled afterwards, so the
+zero-overlap gate holds. Every other diagram in this README shows the `on-line`
+default.
+
 ### Dispositions
 
 Same diagram different disposition : 
-- [Slide disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBzbGlkZSB9CgphY3Rvci1ncm91cCBVU0VSUyAiVXNlcnMiIHsKICBhY3RvciBQQVRJRU5UICJQYXRpZW50Igp9CgphY3Rvci1ncm91cCBTVEFGRiAiU3RhZmYiIHsKICBhY3RvciBTRUNSRVRBUlkgIk1lZGljYWwgc2VjcmV0YXJ5Igp9CgpzeXN0ZW0gQk9PS0lORyAiQXBwb2ludG1lbnQgYm9va2luZyBzeXN0ZW0iIHsKICBsYXllciBGUk9OVCAiUHJlc2VudGF0aW9uIGxheWVyIiB7CiAgICBibG9jayBQT1JUQUwgIkJvb2tpbmdcbnBvcnRhbCIKICB9CiAgbGF5ZXIgQlVTSU5FU1MgIkJ1c2luZXNzIGxheWVyIiB7CiAgICBibG9jayBTQ0hFRFVMRVIgIlNsb3Rcbm1hbmFnZW1lbnQiCiAgICBibG9jayBOT1RJRiAiTm90aWZpY2F0aW9ucyIKICB9Cn0KCmV4dGVybmFsIEVYVCAiRXh0ZXJuYWwgc3lzdGVtcyIgewogIGJsb2NrIFNNUyAiU01TIGdhdGV3YXkiCn0KCiMgLS0tLSBidXNpbmVzcyBvYmplY3RzIC0tLS0KYnVzaW5lc3Mtb2JqZWN0IEJPX0FQUFQgIkFwcG9pbnRtZW50IiAic2xvdCBib29rZWQgYnkgYSBwYXRpZW50IHdpdGggYSBwcmFjdGl0aW9uZXIiCmJ1c2luZXNzLW9iamVjdCBCT19TTE9UICJTbG90IiAidGltZSB3aW5kb3cgb3BlbiBmb3IgYm9va2luZyIKClBBVElFTlQgLT4gUE9SVEFMIDogIlNlYXJjaCBhIHNsb3RcbmFuZCBib29rIiBbQk9fU0xPVF0KUE9SVEFMIC0+IFNDSEVEVUxFUiA6ICJCb29raW5nIHJlcXVlc3QiIFtCT19BUFBUXQpTQ0hFRFVMRVIgLT4gTk9USUYgOiAiQXBwb2ludG1lbnQgY29uZmlybWVkIiBbQk9fQVBQVF0KTk9USUYgLT4gU01TIDogIlNlbmQgU01TIHJlbWluZGVyIgpTRUNSRVRBUlkgLT4gU0NIRURVTEVSIDogIk9wZW4gLyBibG9ja1xuc2xvdHMiIFtCT19TTE9UXQpTQ0hFRFVMRVIgLT4gUEFUSUVOVCA6ICJBcHBvaW50bWVudFxuY29uZmlybWF0aW9uIiBbQk9fQVBQVF0KCmxlZ2VuZCB7CiAgbm90ZSAiSGVhbHRoIGRhdGEgaXMgc3RvcmVkIG9uIGNlcnRpZmllZCBoZWFsdGgtZGF0YS1ob3N0aW5nIGluZnJhc3RydWN0dXJlIgp9Cg==)
-- [Page disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBwYWdlIH0KCmFjdG9yLWdyb3VwIFVTRVJTICJVc2VycyIgewogIGFjdG9yIFBBVElFTlQgIlBhdGllbnQiCn0KCmFjdG9yLWdyb3VwIFNUQUZGICJTdGFmZiIgewogIGFjdG9yIFNFQ1JFVEFSWSAiTWVkaWNhbCBzZWNyZXRhcnkiCn0KCnN5c3RlbSBCT09LSU5HICJBcHBvaW50bWVudCBib29raW5nIHN5c3RlbSIgewogIGxheWVyIEZST05UICJQcmVzZW50YXRpb24gbGF5ZXIiIHsKICAgIGJsb2NrIFBPUlRBTCAiQm9va2luZ1xucG9ydGFsIgogIH0KICBsYXllciBCVVNJTkVTUyAiQnVzaW5lc3MgbGF5ZXIiIHsKICAgIGJsb2NrIFNDSEVEVUxFUiAiU2xvdFxubWFuYWdlbWVudCIKICAgIGJsb2NrIE5PVElGICJOb3RpZmljYXRpb25zIgogIH0KfQoKZXh0ZXJuYWwgRVhUICJFeHRlcm5hbCBzeXN0ZW1zIiB7CiAgYmxvY2sgU01TICJTTVMgZ2F0ZXdheSIKfQoKIyAtLS0tIGJ1c2luZXNzIG9iamVjdHMgLS0tLQpidXNpbmVzcy1vYmplY3QgQk9fQVBQVCAiQXBwb2ludG1lbnQiICJzbG90IGJvb2tlZCBieSBhIHBhdGllbnQgd2l0aCBhIHByYWN0aXRpb25lciIKYnVzaW5lc3Mtb2JqZWN0IEJPX1NMT1QgIlNsb3QiICJ0aW1lIHdpbmRvdyBvcGVuIGZvciBib29raW5nIgoKUEFUSUVOVCAtPiBQT1JUQUwgOiAiU2VhcmNoIGEgc2xvdFxuYW5kIGJvb2siIFtCT19TTE9UXQpQT1JUQUwgLT4gU0NIRURVTEVSIDogIkJvb2tpbmcgcmVxdWVzdCIgW0JPX0FQUFRdClNDSEVEVUxFUiAtPiBOT1RJRiA6ICJBcHBvaW50bWVudCBjb25maXJtZWQiIFtCT19BUFBUXQpOT1RJRiAtPiBTTVMgOiAiU2VuZCBTTVMgcmVtaW5kZXIiClNFQ1JFVEFSWSAtPiBTQ0hFRFVMRVIgOiAiT3BlbiAvIGJsb2NrXG5zbG90cyIgW0JPX1NMT1RdClNDSEVEVUxFUiAtPiBQQVRJRU5UIDogIkFwcG9pbnRtZW50XG5jb25maXJtYXRpb24iIFtCT19BUFBUXQoKbGVnZW5kIHsKICBub3RlICJIZWFsdGggZGF0YSBpcyBzdG9yZWQgb24gY2VydGlmaWVkIGhlYWx0aC1kYXRhLWhvc3RpbmcgaW5mcmFzdHJ1Y3R1cmUiCn0K)
+- [Slide disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBzbGlkZSB9CgphY3Rvci1ncm91cCBVU0VSUyAiVXNlcnMiIHsKICBhY3RvciBQQVRJRU5UICJQYXRpZW50Igp9CgphY3Rvci1ncm91cCBTVEFGRiAiU3RhZmYiIHsKICBhY3RvciBTRUNSRVRBUlkgIk1lZGljYWwgc2VjcmV0YXJ5Igp9CgpzeXN0ZW0gQk9PS0lORyAiQXBwb2ludG1lbnQgYm9va2luZyBzeXN0ZW0iIHsKICBsYXllciBGUk9OVCAiQm9va2luZyBjaGFubmVscyIgewogICAgYmxvY2sgUE9SVEFMICJCb29raW5nXG5wb3J0YWwiCiAgfQogIGxheWVyIEJVU0lORVNTICJBcHBvaW50bWVudCBtYW5hZ2VtZW50IiB7CiAgICBibG9jayBTQ0hFRFVMRVIgIlNsb3Rcbm1hbmFnZW1lbnQiCiAgICBibG9jayBOT1RJRiAiTm90aWZpY2F0aW9ucyIKICB9Cn0KCmV4dGVybmFsIEVYVCAiRXh0ZXJuYWwgc3lzdGVtcyIgewogIGJsb2NrIFNNUyAiU01TIGdhdGV3YXkiCn0KCiMgLS0tLSBidXNpbmVzcyBvYmplY3RzIC0tLS0KYnVzaW5lc3Mtb2JqZWN0IEJPX0FQUFQgIkFwcG9pbnRtZW50IiAic2xvdCBib29rZWQgYnkgYSBwYXRpZW50IHdpdGggYSBwcmFjdGl0aW9uZXIiCmJ1c2luZXNzLW9iamVjdCBCT19TTE9UICJTbG90IiAidGltZSB3aW5kb3cgb3BlbiBmb3IgYm9va2luZyIKClBBVElFTlQgLT4gUE9SVEFMIDogIlNlYXJjaCBhIHNsb3RcbmFuZCBib29rIiBbQk9fU0xPVF0KUE9SVEFMIC0+IFNDSEVEVUxFUiA6ICJCb29raW5nIHJlcXVlc3QiIFtCT19BUFBUXQpTQ0hFRFVMRVIgLT4gTk9USUYgOiAiQXBwb2ludG1lbnQgY29uZmlybWVkIiBbQk9fQVBQVF0KTk9USUYgLT4gU01TIDogIlNlbmQgU01TIHJlbWluZGVyIgpTRUNSRVRBUlkgLT4gU0NIRURVTEVSIDogIk9wZW4gLyBibG9ja1xuc2xvdHMiIFtCT19TTE9UXQpTQ0hFRFVMRVIgLT4gUEFUSUVOVCA6ICJBcHBvaW50bWVudFxuY29uZmlybWF0aW9uIiBbQk9fQVBQVF0KCmxlZ2VuZCB7CiAgbm90ZSAiSGVhbHRoIGRhdGEgaXMgc3RvcmVkIG9uIGNlcnRpZmllZCBoZWFsdGgtZGF0YS1ob3N0aW5nIGluZnJhc3RydWN0dXJlIgp9Cg==)
+- [Page disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBwYWdlIH0KCmFjdG9yLWdyb3VwIFVTRVJTICJVc2VycyIgewogIGFjdG9yIFBBVElFTlQgIlBhdGllbnQiCn0KCmFjdG9yLWdyb3VwIFNUQUZGICJTdGFmZiIgewogIGFjdG9yIFNFQ1JFVEFSWSAiTWVkaWNhbCBzZWNyZXRhcnkiCn0KCnN5c3RlbSBCT09LSU5HICJBcHBvaW50bWVudCBib29raW5nIHN5c3RlbSIgewogIGxheWVyIEZST05UICJCb29raW5nIGNoYW5uZWxzIiB7CiAgICBibG9jayBQT1JUQUwgIkJvb2tpbmdcbnBvcnRhbCIKICB9CiAgbGF5ZXIgQlVTSU5FU1MgIkFwcG9pbnRtZW50IG1hbmFnZW1lbnQiIHsKICAgIGJsb2NrIFNDSEVEVUxFUiAiU2xvdFxubWFuYWdlbWVudCIKICAgIGJsb2NrIE5PVElGICJOb3RpZmljYXRpb25zIgogIH0KfQoKZXh0ZXJuYWwgRVhUICJFeHRlcm5hbCBzeXN0ZW1zIiB7CiAgYmxvY2sgU01TICJTTVMgZ2F0ZXdheSIKfQoKIyAtLS0tIGJ1c2luZXNzIG9iamVjdHMgLS0tLQpidXNpbmVzcy1vYmplY3QgQk9fQVBQVCAiQXBwb2ludG1lbnQiICJzbG90IGJvb2tlZCBieSBhIHBhdGllbnQgd2l0aCBhIHByYWN0aXRpb25lciIKYnVzaW5lc3Mtb2JqZWN0IEJPX1NMT1QgIlNsb3QiICJ0aW1lIHdpbmRvdyBvcGVuIGZvciBib29raW5nIgoKUEFUSUVOVCAtPiBQT1JUQUwgOiAiU2VhcmNoIGEgc2xvdFxuYW5kIGJvb2siIFtCT19TTE9UXQpQT1JUQUwgLT4gU0NIRURVTEVSIDogIkJvb2tpbmcgcmVxdWVzdCIgW0JPX0FQUFRdClNDSEVEVUxFUiAtPiBOT1RJRiA6ICJBcHBvaW50bWVudCBjb25maXJtZWQiIFtCT19BUFBUXQpOT1RJRiAtPiBTTVMgOiAiU2VuZCBTTVMgcmVtaW5kZXIiClNFQ1JFVEFSWSAtPiBTQ0hFRFVMRVIgOiAiT3BlbiAvIGJsb2NrXG5zbG90cyIgW0JPX1NMT1RdClNDSEVEVUxFUiAtPiBQQVRJRU5UIDogIkFwcG9pbnRtZW50XG5jb25maXJtYXRpb24iIFtCT19BUFBUXQoKbGVnZW5kIHsKICBub3RlICJIZWFsdGggZGF0YSBpcyBzdG9yZWQgb24gY2VydGlmaWVkIGhlYWx0aC1kYXRhLWhvc3RpbmcgaW5mcmFzdHJ1Y3R1cmUiCn0K)
 
 
 ### Numbered flows
@@ -160,6 +254,31 @@ Cairn comes with a collection of built-in themes. Choose the one that best fits
   </tr>
 </table>
 
+Pick one from the command line with `--theme`, without editing the diagram:
+
+```sh
+cairn build my-system.cairn --theme nord
+cairn themes                                     # list the built-in names
+```
+
+#### Your own colours
+
+`--theme` also takes a JSON file. It **extends a built-in and overrides only
+what it names**, so a usable theme is a few lines rather than fifty colours:
+
+```json
+{
+  "extends": "dark",
+  "dark": true,
+  "pal": { "bg": "#0d1117", "nStroke": "#58a6ff" },
+  "accentColors": { "blue": "#58a6ff", "blueF": "#0d2136" }
+}
+```
+
+```sh
+cairn build my-system.cairn --theme ./my-theme.json
+```
+
 ## Installation
 
 Prebuilt, self-contained binaries are published on every `v*` tag (no runtime needed). Pick your platform:
@@ -217,6 +336,7 @@ help: move this `block` inside a `layer`, `system` or `external`
 
 ```sh
 cairn build my-system.cairn -o my-system.svg     # -o optional; defaults to the same name, .svg
+cairn build my-system.cairn --theme nord         # or --theme ./my-theme.json
 ```
 
 On validation errors nothing is written and the exit code is 1; warnings are printed but do not block.
@@ -237,6 +357,21 @@ cairn watch my-system.cairn
 
 Rebuilds the SVG on save. On a compile error the SVG becomes an error panel (codes, lines, help), so an open preview never shows a stale diagram. Watch observes only the file it was launched on — run one per file. Pair it with an editor that auto-refreshes an open SVG.
 
+### List the built-in logos
+
+```sh
+cairn logos
+```
+
+```text
+37 built-in logos — use as `logo: <name>` on an element:
+
+  angular        apache         apachekafka    apachespark    django
+  ...
+```
+
+Anything else: point at a file — `logo: "./logos/name.svg"`.
+
 ### Explain a diagnostic
 
 ```sh
@@ -248,13 +383,42 @@ E0240 — The infrastructure view requires every flow to carry its protocol (and
 relevant): the flow matrix is the primary output of this view. Add `(HTTPS/443)` after the label.
 ```
 
-### Check your version
+### Check your version, and what it contains
 
 ```sh
 cairn version    # or --version / -v
+cairn version --licenses
 ```
 
-Released binaries (the ones from Homebrew, Scoop, or the GitHub Releases page) print the exact tag they were built from. Running from a clone via `npm run cairn` prints `package.json`'s version instead.
+Released binaries (the ones from Homebrew, Scoop, or the GitHub Releases page) print the exact tag they were built from. Running from a clone via `npm run cairn` prints `package.json`'s version instead. The bare form prints one line and nothing else, so it stays safe to parse in a script.
+
+`--licenses` adds the third-party notices for that exact build — elkjs under EPL-2.0, the Simple Icons artwork, and, for the released binaries only, the embedded Bun runtime and its LGPL-2.1 JavaScriptCore. It reads from inside the artifact, so it describes the copy you are running rather than whatever the repository says today.
+
+That output is a convenience, not the licence itself. The full texts are installed with cairn: `share/doc/cairn/` for the curl installer and Homebrew, the app directory for Scoop, the package root for npm. [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md) is the long form, with per-icon attribution and the LGPL relink offer.
+
+## License
+
+cairn is [Apache-2.0](LICENSE). Its shipped artifacts also *contain* third-party code Apache-2.0 does not cover: elkjs (EPL-2.0) inlined into every bundle and binary, a curated set of Simple Icons paths vendored into the logos, and — in the release binaries only — the Bun runtime, which statically links JavaScriptCore under the LGPL.
+
+Full texts live in [`licenses/`](licenses/), their provenance in [`licenses/README.md`](licenses/README.md), and the long form in [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).
+
+### What that means for you
+
+Find your row. Most people are in the first one, and owe nothing.
+
+| What you are doing | What you owe |
+|---|---|
+| **Sharing a diagram** | Nothing — unless it draws one of the six licensed logos below, and then cairn has already written the attribution into the SVG. Leave the comment in place. |
+| **Depending on `@r0kshan/cairn`** from npm | Nothing. You distribute no copy of cairn; `npm install` fetches it with its notices intact. |
+| **Bundling cairn** into your own artifact (webpack, Docker, Electron, single-file CLI) | Copy `LICENSE`, `THIRD-PARTY-NOTICES.md` and `licenses/` out of the installed package into your distribution. |
+| **Redistributing a cairn binary** | The same three files — and every installer has already put them on disk beside it (`share/doc/cairn`, the app directory, or the package root, by channel). |
+
+**Two things worth knowing:**
+
+- **6 of the 37 built-in logos** — `angular`, `apache`, `apachekafka`, `apachespark`, `javascript`, `openjdk` — keep their own licence instead of the project-wide CC0-1.0. The other 31 ask for nothing.
+- **Converting a diagram to PNG, or pasting it into a slide deck, drops the attribution comment.** The artwork is still there, so the attribution has to go somewhere you control: a caption, a credits slide, or `licenses/` shipped alongside. This is the one case cairn cannot handle for you.
+
+Diagrams you produce are yours — cairn claims nothing in them. The brands drawn by the built-in logos remain their owners' trademarks.
 
 ## More
 
@@ -263,3 +427,4 @@ Released binaries (the ones from Homebrew, Scoop, or the GitHub Releases page) p
 - [`ARCHITECTURE.md`](documentation/ARCHITECTURE.md) — how the pipeline fits together, for contributors.
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to open a PR, and the gates it must pass.
 - [`documentation/`](documentation/) — architecture, invariants, DSL and internals.
+- [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md) — third-party licence notices, with per-icon attribution.

package/THIRD-PARTY-NOTICES.md

@@ -4,8 +4,154 @@ cairn is Apache-2.0 (`LICENSE`). Its shipped artifacts — the npm tarball's
 `bin/cairn.mjs`, the release binaries, the playground bundles — additionally
 *contain* third-party code, so this notice travels with them.
 
-Build-only tools (esbuild, Bun, biome, typescript) are not listed: nothing of
-theirs is distributed.
+Build-only tools (esbuild, biome, typescript) are not listed: nothing of theirs
+is distributed. Bun is a different case — `bun build --compile` embeds its
+runtime in every release binary — and has its own section below.
+
+Where each artifact carries this notice:
+
+| Artifact | How the notices travel |
+|---|---|
+| npm tarball | `files` ships `LICENSE`, this file and `licenses/`; both bundles also carry a `/*!` banner naming what they inline |
+| release binaries | the texts ship as a `cairn-<version>-licenses.tar.gz` release asset, unpacked into `share/doc/cairn` by `packaging/install.sh`, into the formula's `doc` by the Homebrew tap, and into the app directory by the Scoop manifest — that is what carries the licences. `install.sh` is fail-closed in its own code: it verifies the bundle against the release checksums and installs nothing at all, binary included, if it cannot. Homebrew and Scoop are given the same checksums by `scripts/render-packaging.mjs` and abort on a mismatch through their own resource verification rather than through anything cairn does. `cairn version --licenses` additionally prints the short notice from inside the binary, so a copy separated from its directory still says what it contains |
+| playground | `LICENSE`, this file and `licenses/` are served from the deployed site beside the bundle and linked from the page header; the bundle carries the same banner |
+
+## What this means for you
+
+The rest of this file records what cairn owes and to whom. This section is the
+other direction: what, if anything, *you* take on. It is a plain reading of the
+licence texts in `licenses/`, not legal advice, and the summary below is not a
+substitute for the terms themselves.
+
+Three situations, in increasing order of what they ask of you.
+
+### You generate diagrams with cairn
+
+Nothing. Using a tool is not redistributing it, and every obligation in this
+file attaches to distributing copies. cairn claims nothing in the diagrams you
+produce.
+
+One thing worth knowing, because it is the only case where a third party's
+terms reach your output: **a rendered SVG embeds the icon artwork it draws.**
+31 of the 37 built-in logos are CC0-1.0, which waives copyright and asks for
+nothing. Six carry their own terms and ask for attribution:
+
+| Logo | Licence |
+|---|---|
+| `angular` | CC-BY-4.0 |
+| `apache`, `apachekafka`, `apachespark` | Apache-2.0 |
+| `javascript` | MIT |
+| `openjdk` | BSD-3-Clause |
+
+A diagram that uses none of those six carries no third-party artwork with
+conditions attached, and cairn writes nothing extra into it. One that does is a
+redistribution of that artwork, so the SVG carries its own attribution: an XML
+comment after the opening `<svg>` tag naming each licensed mark it drew, the
+artwork's source, the rights-holder's copyright line where one is published,
+and a URL for the licence text. Only the marks actually painted are named.
+
+That comment also records that the artwork is **modified**, because it is:
+simple-icons redrew each brand mark as a single monochrome path before cairn
+vendored it, and cairn paints that path in the node's colour rather than the
+mark's own. CC-BY-4.0 §3(a)(1)(B) asks that a modification be indicated and
+previous ones retained; Apache-2.0 §4(b) asks that a changed file say so.
+
+**Keep that comment in the file.** It is the attribution those four licences
+ask for, and an exported SVG travels without the `licenses/` directory that
+discharges this everywhere else. An optimiser set to strip comments — `svgo`
+does by default — removes the only notice the diagram carries. The per-icon
+table further down this file says the same thing at more length, for anyone
+who has the repository rather than a lone SVG.
+
+**When the diagram stops being an SVG, the comment stops travelling.** Pasted
+into a slide deck, a wiki page or a PDF, or converted to PNG, it is gone — and
+that is how most diagrams reach an audience. The artwork is still there, so the
+attribution still has to be somewhere: a credits slide, a caption, a colophon,
+or `licenses/` shipped alongside. The per-icon table further down this file is
+the text to copy; `cairn version --licenses` prints a shorter pointer to it.
+This is the one case cairn cannot do for you, because nothing of cairn's is
+left in the artifact by then.
+
+One limit worth stating: Apache-2.0 §4(a) asks that recipients be given "a copy
+of the License", and a comment of that size in every diagram is not practical,
+so the SVG links the text rather than embedding it. CC-BY-4.0 §3(a)(3) permits
+a link outright; MIT and BSD-3-Clause get the holder's copyright line inline
+where one exists. If you need a diagram to carry the texts themselves, ship
+`licenses/` beside it.
+
+Separately from copyright: the brands these logos depict are their owners'
+trademarks. Drawing one in a diagram is not an endorsement, and cairn grants no
+rights in the marks themselves.
+
+### You use cairn as an npm package
+
+Two quite different cases, and which one you are in depends on how your own
+thing is distributed.
+
+**cairn as a dependency.** Your package declares `@r0kshan/cairn` in
+`dependencies` and your users' `npm install` fetches it from the registry, with
+`LICENSE`, this file and `licenses/` intact in `node_modules`. You are
+distributing no copies of cairn, so nothing here attaches to you. Just don't
+strip those files out of what you publish.
+
+**cairn bundled into your artifact** — a webpack/rollup/esbuild bundle, a
+Docker image, an Electron app, a single-file CLI. Now cairn's code, and the
+elkjs inside it, are part of what you hand someone. You take on cairn's
+Apache-2.0 (`LICENSE`), elkjs' EPL-2.0 (§3.2(b) wants a copy of the Agreement
+with each copy of the program), and the per-icon attribution. In practice that
+is copying `LICENSE`, this file and `licenses/` out of the installed package
+into your own distribution.
+
+`bin/cairn.mjs` and `dist/cairn.mjs` each begin with a `/*!` banner naming what
+they contain, and most minifiers preserve `/*!` by default. **Check your
+bundler's comment settings**: one configured to strip all comments removes the
+only notice the code itself carries.
+
+Note that the icon artwork is in the bundle whether or not you ever use a
+`logo:` — the table is not tree-shaken. So for redistribution the six licensed
+icons above apply regardless; it is only your *output* that depends on which
+logos you actually draw.
+
+**EPL-2.0 does not reach your code.** Its copyleft covers modifications to the
+EPL'd work; cairn does not modify elkjs, and bundling is not modification. Your
+own code stays under whatever licence you choose. This is why cairn elects
+EPL-2.0 from elkjs' dual offer rather than GPL-3.0-or-later.
+
+### You redistribute cairn itself
+
+Republishing the binaries, mirroring the release assets, or shipping a cairn
+executable inside something else. This is the heavy case, and it is what most
+of this file exists for: the binaries additionally embed the Bun runtime, which
+statically links JavaScriptCore under the LGPL in part, along with everything
+else in `licenses/bun-LICENSE.md`.
+
+The short version is that the licence texts have to travel with the binary.
+Every installer cairn publishes already puts them on disk for you, but not next
+to the executable: the curl installer unpacks them into `share/doc/cairn`
+beside the `bin/` it installs into, Homebrew stages them into the formula's
+`doc` directory, and Scoop unpacks them into the app directory. Copying just
+the binary out of an install therefore leaves the notices behind — take those
+files with it.
+
+If you are building your own, this is what has to travel with it:
+
+| What | Where it is | Why |
+|---|---|---|
+| `LICENSE` | repo root | cairn's own Apache-2.0, §4(a) |
+| `THIRD-PARTY-NOTICES.md` | repo root | this file — the per-icon attribution and the §6 offer |
+| `licenses/elkjs-EPL-2.0.md` | `licenses/` | EPL-2.0 §3.2(b), a copy with each copy |
+| `licenses/simple-icons-CC0-1.0.md` and the four icon texts | `licenses/` | the six marks that carry their own terms |
+| `licenses/bun-LICENSE.md` and `licenses/LGPL-2.1.txt` | `licenses/` | the runtime the binary embeds |
+
+Shipping the whole `licenses/` directory plus those two root files is the
+simplest way to get all of it, and is what every installer above does.
+
+Two things a copied directory does not give you. The LGPL-2.1 §6 offer names a
+specific WebKit revision, a specific cairn tag and a specific build script — if
+you build against a different Bun, that offer is wrong and you must restate it
+for what you actually linked. And `cairn version --licenses` prints from inside
+the binary, so a build of your own prints your build's notice, not this one.
+Read the Bun and JavaScriptCore sections below before you ship.
 
 ## elkjs
 
@@ -17,8 +163,9 @@ copy of elkjs' own `LICENSE.md`, upstream at https://www.eclipse.org/legal/epl-2
 
 That copy is vendored rather than referenced because elkjs is a *devDependency*:
 the published package installs zero dependencies, so `node_modules/elkjs/` never
-reaches a consumer while the inlined code does. EPL-2.0 §3.1(b) requires the
-license to travel with the distributed form, so `files` ships it in the tarball.
+reaches a consumer while the inlined code does. The inlined form is source
+code, so EPL-2.0 §3.2(b) requires a copy of the Agreement with each copy of it,
+and `files` ships that copy in the tarball.
 
 Per EPL-2.0 §3.1(a): the source code for elkjs is available under the EPL-2.0,
 and can be obtained from https://github.com/kieler/elkjs or from the published
@@ -29,9 +176,166 @@ ties it back to.
 cairn asserts no ownership over elkjs and does not relicense it. Apache-2.0
 covers cairn's own code only.
 
+## Bun
+
+The release binaries are built with `bun build --compile`
+(`scripts/build-binaries.sh`), which packages cairn's code **together with the
+Bun runtime** into one executable. So unlike esbuild, biome and typescript, Bun
+is not merely a build tool here: part of it is distributed in every binary
+cairn publishes. The npm bundles and the playground are built with esbuild and
+carry none of it, and `cairn version --licenses` says so per artifact — the binaries
+print the Bun paragraph, the npm CLI does not.
+
+**Version 1.4.0.** The release workflow pins `bun-version`
+(`.github/workflows/release.yml`) rather than tracking `latest`, because a
+notice that cannot name the runtime it shipped is not a notice. The same pin is
+recorded in `src/notice.ts` as `BUN_VERSION`.
+
+Bun itself is MIT. Its runtime statically links a long list of further
+components with their own terms. Bun's own `LICENSE.md` is the authoritative
+enumeration of them, and it is reproduced verbatim at
+[`licenses/bun-LICENSE.md`](./licenses/bun-LICENSE.md) — fetched from the
+`bun-v1.4.0` tag, so it enumerates the runtime cairn actually embeds rather
+than whatever upstream `main` says today. That file, not this section, is the
+notice for everything Bun links; it is shipped with every binary.
+
+### JavaScriptCore and the LGPL
+
+The component that carries real obligations is JavaScriptCore, from WebKit,
+which Bun links statically and which is under the GNU Lesser (originally
+Library) General Public License for part of its source. Which version takes a
+sentence to state, because the sources disagree in wording rather than in
+substance: Bun's `LICENSE.md` labels it `LGPL-2`, while WebKit's own file
+headers offer "version 2 of the License, or (at your option) any later
+version". cairn takes that offer at **2.1** — that is the text shipped at
+[`licenses/LGPL-2.1.txt`](./licenses/LGPL-2.1.txt), and the §6 offer below is
+written against it. tinycc, also in Bun's list, is LGPL v2.1 outright.
+
+LGPL-2.1 §6 permits distributing a work that statically links the library
+provided the recipient can modify the library and relink. cairn discharges that
+as follows, and everything named here is published:
+
+- **The library's source.** JavaScriptCore as Bun links it is at
+  <https://github.com/oven-sh/webkit>, at revision
+  `0f966e81b78c84bb23213e391bc679c4ef83e56b` — the `WEBKIT_VERSION` pinned in
+  `scripts/build/deps/webkit.ts` at Bun's `bun-v1.4.0` tag, which is the Bun
+  the release workflow is pinned to. Naming the revision rather than the
+  repository is the point: "the version Bun happens to use" is not something a
+  recipient can check, and a relink has to start from the same source the
+  binary was built against. Bun's `LICENSE.md` gives the relink procedure
+  verbatim, and it is reproduced at `licenses/bun-LICENSE.md`.
+- **cairn's own source, which is the rest of the work.** Apache-2.0, at
+  <https://github.com/R0kshan/cairn>, at the tag the binary was built from —
+  `cairn version` prints that tag, and the release carries a build-provenance
+  attestation tying the binary to that commit.
+- **The build that combines them.** `scripts/build-binaries.sh`, in the same
+  repository, is the whole of it: one `bun build --compile` invocation against
+  a pinned Bun. Anyone who relinks a modified JavaScriptCore into Bun by
+  upstream's procedure can rerun that script and obtain an equivalent cairn
+  binary.
+
+Requests for anything in this list that you cannot obtain from those URLs
+should be opened as an issue on the cairn repository.
+
+> **This is a good-faith implementation, not a legal opinion.** Static linking
+> of LGPL-2.1 code is an area where reasonable lawyers differ, particularly on
+> whether an offer of source-plus-build-script is equivalent to the "object
+> format" §6 speaks of. The facts above are accurate and the materials are
+> genuinely published; whether they are sufficient for a given jurisdiction or
+> distribution is a question for counsel. If you need certainty without that
+> question, the npm and playground artifacts contain no Bun and no LGPL code at
+> all.
+
+## simple-icons
+
+Version 16.29.0, CC0-1.0. Upstream: https://github.com/simple-icons/simple-icons
+
+cairn's shipped artifacts and runtime do not depend on simple-icons; only
+regenerating the logos does. A curated
+subset of its icon *paths* — the ones behind `logo: <name>` — is vendored into
+`src/logos.ts` by `scripts/update-logos.mjs`, which fetches the pinned version
+with `npm pack` and writes the paths out as source. The full license text is in
+[`licenses/simple-icons-CC0-1.0.md`](./licenses/simple-icons-CC0-1.0.md), a
+verbatim copy of the project's own `LICENSE.md` at that version.
+
+That version stamp is deliberate. The file records which licence governed the
+paths cairn actually ships, so it is a historical fact rather than a mirror of
+upstream: a later relicence there cannot make it wrong, and cannot oblige a
+cairn release. CC0 is irrevocable, so paths vendored under it stay CC0 whatever
+simple-icons does next.
+
+**The project licence is not the whole story.** Simple Icons' `DISCLAIMER.md`
+says individual icons may carry their own terms, and some of the ones cairn
+vendors do. `scripts/update-logos.mjs` reads each icon's declared licence and
+refuses anything cairn cannot pass on under its own Apache-2.0 — so such an icon
+cannot reach `src/logos.ts` even if someone adds it to the curated list. The
+reasons differ by licence, and are set out with the table below.
+
+<!-- generated by scripts/update-logos.mjs — do not edit by hand -->
+
+Most of the 37 vendored icons carry no licence of their own and are
+covered by the project-wide CC0-1.0 above. These declare their own, which
+applies to that icon's artwork instead:
+
+| Icon | Licence | Full text | Artwork source |
+| --- | --- | --- | --- |
+| Angular (`angular`) | CC-BY-4.0 | [`CC-BY-4.0.txt`](./licenses/CC-BY-4.0.txt) | <https://angular.dev/press-kit> |
+| Apache (`apache`) | Apache-2.0 | [`Apache-2.0.txt`](./licenses/Apache-2.0.txt) | <https://www.apache.org/foundation/press/kit> |
+| Apache Kafka (`apachekafka`) | Apache-2.0 | [`Apache-2.0.txt`](./licenses/Apache-2.0.txt) | <https://apache.org/logos> |
+| Apache Spark (`apachespark`) | Apache-2.0 | [`Apache-2.0.txt`](./licenses/Apache-2.0.txt) | <https://apache.org/logos> |
+| JavaScript (`javascript`) | MIT | [`MIT-javascript-logo.js.txt`](./licenses/MIT-javascript-logo.js.txt) | <https://github.com/voodootikigod/logo.js/blob/1544bdeed6d618a6cfe4f0650d04ab8d9cfa76d9/js.svg> |
+| OpenJDK (`openjdk`) | BSD-3-Clause | [`BSD-3-Clause.txt`](./licenses/BSD-3-Clause.txt) | <https://github.com/openjdk/duke/blob/master/vector/Agent.svg> |
+
+Each permits commercial redistribution and asks for attribution, which this
+table and the shipped licence texts are. **Attribution is to the artwork
+source named above.** Where a rights-holder publishes no copyright line at
+that source — as is the case for several of these marks — cairn identifies
+the origin by that URL rather than assert a copyright holder it cannot
+verify. `licenses/BSD-3-Clause.txt` is consequently the SPDX template, with
+the `<year> <owner>` fields as upstream left them; see `licenses/README.md`.
+
+Source notes:
+
+- **OpenJDK (`openjdk`)** — simple-icons records <https://hg.openjdk.java.net/duke/duke/file/ca00f100dafc/vector/Agent.svg>, and that Mercurial host has been retired — it answers 403. The attribution above therefore names the live GitHub location of the same file, recorded in SOURCE_OVERRIDES rather than silently swapped. Checked 2026-09-04: that repository has no LICENSE file, the GitHub API reports no licence for it, and `vector/Agent.svg` carries no copyright notice of its own. So there is no upstream copyright line to reproduce, which is why `licenses/BSD-3-Clause.txt` keeps the SPDX `<year> <owner>` fields blank and attribution for this mark is to the source URL.
+
+Three kinds of terms are refused by the generator instead, and never reach
+`src/logos.ts`, for three different reasons:
+
+- **NonCommercial** bars the commercial use cairn's own Apache-2.0 grants
+  downstream, so cairn would be promising a right it does not hold.
+- **ShareAlike** does permit commercial use, but requires adaptations to carry
+  the same licence — an obligation cairn cannot discharge on behalf of whoever
+  embeds the mark in their own diagram.
+- **A trademark policy** in place of a licence is not a copyright grant at all,
+  so there is no permission to copy the artwork to rely on.
+
+<!-- end generated -->
+
+CC0-1.0 waives copyright and imposes no attribution requirement, so for the
+icons it covers this entry is a courtesy rather than an obligation. It is kept
+because the paths reach users inside every shipped artifact, and a reader
+deserves to know where the artwork came from. For the icons in the table above
+it is not a courtesy: MIT, BSD-3-Clause, CC-BY-4.0 and Apache-2.0 each require
+the attribution it carries.
+
+**Trademarks are a separate matter from the license.** Simple Icons' own
+`DISCLAIMER.md` is explicit that CC0 covers the project while individual icons
+may carry their own terms, and that brand marks remain the property of their
+owners. cairn redistributes the artwork only; it claims no rights in the brands
+depicted, and using a logo in a diagram does not imply the brand endorses
+anything. Anyone republishing a cairn diagram is responsible for their own use
+of the marks it shows.
+
 ---
 
 If the set of inlined dependencies changes, update this file **and** `licenses/`
-in the same commit — a notice that names a license text the tarball doesn't carry
-is the failure mode this section exists to prevent. `files` in `package.json`
-ships both with the npm package.
+**and** `src/notice.ts` in the same commit — a notice that names a license text
+the tarball doesn't carry is the failure mode this section exists to prevent.
+`files` in `package.json` ships them with the npm package.
+
+`src/notice.ts` is the single source for the short form: the bundle banners
+(`scripts/notice-banner.sh`) and `cairn version --licenses` both render from it,
+so they cannot drift apart. `tests/notice.test.ts` fails the build if a checked-in
+artifact's banner no longer matches. The long form — full texts, per-icon
+attribution, the LGPL relink offer — is this file, and `licenses/README.md`
+records where each text was fetched from.