@openpowershift/logic-diagram-language 0.1.0

package/dist/theme/themes.d.ts

@@ -0,0 +1,58 @@
+export interface DiagramTheme {
+    background: string;
+    stroke: string;
+    fill: string;
+    wire: string;
+    wireHover: string;
+    portFill: string;
+    nameFill: string;
+    nameOutFill: string;
+    descFill: string;
+    idFill: string;
+    junctionFill: string;
+}
+export interface UITheme {
+    bg: string;
+    surface: string;
+    border: string;
+    text: string;
+    textDim: string;
+    textMuted: string;
+    toolbarBg: string;
+    toolbarDark: string;
+    toolbarActive: string;
+    accent: string;
+    errorBg: string;
+    errorBorder: string;
+    errorText: string;
+    editorBg: string;
+    editorGutter: string;
+    editorGutterText: string;
+    editorActiveLine: string;
+    editorActiveGutter: string;
+    editorCursor: string;
+    editorSelection: string;
+    syntaxComment: string;
+    syntaxKeyword: string;
+    syntaxType: string;
+    syntaxVariable: string;
+    syntaxString: string;
+    syntaxNumber: string;
+    syntaxPunct: string;
+    toolbarText: string;
+    toolbarBorderAlpha20: string;
+    toolbarBorderAlpha40: string;
+    toolbarSeparator: string;
+}
+export interface AppTheme {
+    name: string;
+    ui: UITheme;
+    diagram: DiagramTheme;
+    print: DiagramTheme;
+}
+export declare const LIGHT_DIAGRAM: DiagramTheme;
+export declare const DARK_DIAGRAM: DiagramTheme;
+export declare const LIGHT_UI: UITheme;
+export declare const DARK_UI: UITheme;
+export declare const LIGHT_THEME: AppTheme;
+export declare const DARK_THEME: AppTheme;

package/dist/theme/themes.js

@@ -0,0 +1,104 @@
+export const LIGHT_DIAGRAM = {
+    background: '#ffffff',
+    stroke: '#2c3e50',
+    fill: '#ffffff',
+    wire: '#34495e',
+    wireHover: '#1b5e20',
+    portFill: '#2c3e50',
+    nameFill: '#1a237e',
+    nameOutFill: '#1a237e',
+    descFill: '#607d8b',
+    idFill: '#90a4ae',
+    junctionFill: '#34495e',
+};
+export const DARK_DIAGRAM = {
+    background: '#1a1b2e',
+    stroke: '#c8cdd5',
+    fill: '#2a2b3d',
+    wire: '#9aa5b4',
+    wireHover: '#4caf50',
+    portFill: '#c8cdd5',
+    nameFill: '#82b1ff',
+    nameOutFill: '#82b1ff',
+    descFill: '#90a4ae',
+    idFill: '#607080',
+    junctionFill: '#9aa5b4',
+};
+export const LIGHT_UI = {
+    bg: '#f5f6fa',
+    surface: '#e8eaf0',
+    border: '#dce1e8',
+    text: '#2c3e50',
+    textDim: '#78909c',
+    textMuted: '#90a4ae',
+    toolbarBg: '#2c3e50',
+    toolbarDark: '#1a252f',
+    toolbarActive: '#0f3460',
+    accent: '#3498db',
+    errorBg: '#fdecea',
+    errorBorder: '#e57373',
+    errorText: '#c62828',
+    editorBg: '#ffffff',
+    editorGutter: '#f5f6fa',
+    editorGutterText: '#90a4ae',
+    editorActiveLine: '#f0f2f8',
+    editorActiveGutter: '#e8eaf0',
+    editorCursor: '#2c3e50',
+    editorSelection: 'rgba(52, 152, 219, 0.25)',
+    syntaxComment: '#6a9955',
+    syntaxKeyword: '#9c27b0',
+    syntaxType: '#1565c0',
+    syntaxVariable: '#2c3e50',
+    syntaxString: '#e65100',
+    syntaxNumber: '#00695c',
+    syntaxPunct: '#78909c',
+    toolbarText: '#e0e0e0',
+    toolbarBorderAlpha20: 'rgba(255,255,255,0.2)',
+    toolbarBorderAlpha40: 'rgba(255,255,255,0.4)',
+    toolbarSeparator: 'rgba(255,255,255,0.25)',
+};
+export const DARK_UI = {
+    bg: '#12131e',
+    surface: '#1a1b2e',
+    border: '#2e3045',
+    text: '#e2e8f0',
+    textDim: '#9aa5b4',
+    textMuted: '#607080',
+    toolbarBg: '#1e1f32',
+    toolbarDark: '#141525',
+    toolbarActive: '#283593',
+    accent: '#42a5f5',
+    errorBg: '#2d1215',
+    errorBorder: '#c62828',
+    errorText: '#ef9a9a',
+    editorBg: '#1a1b2e',
+    editorGutter: '#12131e',
+    editorGutterText: '#607080',
+    editorActiveLine: '#252640',
+    editorActiveGutter: '#2a2b3d',
+    editorCursor: '#e2e8f0',
+    editorSelection: 'rgba(66, 165, 245, 0.25)',
+    syntaxComment: '#6a9955',
+    syntaxKeyword: '#ce93d8',
+    syntaxType: '#64b5f6',
+    syntaxVariable: '#e2e8f0',
+    syntaxString: '#ffab91',
+    syntaxNumber: '#4db6ac',
+    syntaxPunct: '#9aa5b4',
+    toolbarText: '#e0e0e0',
+    toolbarBorderAlpha20: 'rgba(255,255,255,0.2)',
+    toolbarBorderAlpha40: 'rgba(255,255,255,0.4)',
+    toolbarSeparator: 'rgba(255,255,255,0.25)',
+};
+export const LIGHT_THEME = {
+    name: 'light',
+    ui: LIGHT_UI,
+    diagram: LIGHT_DIAGRAM,
+    print: LIGHT_DIAGRAM,
+};
+export const DARK_THEME = {
+    name: 'dark',
+    ui: DARK_UI,
+    diagram: DARK_DIAGRAM,
+    print: LIGHT_DIAGRAM,
+};

package/docs/api.adoc

@@ -0,0 +1,196 @@
+= LDL API Reference
+:toc: left
+:toclevels: 2
+:source-highlighter: highlight.js
+
+The `@openpowershift/logic-diagram-language` package turns *LDL* source (see the
+link:user-guide.adoc[User Guide] for the language) into an SVG, and — in the browser — into a PNG or
+PDF. This page documents the programmatic API.
+
+== Installation
+
+[source,sh]
+----
+npm install @openpowershift/logic-diagram-language
+----
+
+The package is ESM-only (`"type": "module"`) and ships type declarations. SVG rendering is
+isomorphic (Node + browser); the PNG/PDF helpers are browser-only.
+
+== Pipeline
+
+[source]
+----
+LDL source ──parse──▶ Diagram ──layoutDiagram──▶ LayoutResult (geometry)
+                          └────── renderDiagram ──▶ SVG string
+----
+
+`renderDiagram` runs the layout internally, so the common path is just `parse` → `renderDiagram`.
+
+== Quick start (SVG)
+
+[source,ts]
+----
+import { parse, renderDiagram, resolveOptions } from '@openpowershift/logic-diagram-language';
+
+const source = `
+  O1.Name = "Trip"
+  I1.Name = "Overcurrent"
+  I2.Name = "Enable"
+  O1 = I1 AND I2
+`;
+
+const { diagram, errors } = parse(source);
+if (errors.length) throw new Error(errors[0].message);
+
+const svg = renderDiagram(
+  diagram,
+  diagram.portMeta,
+  true,                             // showLabels
+  false,                            // showIds
+  resolveOptions(diagram.options),  // options (merges OPTION lines over the defaults)
+);
+// `svg` is a complete <svg>…</svg> string — write it to a file or inject into the DOM.
+----
+
+== Rendering to SVG
+
+[source,ts]
+----
+function renderDiagram(
+  diagram: Diagram,
+  portMeta?: PortMeta[],
+  showLabels?: boolean,       // default true  — draw .Name / .Description labels
+  showIds?: boolean,          // default false — draw bare identifiers (I1, AND#G1, …)
+  options?: RenderOptions,    // default DEFAULT_OPTIONS
+  diagramTheme?: DiagramTheme // default LIGHT_DIAGRAM
+): string
+----
+
+- `diagram` / `portMeta` come from `parse()` (`result.diagram`, `result.diagram.portMeta`).
+- `options` is a fully-resolved `RenderOptions`; build it with `resolveOptions(diagram.options)` so a
+  diagram's own `OPTION` lines are honoured, then override fields as needed.
+- Pass `DARK_DIAGRAM` (or a custom `DiagramTheme`) for a dark render.
+
+Node example writing a file:
+
+[source,ts]
+----
+import { writeFileSync } from 'node:fs';
+import { parse, renderDiagram, resolveOptions } from '@openpowershift/logic-diagram-language';
+
+const { diagram } = parse(source);
+writeFileSync('diagram.svg', renderDiagram(diagram, diagram.portMeta, true, false,
+  resolveOptions(diagram.options)));
+----
+
+== Rendering to PNG (browser)
+
+[source,ts]
+----
+import { parse, renderDiagram, resolveOptions, svgToPngBlob } from '@openpowershift/logic-diagram-language';
+
+const { diagram } = parse(source);
+const svg = renderDiagram(diagram, diagram.portMeta, true, false, resolveOptions(diagram.options));
+
+const pngBlob = await svgToPngBlob(svg, 2);   // 2× the diagram's intrinsic pixel size
+// e.g. download it:
+const url = URL.createObjectURL(pngBlob);
+Object.assign(document.createElement('a'), { href: url, download: 'diagram.png' }).click();
+URL.revokeObjectURL(url);
+----
+
+`svgToPngBlob(svg, scale = 2)` rasterises the SVG onto a white `<canvas>` at `scale`× and returns a
+PNG `Blob`. Browser only (needs `DOMParser`, `Image`, `<canvas>`).
+
+== Rendering to PDF (browser)
+
+[source,ts]
+----
+import { svgToPdfBlob } from '@openpowershift/logic-diagram-language';
+
+const pdfBlob = await svgToPdfBlob(svg);       // single page sized to the diagram
+----
+
+`svgToPdfBlob(svg, scale = 2)` returns a one-page PDF `Blob` sized to the diagram (orientation follows
+the aspect ratio). It loads `jspdf` on demand, so it is not pulled into your bundle unless used.
+Browser only.
+
+TIP: In Node, render the SVG with `renderDiagram` and convert it with a server-side rasteriser such as
+`@resvg/resvg-js`, `sharp`, or a headless browser.
+
+== Options
+
+Resolve a diagram's `OPTION` lines into a `RenderOptions`, then override individually:
+
+[source,ts]
+----
+import { resolveOptions, DEFAULT_OPTIONS } from '@openpowershift/logic-diagram-language';
+
+const options = resolveOptions(diagram.options);
+options.inversion = 'BUBBLES';     // override in code
+options.margin = 16;
+----
+
+`resolveOptions(optionDecls)` starts from `DEFAULT_OPTIONS` and applies each `OPTION` declaration.
+Passing `diagram.options` (from `parse`) reproduces exactly what the diagram asked for.
+
+[cols="1m,1,1m",options="header"]
+|===
+| Field | Values | Default
+
+| inversion        | `'GATES'` \| `'BUBBLES'`                              | `'GATES'`
+| portStyle        | `'CIRCLE'` \| `'SQUARE'`                              | `'CIRCLE'`
+| gateInputStyle   | `'EXPAND'` \| `'BARS'`                                | `'EXPAND'`
+| inputOrder       | `'AUTO'` \| `'DECLARATION'`                           | `'AUTO'`
+| outputOrder      | `'AUTO'` \| `'DECLARATION'`                           | `'AUTO'`
+| columnSpacing    | `'ADAPTIVE'` \| `'UNIFORM'`                           | `'ADAPTIVE'`
+| compactness      | `'NORMAL'` \| `'COMPACT'` \| `'COMPACT_V'` \| `'COMPACT_H'` \| `'SPACIOUS'` | `'NORMAL'`
+| compactnessFactors | `[number, number]` (vertical, horizontal)          | —
+| margin           | `number` (px)                                        | `8`
+| wireLabelLeader  | `boolean`                                            | `true`
+| strokeWidth      | `number` (px)                                        | `2.5`
+| hideJunctions    | `boolean`                                            | `false`
+|===
+
+Each field also has an `OPTION` form (e.g. `OPTION INVERSION = BUBBLES`, `OPTION MARGIN = 16`) — see
+the link:user-guide.adoc[User Guide] and link:../spec/spec.adoc[spec] for the source syntax.
+
+== Working with geometry directly
+
+To post-process the layout (custom renderer, measurements, hit-testing) call `layoutDiagram`:
+
+[source,ts]
+----
+import { parse, layoutDiagram, resolveOptions, findWireCrossings } from '@openpowershift/logic-diagram-language';
+
+const { diagram } = parse(source);
+const layout = layoutDiagram(diagram, diagram.portMeta, resolveOptions(diagram.options));
+
+layout.nodes;      // LayoutNode[]  — gates/blocks/inputs/outputs with absX/absY/width/height + ports
+layout.wires;      // LayoutWire[]  — orthogonal point lists, fromId/toId
+layout.junctions;  // LayoutJunction[]
+layout.labels;     // LayoutLabel[] — consumed-intermediate net labels (+ optional leaderX/leaderY)
+layout.width; layout.height;
+
+const crossings = findWireCrossings(layout.wires, layout.junctions); // WireCrossing[]
+----
+
+== Exports
+
+[cols="1m,3",options="header"]
+|===
+| Export | Description
+
+| parse                 | LDL source → `{ diagram, errors }`
+| renderDiagram         | `Diagram` → SVG string (runs layout internally)
+| layoutDiagram         | `Diagram` → `LayoutResult` (geometry only)
+| findWireCrossings     | count/enumerate wire crossings in a layout
+| resolveOptions        | `OptionDecl[]` → fully-resolved `RenderOptions`
+| DEFAULT_OPTIONS       | the default `RenderOptions`
+| svgToPngBlob          | SVG string → PNG `Blob` (browser)
+| svgToPdfBlob          | SVG string → PDF `Blob` (browser)
+| LIGHT_DIAGRAM, DARK_DIAGRAM | built-in `DiagramTheme` values
+| EXAMPLES, EXAMPLE_NAMES | map of example name → LDL source, and its keys
+| _types_               | `RenderOptions`, `Diagram`, `LayoutResult`, `DiagramTheme`, … (see `index.d.ts`)
+|===

package/docs/ldl-for-llms.md

@@ -0,0 +1,163 @@
+# Authoring LDL — a guide for AI agents
+
+This is a **self-contained, implemented-only** reference for generating LDL (Logic Diagram Language)
+source. Prefer it over the full [spec](../spec/spec.adoc): the spec is a formal grammar that also
+describes *reserved but not-yet-implemented* features. Everything below renders today.
+
+Give an end user a diagram by emitting an LDL file and rendering it with
+`@openpowershift/logic-diagram-language` (`parse` → `renderDiagram`, see [api.adoc](api.adoc)).
+
+## Mental model
+
+- An LDL file is a list of **assignments** `NAME = <expression>`. The renderer lays everything out
+  automatically — you never specify coordinates.
+- A name **consumed** in another expression becomes a shared internal signal (it fans out). A name
+  **not** consumed anywhere becomes a diagram **output** (drawn on the right). Boundary names that are
+  only ever *read* become **inputs** (drawn on the left).
+- So: to make `X` an output, don't reference it elsewhere. To force an intermediate to also render as
+  an output, add `X.OUT = TRUE`.
+
+## Core syntax (all implemented)
+
+```ldl
+// comment to end of line
+
+O1 = A AND B OR NOT C          // operators: AND, OR, NOT  (precedence: NOT > AND > OR)
+O2 = A AND (B OR C)            // parentheses group
+INT = A AND B                  // INT is consumed below -> internal signal (not an output)
+O3 = INT OR D
+
+// Labels & descriptions (identifiers stay the machine name; labels are display text)
+A.Name = "Overcurrent"
+A.Description = "50P1 pickup"
+O1.Name = "Trip"
+
+// Inline TeX math in any label with $...$
+IA.Name = "$I_a > I_{pickup}$"
+
+// Force an internal signal to ALSO be drawn as an output
+INT.OUT = TRUE
+```
+
+### Operators
+
+Only **`AND`**, **`OR`**, **`NOT`** exist. `NAND`, `NOR`, `XOR`, `XNOR` are **not implemented** —
+express them the long way (e.g. NAND → `NOT (A AND B)`).
+
+### Named gates
+
+Give a specific gate an id (so it can be labelled or CSS-styled) with `GATE#ID(...)`:
+
+```ldl
+TRIP = AND#G1(A, B, C)
+G1.Name = "Trip AND"
+```
+
+### Function blocks (SEL-style)
+
+```ldl
+T   = TIMER(IN, 2cyc, 5cyc)      // TIMER(input, pickup, dropout); durations: 2cyc, 30cyc, 3s, 0
+L   = SR(SET, RESET)             // SR latch (default output Q). For the inverted output: SR(SET, RESET).NQ
+E   = RISING(A)                  // rising-edge  (FALLING(A) for falling)
+C   = COMPARE(IA, IPICKUP)       // comparator: + over -, outputs true when IA > IPICKUP
+// Generic block with named ports and a selected output port:
+P50 = FB#E50P1(I = IPH, TC = NOT BLK).T
+E50P1.Name = "50P1"
+E50P1.Description = "DT 4.8 x In, 0.02 s"
+```
+
+- Reference a block's output port with `.PORT` (e.g. `.Q`, `.NQ`, `.T`). Default port if omitted.
+- Reuse a block instance by id: `SR#L1(...)` used twice refers to the same latch.
+
+### Feedback / seal-in
+
+If a name appears **inside its own definition**, that reference is drawn as a loop-back wire (a latch
+holding itself in) rather than a new input:
+
+```ldl
+SEAL = (PICKUP OR SEAL) AND NOT RESET   // SEAL feeds back into itself
+```
+
+### Options
+
+Put `OPTION` lines at the top. Implemented options and defaults:
+
+| Option | Values (default first) |
+| --- | --- |
+| `INVERSION` | `GATES`, `BUBBLES` |
+| `PORT_STYLE` | `CIRCLE`, `SQUARE` |
+| `GATE_INPUT_STYLE` | `EXPAND`, `BARS` |
+| `INPUT_ORDER` | `AUTO`, `DECLARATION` |
+| `OUTPUT_ORDER` | `AUTO`, `DECLARATION` |
+| `COLUMN_SPACING` | `ADAPTIVE`, `UNIFORM` |
+| `COMPACTNESS` | `NORMAL`, `COMPACT_V`, `COMPACT_H`, `COMPACT`, `SPACIOUS`, or `70,70` |
+| `MARGIN` | integer px (default `8`) |
+| `WIRE_LABEL_LEADER` | `TRUE` (default), `FALSE` |
+| `STROKE_WIDTH` | number px (default `2.5`) |
+| `HIDE_JUNCTIONS` | `TRUE`, `FALSE` |
+
+```ldl
+OPTION INVERSION = BUBBLES
+OPTION MARGIN = 16
+```
+
+### Styling (optional)
+
+```ldl
+STYLE
+  #G1 path { fill: #ffecec; }              // a gate body by its id (target the shape, e.g. path/rect)
+  .ldl-wire[data-to="TRIP"] { stroke: #c62828; stroke-width: 4; }
+END STYLE
+```
+
+## Do NOT use (reserved but not implemented — they will not render)
+
+`NAND` / `NOR` / `XOR` / `XNOR` operators · `CONNECT` · custom `SYMBOL` definitions ·
+`IMPORT` / `STYLESHEET` · hyperlinks / `.LINK` · `.Style` attribute · `BIDI`.
+
+## Complete worked examples
+
+Simple trip logic:
+
+```ldl
+I1.Name = "Overcurrent"
+I2.Name = "Block"
+O1.Name = "Trip"
+O1 = I1 AND NOT I2
+```
+
+Overcurrent with seal-in latch and a trip timer (SEL-style):
+
+```ldl
+OPTION INVERSION = BUBBLES
+
+A    = SR#L1(COMPARE(IA, IPICKUP), RESET)   // comparator pickup into a seal-in latch (Q output)
+TRIP = TIMER(A, 0, 30cyc)                   // 30-cycle trip delay; TRIP is unconsumed -> an output
+
+IA.Name      = "$I_a$"
+IPICKUP.Name = "$I_{pickup}$"
+RESET.Name   = "Reset"
+TRIP.Name    = "Trip"
+```
+
+Two protection elements ORed to a common trip, one shared blocking signal:
+
+```ldl
+BLK  = HBL2T AND WIN                  // shared internal signal (fans out to both)
+P50  = FB#E50P1(I = IPH, TC = NOT BLK).T
+Q50  = FB#E50Q1(I = IQ,  TC = NOT BLK).T
+TRIP = P50 OR Q50
+
+BLK.Name   = "Inrush block"
+E50P1.Name = "50P1"
+E50Q1.Name = "50Q1"
+TRIP.Name  = "Trip"
+```
+
+## Checklist before returning a file
+
+1. Only `AND` / `OR` / `NOT` operators (rewrite any NAND/NOR/XOR/XNOR).
+2. `OPTION` lines first, then assignments.
+3. Every signal that should be an **output** is not referenced elsewhere (or has `.OUT = TRUE`).
+4. Labels via `.Name` / `.Description`; wrap math in `$...$`.
+5. Validate by rendering: `parse(src).errors` must be empty.