@openpowershift/logic-diagram-language 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Mulholland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# LDL — Logic Diagram Language
+
+LDL is a small text language and renderer for **logic and protection diagrams**. You
+write boolean equations; the renderer draws the gates, routes the wires, and lays the
+whole diagram out automatically — producing clean, publication-quality SVG (and PNG/PDF
+in the browser).
+
+> **Try it in the browser: [openpowershift.github.io/logic-diagram-language](https://openpowershift.github.io/logic-diagram-language/)**
+> — a live playground: type LDL on the left, see the diagram on the right.
+>
+> Published as **`@openpowershift/logic-diagram-language`**. See the **[API Reference](docs/api.adoc)**
+> for programmatic use.
+
+```
+TRIP = OVERCURRENT AND NOT BLOCK
+      OR (EARTH AND MANUAL)
+```
+
+That single expression yields a complete diagram: boundary inputs on the left, gates in
+the middle, the `TRIP` output on the right, with wires routed and crossings minimised —
+no coordinates, no manual placement.
+
+## Why
+
+Protection and control schematics are tedious to draw by hand and awkward to keep in
+sync with the logic they represent. LDL treats the **logic as the source of truth**: the
+diagram is a rendering of an expression, so it is diffable, reviewable, and regenerated
+automatically whenever the logic changes.
+
+## Goals & concepts
+
+- **Expression-first.** A simple boolean expression produces a complete diagram. Names
+  that are consumed elsewhere become shared internal signals; names that aren't become
+  outputs.
+- **Declarative — the layout is the renderer's job.** You describe _what_ is connected,
+  not _where_ things go. A Sugiyama-style layout engine assigns layers and coordinates
+  and actively minimises wire crossings; every reshaping pass validates a single
+  wire-separation contract so wires never overlap or crowd.
+- **Protection-domain aware.** Beyond `AND`/`OR`/`NOT`, LDL has SEL-style function
+  blocks — `TIMER`, `SR` latch, `RISING`/`FALLING` edge triggers, `COMPARE` comparator,
+  and a generic `FB` block — plus seal-in/feedback loops drawn as loop-back wires.
+- **Labelled & styled.** Inputs, outputs and gates carry `.Name`/`.Description` labels
+  (with inline TeX math via MathJax), and every element has a stable id/class for CSS.
+- **Readable output.** Options control inversion bubbles vs. NOT gates, input bars,
+  compactness, adaptive column spacing, and more.
+
+## Use as a library
+
+```bash
+npm install @openpowershift/logic-diagram-language
+```
+
+```ts
+import {
+  parse,
+  renderDiagram,
+  resolveOptions,
+} from "@openpowershift/logic-diagram-language";
+
+const { diagram } = parse("O1 = I1 AND NOT I2");
+const svg = renderDiagram(
+  diagram,
+  diagram.portMeta,
+  true,
+  false,
+  resolveOptions(diagram.options),
+); // → a complete <svg>…</svg> string
+```
+
+SVG rendering is isomorphic (Node + browser). In the browser, `svgToPngBlob(svg)` and
+`svgToPdfBlob(svg)` rasterise it to a PNG/PDF `Blob`. Full API, options table and PNG/PDF
+recipes are in the **[API Reference](docs/api.adoc)**.
+
+## Playground / development
+
+Requires Node 20+ (the dev playground uses Node 24 — see `.nvmrc`).
+
+```bash
+npm install
+npm run dev        # live playground at the printed URL — type LDL, see SVG update live
+npm run build      # type-check + production build of the playground app to dist/
+npm run build:lib  # build the publishable library to dist/ (index.js + type declarations)
+npm test           # run the test suite (vitest)
+```
+
+The playground has a source editor on the left and a live diagram on the right, with a
+dropdown of built-in examples covering every language feature. Toggle labels/ids,
+junction dots, zoom, and export to SVG/PNG/PDF.
+
+## A taste of the language
+
+```ldl
+OPTION OUTPUT_ORDER = AUTO
+
+// SEL-style: a comparator feeds an SR latch, sealed in, into a pickup timer
+A     = SR(COMPARE(IA, IPICKUP), RESET)
+TRIP  = TIMER(A, 0, 30cyc)
+ALARM = RISING(COMPARE(IA, IPICKUP))
+
+IA.Name       = "$I_a$"
+IPICKUP.Name  = "$I_{pickup}$"
+TRIP.Name     = "Trip"
+```
+
+See the **[User Guide](docs/user-guide.adoc)** for the full working syntax with
+examples, and the **[LDL Specification](spec/spec.adoc)** for the formal grammar and the
+rendering contract. Current implementation status is tracked in
+[IMPLEMENTATION.md](IMPLEMENTATION.md).
+
+**Generating LDL with an AI agent?** Point it at
+**[docs/ldl-for-llms.md](docs/ldl-for-llms.md)** — a compact, implemented-only authoring guide (the
+full spec includes reserved features that don't render yet, which trips agents up).
+
+## Project layout
+
+| Path                  | What                                                                                  |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `src/index.ts`        | Public library API (`parse`, `renderDiagram`, `layoutDiagram`, options, types)        |
+| `src/export-image.ts` | Browser-only PNG/PDF helpers (`svgToPngBlob`, `svgToPdfBlob`)                         |
+| `src/parser/`         | Tokeniser, parser, and AST for LDL source                                             |
+| `src/renderer/`       | Layout engine (`layout.ts`, `graph.ts`), A\* wire router, SVG renderer, gate symbols  |
+| `src/components/`     | Lit web components — the playground app, editor and viewer                            |
+| `src/worker/`         | Off-thread parse → layout → render worker                                             |
+| `docs/`               | [User guide](docs/user-guide.adoc) and [API reference](docs/api.adoc)                 |
+| `spec/`               | AsciiDoc language specification (`spec/spec.adoc`)                                    |
+| `tests/`              | Vitest unit tests, layout invariants, and golden geometry/visual-regression snapshots |
+
+## Status
+
+LDL is under active development. The core language (boolean expressions, intermediates,
+feedback, SEL function blocks, labels, TeX math, styling, and the layout options) is
+implemented and tested. Some specified constructs are reserved but not yet implemented —
+the `NAND`/`NOR`/`XOR`/`XNOR` operators, `CONNECT`, custom `SYMBOL` definitions,
+`IMPORT`/`STYLESHEET`, and hyperlinks. See the guide and `IMPLEMENTATION.md` for the
+current boundary.
+
+## License
+
+[MIT](LICENSE) © 2026 Daniel Mulholland

package/dist/examples.d.ts

@@ -0,0 +1,2 @@
+export declare const EXAMPLES: Record<string, string>;
+export declare const EXAMPLE_NAMES: string[];

package/dist/examples.js

@@ -0,0 +1,469 @@
+export const EXAMPLES = {
+    'Breaker Failure (SEL-751A)': `// Feedback seal-in: BFT appears inside its OWN definition, so rather than
+// becoming a second input it is drawn as a loop-back wire (a latch holding
+// itself in). Labels use inline TeX ($...$). OUTPUT_ORDER / INPUT_ORDER = AUTO
+// reorder ports to minimise crossings (INPUT_ORDER is AUTO by default anyway).
+OPTION OUTPUT_ORDER = AUTO
+OPTION INPUT_ORDER = AUTO
+
+BFT = BFI OR BFT AND ((CB52A AND CB52ABFY) OR (I1I2 AND INOM))
+
+BFI.Description = "Relay Word Bit"
+
+CB52A.Name = "52A"
+CB52ABFY.Name = "52ABF = Y"
+CB52ABFY.Description = "Setting"
+
+I1I2.Name = "$\\mathrm{|I1|+|I2|}$"
+INOM.Name = "$\\mathrm{0.02 \\cdot I_{NOM}}$"
+
+// SEL-751A Instruction Manual Figure 4.55 Breaker Failure Logic`,
+    'SEL Function Blocks': `// SEL-style function blocks compose like any sub-expression:
+//   TIMER(in, pu, do) - pickup/dropout delays. A bare number is cycles; ms/s/m
+//                       also work, or name them PU=/DO=. 0 = no delay.
+//   SR(set, reset).Q  - set/reset latch (.NQ for Q-bar; DOMINANT=SET, see "SR Latch").
+//   COMPARE(+, -)     - analog comparator.  RISING/FALLING(in) - edge one-shots.
+OPTION OUTPUT_ORDER = AUTO
+A = SR(COMPARE(IA, IPICKUP), RESET)
+TRIP = TIMER(A, 0, 30cyc)
+ALARM = RISING(COMPARE(IA, IPICKUP))
+RESTART = FALLING(BLOCK)`,
+    'SR Latch (Q and NQ)': `// SR latch with both outputs: .Q (default) and .NQ (the inverted output, Q-bar).
+// Referencing SR#L1 twice reuses the SAME latch; DOMINANT=SET makes 'set' win
+// when both inputs are asserted (reset-dominant by default). Each output port
+// is drawn only when it is referenced.
+PERMIT  = SR#L1(START, STOP, DOMINANT=SET).Q
+BLOCKED = SR#L1(START, STOP).NQ
+L1.Name = "Enable Latch"`,
+    'Layout Options': `// Layout controls: ADAPTIVE column spacing packs each column to its content
+// (default UNIFORM), COMPACT_V tightens row spacing (also COMPACT_H, COMPACT,
+// SPACIOUS, or explicit factors like [70,70]), and an expression may span
+// multiple lines — a continuation line simply begins with whitespace.
+OPTION COLUMN_SPACING = ADAPTIVE
+OPTION COMPACTNESS = COMPACT_V
+OPTION OUTPUT_ORDER = AUTO
+
+TRIP = PHASE AND ENABLE
+    OR (EARTH AND NOT BLOCK)
+    OR MANUAL
+
+PHASE.Name = "Phase OC"
+EARTH.Name = "Earth Fault"
+BLOCK.Name = "Harmonic Block"`,
+    'Labelled Gates': `// Name a gate by assigning it to an intermediate, then label that name — the
+// name/description appear at the gate's output and wires route around them.
+// (For the same result without the pass-through name, see "Named Gates".)
+OPTION OUTPUT_ORDER = AUTO
+PH  = O51 OR O50 OR NEGSEQ
+EF  = E51N OR E50N
+HS  = O502 OR E50N2
+SUP = PH AND NOT HBLK
+TRIP = SUP OR EF OR HS
+PH.Name = "Phase OC"
+PH.Description = "51/50/46"
+EF.Name = "Earth Fault"
+EF.Description = "51N/50N"
+HS.Name = "High-Set"
+HS.Description = "50-2"
+SUP.Name = "Supervised"
+SUP.Description = "harmonic block"`,
+    'Complex Protection (SEL)': `// Every block type, nested and mixed with gates. A block may take an instance
+// id (TIMER#TD, COMPARE#C50) so it can carry a .Name/.Description, and blocks
+// nest freely — here a COMPARE feeds an SR feeds a TIMER. Bare cycle numbers
+// (2cyc, 12cyc) are positional PU/DO settings.
+OPTION OUTPUT_ORDER = AUTO
+
+OC_TRIP = TIMER#TD(SR#TL(COMPARE#C50(IA, IPICKUP) AND NOT BLOCK, RESET), 2cyc, 0)
+BF_TRIP = TIMER#BFT(COMPARE#C87(IDIFF, IREST) AND CB52A, 0, 12cyc)
+ALARM = RISING(START) OR EXT_ALARM
+RECLOSE = FALLING(CB52A) AND NOT LOCKOUT
+
+C50.Name = "50P1"
+C50.Description = "Phase OC"
+C87.Name = "87"
+C87.Description = "Differential"
+TL.Name = "Trip Latch"
+TD.Name = "62T"
+TD.Description = "Trip delay"
+BFT.Name = "62BF"
+BFT.Description = "BF delay"`,
+    'Shared Intermediates': `// Consumed intermediates: A is internal but labelled at its junction;
+// B is forced to an output with .OUT = TRUE
+OPTION OUTPUT_ORDER = AUTO
+B = COMPARE(IA, IPICKUP)
+A = SR(B, RESET) OR B OR C
+TRIP = TIMER(A, 0, 30cyc)
+ALARM = RISING(COMPARE(IA, IPICKUP))
+A.Name = "Trip Permit"
+A.Description = "Seal-in"
+B.OUT = TRUE`,
+    'Generic Block (FB)': `// A generic user block (FB): a box with whatever ports you need, for a function
+// whose internals aren't drawn. Call arguments are input ports (NAME=expr labels
+// them); each .PORT you reference is an output port. Reusing one #id (FB#PROT)
+// binds several outputs to a SINGLE box.
+OPTION OUTPUT_ORDER = AUTO
+TRIP  = FB#PROT(PHASE=IA, EARTH=IN, EN=ENABLE).TRIP
+ALARM = FB#PROT.ALARM
+CLOSE = FB#PROT.CLOSE
+PROT.Name = "Feeder Protection"
+PROT.Description = "SEL-751A"`,
+    'Named Gates': `// Direct gate naming with AND#ID(...) / OR#ID(...) — no pass-through intermediate needed
+OPTION OUTPUT_ORDER = AUTO
+OC = OR#OC1(I51, I50, I46)
+OC1.Name = "Overcurrent"
+OC1.Description = "51/50N"
+TRIP = AND#TRIP1(OC, NOT BLOCK)
+TRIP1.Name = "Trip AND"
+TRIP1.Description = "permissive"
+O1 = AND#GEN(A, B)
+GEN.Name = "Combo Gate"
+GEN.Description = "stage 1"`,
+    'Simple AND Gate': `// The smallest diagram: one assignment. Bare identifiers that are never
+// assigned (A, B) become boundary inputs on the left; the assigned name (OUT)
+// becomes the output on the right. The operators are AND, OR and NOT.
+OUT = A AND B`,
+    'Simple OR Gate': `// An OR gate. Its ">=1" glyph is the IEC 60617 symbol for OR (AND shows "&",
+// NOT a triangle). Combine AND / OR / NOT to build any boolean expression.
+OUT = A OR B`,
+    'NOT Gate': `// A NOT gate (inverter), drawn as a triangle with a bubble. With
+// OPTION INVERSION = BUBBLES the inversion is drawn as just a bubble on the
+// downstream port instead of a separate gate (see "Inversion Bubbles").
+OUT = NOT A`,
+    'Combined Logic (CBFPS)': `// Operator precedence is NOT > AND > OR, so this parses as
+// (AB AND DC) OR ((NOT DC) AND GF). Add parentheses to override precedence.
+CBFPS = AB AND DC OR (NOT DC AND GF)`,
+    'Trip Logic': `// TRIP is used by MAIN_TRIP, so it is a consumed intermediate — drawn as an
+// internal gate, not a boundary output. Add "TRIP.OUT = TRUE" to also expose it
+// as an output (see "Shared Intermediates").
+TRIP = OVERCURRENT OR (NOT EARTH_FAULT)
+MAIN_TRIP = TRIP AND (MANUAL_TRIP OR REMOTE_TRIP)`,
+    'Three-Input AND': `// A multi-input gate. By default (GATE_INPUT_STYLE = EXPAND) the gate grows
+// vertically to fit every input; GATE_INPUT_STYLE = BARS keeps it 2-input-sized
+// and taps the extra inputs onto vertical bars instead (see "Input Bars").
+OUT = A AND B AND C`,
+    'Triple OR': `// Three inputs into one OR gate. INPUT_ORDER = AUTO (the default) may reorder
+// a gate's inputs to reduce wire crossings; INPUT_ORDER = DECLARATION keeps the
+// order as written.
+ALARM = TEMP OR PRESSURE OR FLOW`,
+    'Nested NOT': `// Double negation cancels: NOT NOT A = A, so no inverter is drawn. An odd
+// number of NOTs reduces to a single inversion — try adding one more NOT.
+OUT = NOT NOT A`,
+    'Complex Protection': `// TRIP_1 and TRIP_2 are referenced by MAIN_TRIP, so they are consumed
+// intermediates: drawn as internal gates that fan out, not as boundary outputs.
+// Only MAIN_TRIP (referenced by nothing) becomes an output. OUTPUT_ORDER = AUTO
+// stacks outputs by their driver to reduce crossings (default: DECLARATION order).
+OPTION OUTPUT_ORDER = AUTO
+TRIP_1 = OVERCURRENT_A OR OVERCURRENT_B
+TRIP_2 = EARTH_FAULT AND NOT BLOCK
+MAIN_TRIP = TRIP_1 AND TRIP_2`,
+    'Mixed Logic': `// Mixed AND/OR with negation: RESULT is consumed (not shown), OUTPUT is the result
+RESULT = (A AND B) OR (C AND NOT D)
+OUTPUT = RESULT AND (ENABLE OR FORCE)`,
+    'Launch Interlock': `// Launch interlock for Pad 39A: all safety permissives, no hold,
+// AND either the automatic sequence OR a manual firing enable ignition
+
+I1.Name = "Pad Cleared"
+I1.Description = "(LP 3.1)"
+
+I2.Name = "Umbilicals Retracted"
+I2.Description = "(LP 3.24)"
+
+I3.Name = "Tanks Pressurised"
+I3.Description = "(LP 3.3)"
+
+I4.Name = "Guidance Aligned"
+I4.Description = "(GNC 3.5)"
+
+I5.Name = "Hold Fired"
+I5.Description = "(RSO 3.15)"
+
+I6.Name = "Auto Sequence"
+I6.Description = "(SEQ 3.11)"
+
+I7.Name = "Range Safety Armed"
+I7.Description = "(RSO 3.23)"
+
+I8.Name = "GO from LCC"
+I8.Description = "(via LCC)"
+
+I9.Name = "Manual Enable"
+I9.Description = "(LCC 3.12)"
+
+I10.Name = "Fire Button"
+I10.Description = "(LCC 3.20)"
+
+O1 = (I1 AND I2) AND (I3 AND I4 AND NOT I5) AND ((I6 AND I7 AND I8) OR (I9 AND I10))
+
+O1.Name = "Launch Command"
+O1.Description = "(BO 3.2)"`,
+    'Inversion Bubbles': `// INVERSION = BUBBLES draws every NOT as a small bubble on the downstream
+// input/output port instead of a separate NOT gate (the default is
+// INVERSION = GATES). O4 shows double-inversion cancellation (NOT NOT I3 = I3).
+OPTION INVERSION = BUBBLES
+
+I1.Name = "Start Permitted"
+I1.Description = "(BI 1.1)"
+I2.Name = "Stop Condition"
+I2.Description = "(BI 1.2)"
+I3.Name = "Reset"
+I3.Description = "(BI 1.3)"
+
+O1 = I1 AND NOT I2 AND I3
+O2 = NOT (I1 AND I3)
+O3 = NOT I2
+O4 = NOT NOT I3
+
+O1.Name = "Run"
+O1.Description = "(BO 1.1)"
+O2.Name = "NAND Result"
+O2.Description = "(BO 1.2)"
+O3.Name = "Inverted Stop"
+O3.Description = "(BO 1.3)"
+O4.Name = "Pass-Through"
+O4.Description = "(BO 1.4)"`,
+    'Input Bars': `// GATE_INPUT_STYLE = BARS keeps a multi-input gate at its base 2-input size and
+// taps the extra inputs onto vertical bars. The default, EXPAND, grows the gate
+// vertically instead (compare "Three-Input AND").
+OPTION GATE_INPUT_STYLE = BARS
+
+I1.Name = "Start"
+I2.Name = "Stop"
+I3.Name = "Reset"
+I4.Name = "Enable"
+I5.Name = "Supervision"
+
+O1 = I1 AND I2 AND I3 AND I4 AND I5
+O1.Name = "Output"`,
+    'Square Ports': `// PORT_STYLE = SQUARE draws port markers as small squares; the default is
+// CIRCLE. (Other rendering options: INVERSION, GATE_INPUT_STYLE, LABEL_STYLE.)
+OPTION PORT_STYLE = SQUARE
+
+A.Name = "Signal A"
+B.Name = "Signal B"
+O1 = A AND B
+O1.Name = "Result"`,
+    'Combined Options': `// Options combine freely. Here three at once — bubbles for NOT, bars for the
+// multi-input gate, and square port markers — each overriding its own default
+// (GATES / EXPAND / CIRCLE). Options must precede the logic they affect.
+OPTION INVERSION = BUBBLES
+OPTION GATE_INPUT_STYLE = BARS
+OPTION PORT_STYLE = SQUARE
+
+I1.Name = "Start"
+I2.Name = "Stop"
+I3.Name = "Reset"
+I4.Name = "Enable"
+I5.Name = "Supervision"
+I6.Name = "Override"
+
+O1 = (I1 AND NOT I2) AND (I3 AND I4 AND I5 AND I6)
+O1.Name = "Master Trip"
+O1.Description = "(BO 1.1)"`,
+    'Overcurrent Protection': `// Inline TeX math in labels: wrap it in $...$ (e.g. $I_a$, $I_{set}$). Plain
+// text and math may be mixed, and a literal dollar is written \\$. I1 feeds both
+// outputs — a name used more than once is one shared input that fans out.
+OPTION OUTPUT_ORDER = AUTO
+I1.Name = "$I_a$"
+I1.Description = "Phase A current"
+
+I2.Name = "$I_b$"
+I2.Description = "Phase B current"
+
+I3.Name = "$I_c$"
+I3.Description = "Phase C current"
+
+I4.Name = "$I_{set}$"
+I4.Description = "Setting $= 5.0 \\$ A$"
+
+O1.Name = "$I > I_{set}$"
+O1.Description = "Overcurrent trip"
+
+O2.Name = "$I_a + I_b + I_c$"
+O2.Description = "Residual current"
+
+O1 = I1 AND I4
+O2 = I1 OR I2 OR I3`,
+    'Differential Protection': `// More TeX-labelled I/O — subscripts ($I_{in}$), inequalities ($>$) and mixed
+// text/math. I3 (Block) is used by both outputs, so it fans out to each.
+// Differential protection: $I_{diff} = I_{in} - I_{out}$
+
+I1.Name = "$I_{in}$"
+I1.Description = "CT primary current"
+
+I2.Name = "$I_{out}$"
+I2.Description = "CT secondary current"
+
+I3.Name = "Block"
+I3.Description = "Blocking signal"
+
+O1.Name = "$I_{diff} > I_{bias}$"
+O1.Description = "Differential trip"
+
+O2.Name = "Restricted Earth Fault"
+O2.Description = "$I_0 > I_{0\\_set}$"
+
+O1 = (I1 AND NOT I2) AND NOT I3
+O2 = NOT I3`,
+    'Boolean Algebra': `// The four basic functions. There is no NAND operator — write it as
+// NOT (A AND B), as O4 does. The overline in the labels is TeX
+// ($\\overline{A \\cdot B}$), not a language construct.
+OPTION OUTPUT_ORDER = AUTO
+
+A.Name = "$A$"
+A.Description = "Input A"
+
+B.Name = "$B$"
+B.Description = "Input B"
+
+C.Name = "$C$"
+C.Description = "Input C"
+
+O1.Name = "$A \\cdot B$"
+O1.Description = "Logical AND"
+
+O2.Name = "$A + B$"
+O2.Description = "Logical OR"
+
+O3.Name = "$\\overline{A}$"
+O3.Description = "Logical NOT"
+
+O4.Name = "$\\overline{A \\cdot B}$"
+O4.Description = "NAND: $\\overline{AB}$"
+
+O1 = A AND B
+O2 = A OR B
+O3 = NOT A
+O4 = NOT (A AND B)`,
+    'Motor Control Circuit': `// A motor starter: TeX-labelled I/O plus INVERSION = BUBBLES for the NOT
+// inputs. Note the OPTION line can sit anywhere before the expressions that use
+// it (here it follows the label declarations).
+
+I1.Name = "Start PB"
+I1.Description = "$NO\\ contact$"
+
+I2.Name = "Stop PB"
+I2.Description = "$NC\\ contact$"
+
+I3.Name = "OL Trip"
+I3.Description = "$I^2 > I_{rated}^2$"
+
+I4.Name = "Thermal"
+I4.Description = "$\\Theta > \\Theta_{trip}$"
+
+I5.Name = "$I_s$"
+I5.Description = "Start current"
+
+O1.Name = "Contactor"
+O1.Description = "$K_1$"
+
+O2.Name = "Trip"
+O2.Description = "$\\Delta I > \\Delta I_{set}$"
+
+OPTION INVERSION = BUBBLES
+
+O1 = I1 AND NOT I2 AND NOT I3 AND NOT I4
+O2 = I3 OR I4 OR NOT I5`,
+    'Styled by ID': `// Reveal IDs in the toolbar to see the SVG id on each gate, block and port.
+//
+// A gate/block group carries its instance id: AND#G1 -> id "G1", FB#P -> id "P".
+// The gate body is a <path> and the block body a <rect>, each carrying its OWN fill
+// and stroke, so target the shape, not the group: "#G1 path" styles the gate body and
+// "#P rect" styles the block body. Setting fill/stroke on the group ("#G1" / "#P") does
+// not reach the body — the shape's own attribute wins — it only reaches inheriting
+// children such as the block's text.
+// Every wire carries data-from / data-to with its net endpoints, so
+// '.ldl-wire[data-to="TRIP"]' colours the wire feeding the TRIP output.
+//
+// What each rule in the STYLE block below targets:
+//   #G1 path                   -> the AND gate's body <path> (fill).
+//   #P rect                    -> the block's body <rect> (fill + stroke).
+//   .ldl-wire[data-to="TRIP"]  -> the signal wire whose destination net is TRIP.
+//   .ldl-wire[data-to="ALARM"] -> the signal wire whose destination net is ALARM.
+// Note: a bare "#TRIP" matches only the output node's short id-stub, NOT the wire that
+// feeds it — colour the wire itself via its data-to net.
+//
+// Toggle the Dots toolbar button to hide junction tie-points (item 11).
+// Use the PNG dropdown for selectable-DPI raster export (item 13).
+OPTION OUTPUT_ORDER = AUTO
+OPTION HIDE_JUNCTIONS = FALSE
+
+TRIP = AND#G1(START, INHIBIT, FB#P(BAND=IA, EARTH=IN, EN=BLK).TRIP)
+ALARM = FB#P.ALARM
+
+G1.Name = "Trip AND"
+P.Name = "Feeder Protection"
+P.Description = "SEL-751A"
+
+STYLE
+  #G1 path { fill: #ff003333; }
+  #P rect { fill: #e8f5e9; stroke: #1b5e20; }
+  .ldl-wire[data-to="TRIP"] { stroke: #c62828; stroke-width: 4; }
+  .ldl-wire[data-to="ALARM"] { stroke: #ef6c00; }
+END STYLE`,
+    'Hidden Dots': `// OPTION HIDE_JUNCTIONS hides every junction dot on the diagram (the toolbar
+// Dots button flips the same flag on top of the source option). Useful when
+// printing or when the wiring/junction pattern is visually noisy.
+OPTION HIDE_JUNCTIONS = TRUE
+OPTION INVERSION = BUBBLES
+A = A1 OR A2 OR A3
+B = B1 AND B2 AND B3
+O = A AND B AND C`,
+    'Reactor Scram Matrix': `// Real-world scram matrix: a large (18-input) OR gathers every reactor
+// protection trip, an SR latch seals it in, and the result fans out to
+// annunciators, the plant computer, transient records and rod-drive trips.
+// Exercises large fan-in and reconvergence (SCR01 drives several outputs and
+// the RTS OR; RTS drives more).
+OPTION OUTPUT_ORDER = AUTO
+
+E24U2T1.Name = "NEUTRON FLUX HIGH"
+EWT.Name = "CORE OUTLET TEMP HIGH (RT301)"
+E50TP2.Name = "RCS PRESSURE HIGH (PT502)"
+EPSV17.Name = "RCS PRESSURE LOW (PT517)"
+E51T01.Name = "SG-1 LEVEL LOW (LT101)"
+E51T02.Name = "SG-2 LEVEL LOW (LT102)"
+E593P1T.Name = "CONTAINMENT PRESS HI-1 (PT591)"
+E593P2T.Name = "CONTAINMENT PRESS HI-2 (PT592)"
+EBUCH.Name = "RCP UNDERSPEED (ST307)"
+ETP.Name = "STEAM LINE PRESSURE"
+EREFF2.Name = "REACTOR COOLANT FLOW LOW (FT2)"
+E87Z2.Name = "PRESSURISER LEVEL HIGH (LT2)"
+E87Q2.Name = "FEED/STEAM MISMATCH (FQ2)"
+EIN202.Name = "LOSS OF COOLANT FLOW (IN202)"
+EPLQ_X_IT.Name = "MANUAL SCRAM A (IN408)"
+EPLQ_X_CBF.Name = "MANUAL SCRAM B (IN407)"
+EGCB_CBF.Name = "TURBINE TRIP (TTFS)"
+SWA_CON_MON.Name = "DIV A DC BUS MONITOR (PSV20)"
+SWB_CON_MON.Name = "DIV B DC BUS MONITOR (PSV20)"
+CTR.Name = "From Div II Scram (IN203)"
+
+TR01 = E24U2T1 OR EWT OR E50TP2 OR EPSV17 OR E51T01 OR E51T02 OR (E593P1T OR E593P2T) OR EBUCH OR ETP OR EREFF2 OR E87Z2 OR E87Q2 OR EIN202 OR EPLQ_X_IT OR EPLQ_X_CBF OR EGCB_CBF OR SWA_CON_MON OR SWB_CON_MON
+TR01.Name = "REACTOR SCRAM"
+
+PSV01 = SR(TR01, ULTR01).Q OR CTR
+TRS = PSV01 OR TRIP3 OR TRIP5
+
+LED_01 = PSV01
+LED_01.Out = True
+LED_01.Name = "TO SCRAM LED"
+
+ICMS_PSV01 = PSV01
+ICMS_PSV01.Out = True
+ICMS_PSV01.Name = "Reactor Scram [TO SPDS] & [TO PPC]"
+
+OCT = PSV01
+OCT.Out = True
+OCT.Name = "To Transient Recorder (OUT204)"
+
+SWA_CB_TRIP_1 = PSV01
+SWA_CB_TRIP_1.Name = "TO DIV A ROD DRIVE TRIP"
+
+SWB_CB_TRIP_1 = PSV01
+SWB_CB_TRIP_1.Name = "TO DIV B ROD DRIVE TRIP"
+
+GCB_TRIP_1 = TRS
+GCB_TRIP_1.Name = "TO REACTOR TRIP BKR (OUT401)"
+
+GCB_CBF = TRS
+GCB_CBF.Name = "TO SCRAM BKR FAIL"`,
+};
+export const EXAMPLE_NAMES = Object.keys(EXAMPLES);

package/dist/export-image.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Rasterise an SVG string to a PNG Blob at `scale`× the diagram's intrinsic pixel size (default 2×).
+ * Browser only.
+ */
+export declare function svgToPngBlob(svg: string, scale?: number): Promise<Blob>;
+/**
+ * Rasterise an SVG string into a single-page PDF Blob sized to the diagram (orientation follows the
+ * aspect ratio). Loads `jspdf` on demand. Browser only.
+ */
+export declare function svgToPdfBlob(svg: string, scale?: number): Promise<Blob>;