@openpowershift/logic-diagram-language 0.1.0

package/spec/sections/layout-rules.adoc

@@ -0,0 +1,491 @@
+== Layout Rules
+
+The renderer MUST follow these layout rules to produce clear, non-overlapping diagrams.
+
+[#visual-quality]
+=== Visual Quality Objectives
+
+A diagram is "visually good" when an engineer can trace every signal at a glance. The
+renderer optimises for the following objectives, in roughly this priority order, and the
+detailed rules in the rest of this section exist to serve them:
+
+. **Left-to-right signal flow.** Inputs on the left, outputs on the right, gates in columns
+  ordered by their dependency depth. A reader's eye always moves one way.
+. **Connected and unambiguous.** Every port is wired to exactly what it should be; tap-off
+  (fan-out) points are marked with a junction dot; crossings without a dot are never
+  connections.
+. **Few crossings.** Wires cross as little as possible. Nodes within a column are ordered to
+  minimise crossings (see <<row-optimisation>>). Some crossings are topologically
+  unavoidable and are accepted.
+. **Straight, low-bend wires.** A wire is a straight line wherever its endpoints align, and
+  otherwise a single clean Z (one vertical run, at least `MIN_DOGLEG` tall). Small jogs are
+  never produced.
+. **Aligned gates.** A gate is positioned vertically at the centre of the signals it
+  connects — both the sources feeding it and the destination it drives — so its wires are
+  as short and straight as possible (see <<coordinate-assignment>>). A single-input gate
+  (e.g. NOT) is placed in line with its source and sink.
+. **Even spacing, no overlap.** Gate bodies never overlap; ports within a gate keep a
+  uniform gap; parallel wires keep clear of one another and of gate bodies.
+. **Symmetry and balance.** Fan-in and fan-out are arranged symmetrically about the gate
+  they serve.
+. **Compact but not cramped.** The diagram is as small as it can be without violating the
+  spacing rules, giving a readable aspect ratio.
+. **Stable and fast.** Layout is deterministic (the same source always yields the same
+  diagram) and fast: well under 0.5 s for medium diagrams and under 1 s for large ones.
+  Routing tries cheap deterministic routes (straight line, then a clean Z) before falling
+  back to grid-based pathfinding, so cost scales with diagram complexity, not canvas size.
+
+=== Column Assignment
+
+Gates are assigned to columns based on their depth in the expression tree:
+
+* **Column 0**: Input ports (leftmost).
+* **Column N**: Output ports (rightmost).
+* **Intermediate columns**: Gates at depth *d* are placed in column *d*.
+
+Outputs of a gate at column *c* align horizontally with the inputs of gates at column *c+1*. The renderer MUST NOT introduce horizontal doglegs (jogs) in a wire between a gate output and a downstream gate input unless there is an obstruction requiring it.
+
+=== Vertical Alignment
+
+* Gate inputs MUST be vertically spaced so that each input sits on the same vertical grid row as its upstream source.
+* When multiple inputs connect to the same source, they implicitly fan out. Fan-out wires MUST be spaced apart vertically so they do not overlap.
+* Horizontal wire segments MUST NOT overlap. If two horizontal wires would occupy the same row, the renderer MUST increment the row of one wire to resolve the conflict.
+* A horizontal wire passing above or below a gate body (one it does not connect to) MUST keep a clear vertical gap of at least **2x the wire gap** off the gate's top/bottom edge, so it never looks crammed against the body. The wire's own source/destination gate is exempt (it connects there). The router keeps the larger clearance vertically while keeping the normal (smaller) clearance horizontally, so fan-in channels just left of a gate are unaffected.
+* Adjacent gate bodies in the same column MUST keep a minimum vertical gap (the protected zone, see the pipeline). When a gate is pushed apart to satisfy this, the small offset added to its wires is kept >= `MIN_DOGLEG` so they stay clean Z-routes.
+
+[#row-optimisation]
+==== Row Optimisation (Sugiyama Barycentre Method)
+
+Input nodes are initially assigned rows in natural sort order (I1, I2, ..., I10). When `OPTION INPUT_ORDER = AUTO` (the default) the renderer MUST then apply the Sugiyama barycentre crossing-minimisation algorithm to reorder input nodes so that wires between levels cross as little as possible. When `OPTION INPUT_ORDER = DECLARATION` the inputs keep their natural-sorted order and only the gate rows are propagated from it.
+
+The algorithm iterates up to 3 times:
+
+. For each input node, compute its barycentre: the average row position of all gates that reference it as an input.
+. Sort the input nodes by their barycentre values.
+. Re-assign sequential row indices (0, 1, 2, ...) based on the sorted order.
+. Recompute the row positions of gates at deeper depths using `(minRow + maxRow) / 2` of their inputs.
+
+Gate row positions are NOT compressed within depth groups — each gate stays at the barycentre of its inputs, even if this leaves gaps between gates at the same depth. This ensures gates are visually close to their inputs.
+
+[#coordinate-assignment]
+==== Coordinate Assignment (Two-Sided Alignment)
+
+Ordering (above) only fixes the *relative* order of nodes in each column; this step fixes
+their actual vertical positions. A gate should sit at the centre of *all* the signals it
+connects — both the sources feeding its inputs and the destination it drives — not just its
+inputs. Aligning to one side only (inputs) is what leaves a gate offset from its consumer
+and forces needless bends (e.g. a NOT pushed up away from the output it feeds).
+
+The renderer therefore performs alternating alignment sweeps after the initial barycentre
+ordering:
+
+. **Downward sweep** (sources → sinks): position each gate/output at the median Y of the
+  nodes feeding it.
+. **Upward sweep** (sinks → sources): nudge each gate toward the median Y of the nodes it
+  drives.
+
+Each sweep preserves the column ordering and enforces a minimum vertical separation between
+adjacent nodes in a column (so nodes never overlap). A few iterations converge to a stable
+assignment in which most wires are straight and the rest are clean single-bend Z-routes.
+This is a lightweight form of the priority/median coordinate-assignment methods used in
+layered graph drawing, chosen for speed.
+
+[#input-reordering]
+==== Gate Input Port Assignment
+
+Within each gate, input ports MUST be assigned to source signals in ascending order of source Y position. The source with the smallest Y connects to the topmost input port, and the source with the largest Y connects to the bottommost input port.
+
+=== Layout Pipeline
+
+The renderer does not produce a single layout; it produces several **candidate** layouts and keeps
+the one that measures best on the real rendered geometry (see <<crossover-minimisation>>). Each
+candidate is a full, independent layout over two orthogonal dimensions — input **ordering**
+(`heuristic` / `crossmin`) and long-edge **lane packing** (loose / tight) — ranked lexicographically
+by *fewest sub-min doglegs, then crossings, then bends, then height*. The loose-heuristic candidate is
+always generated and is always dogleg-free, so the winner can never be worse than it on any of those.
+A final cosmetic symmetry pass (small-gate fan-in doglegs mirrored) is applied to the winner, fully
+validated so it can never add a crossing or crowd.
+
+Within a single candidate, all gate position adjustments MUST be completed before wire routing begins,
+so wire obstacle data (gate bounding boxes) reflects the final gate positions. A candidate executes in
+this order:
+
+. Row **ordering** (barycentre + contiguity, or the `crossmin` optimiser) — REAL nodes only.
+. Long-edge **lane reservation**: every edge spanning more than one column is decomposed into a chain
+  of thin dummy nodes so coordinate assignment reserves a clear vertical lane for it. Under tight
+  packing, adjacent dummy lanes pack at `MIN_DOGLEG` rather than the full column channel (a lane next
+  to a real gate always keeps the full channel, so gates never shift toward a lane).
+. **Coordinate assignment**: a joint per-column optimiser (weighted isotonic regression / PAVA) aligns
+  each node to the port-aware mean of its neighbours on both sides, iterated to convergence. This
+  replaces the old greedy median sweeps and settles gate heights, fan-in spreading and single-input
+  alignment together. Dummies are then removed.
+. Downstream placement refinements PAVA does not do on its own: gate min-jog placement, dogleg
+  cleanup, a protected minimum gap between adjacent gate bodies, and output placement.
+. **Wire routing** (obstacle-aware A* fan-out), then the reshaping passes: channel-track assignment,
+  multi-input fan-in channels (<<fan-in-channels>>), obstacle-aware output placement
+  (<<output-placement>>) and input un-wrap (<<input-unwrap>>), sub-`MIN_DOGLEG` straightening,
+  feedback routing, shared fan-out trunk merge, and the gate-entrance guarantee (<<gate-entrance>>).
+. **Junction detection**, a final uniform vertical re-normalisation (which shifts every node, wire,
+  junction AND label together so labels never drift from the gates they annotate), and a
+  **blank-band collapse**: any fully-empty horizontal band between two disconnected logic sections
+  (no node, label, or wire — including verticals — crosses it, so the sections share no signal) is
+  reduced to a fixed section gap, removing wasted vertical space. Being a uniform per-section shift
+  over an empty band, it preserves every wire shape and cannot cause an overlap or crossing.
+
+Every reshaping pass validates its proposed geometry through the shared wire-separation contract
+(>= `MIN_WIRE_SPACING` between parallel cross-net segments) plus gate clearance, and reverts any move
+that would add a crossing — so no pass can silently undo another's separation or introduce a crossover.
+
+=== Wire Routing
+
+Every wire MUST be drawn as either a straight horizontal line or a single clean
+**Z-route** (`horizontal → vertical → horizontal`). Wires MUST NOT contain *doglegs* — a
+dogleg is a small or needless jog, defined as a vertical run shorter than `MIN_DOGLEG`
+(30px) sitting between two horizontal segments. Doglegs are avoided primarily at the
+*layout* level (see <<minimum-dogleg-height>>): port Y positions are aligned so the
+natural orthogonal route is already straight or a clean Z.
+
+Wires between ports follow these rules:
+
+. A wire exits a source port horizontally to the right.
+. At a vertical channel between the source column and the destination column, the wire
+  turns vertically and travels to align with the destination port's Y.
+. The wire enters the destination port horizontally. For AND/NOT inputs it enters at the
+  straight bounding-box left edge; for OR inputs it terminates **on the concave curve**
+  (see <<or-curve-ports>>).
+. [[gate-entrance]]**Minimum gate entrance (a guaranteed contract).** When a wire turns into a gate input port,
+  its final horizontal run (the entrance) MUST be at least `GATE_ENTRANCE` (20px) long, so the
+  vertical turn sits clear of the gate body/curve and the wire visibly enters horizontally rather
+  than turning on the gate's edge. Equivalently, a turning wire's vertical channel sits at least
+  `GATE_ENTRANCE` to the left of the port's X. This matters most for OR inputs, whose curve-tap X
+  lies inside the bounding box: without the rule the channel would hug (or fall on) the box's left
+  edge.
++
+This is not left to chance in the routing/reshaping heuristics (which each satisfy it only as a
+side effect and can leave a hug behind — the channel-track pass skips multi-bend wires, and fan-in
+nesting is all-or-nothing). It is *guaranteed* by a dedicated final pass that, for **every**
+gate-input wire, pulls its final turn back to the gate-most clear track that satisfies the contract
+— first trying to draw a wandered-but-collinear wire straight, then a per-wire pull-back, then a
+joint re-pack of all of a gate's incoming channels. Every move is validated through the wire-
+separation contract, gate clearance, and a no-new-crossing check, so it can never introduce a crowd
+or crossing; a move that cannot be made cleanly is left as routed. The guarantee is asserted for
+every example by the `gate-input wires keep the GATE_ENTRANCE approach` invariant. The single
+documented exception is a wire that can only reach a compliant entrance by adding a crossing (a
+middle input whose straight line is occupied by another net): there the shorter approach is kept,
+because crossing-minimisation outranks entrance — a *placement* over-constraint, not a routing gap.
+
+[#feedback-loops]
+=== Feedback (Loop-Back) Wires
+
+When an output name is used inside its own definition (directly or transitively) — a
+self/cyclic reference such as a seal-in latch `Q = SET OR (Q AND NOT RESET)` — it MUST NOT
+be added as a new input. Instead it loops back: the output's signal feeds back into the gate
+that consumes it. The feedback shares the output's driving signal (it taps the gate that
+drives the output) and is routed by the obstacle-aware pathfinder as a local loop around the
+gates — not a fixed full-width lane. The loop keeps a clear distance (at least 3x the wire
+gap) off the driver output and the consumer input, and it enters the consumer on the side it
+approaches from (over the top → top input port; under the bottom → bottom input port),
+whichever gives fewer crossings. Feedback wires are exempt from the left-to-right flow and
+no-backward-segment rules (they are loops by nature). A forward reference to an
+*already-defined* output is not a feedback edge.
+. When the source and destination Y differ by less than 1px, the wire MUST be a straight
+  horizontal line with no vertical segment.
+. Wires MUST NOT backtrack; a vertical segment's X MUST be >= the source port's X + 15px.
+. Every node position, port Y position, and wire vertex MUST align to the 5px grid (the OR
+  input-port X, which taps the curve, is the sole exception). Every wire segment MUST be
+  exactly horizontal or vertical — no diagonal segments.
+
+The renderer uses A* pathfinding on the 5px grid to realise these routes around obstacles:
+
+. Gate bodies are impassable obstacles with a 20% buffer zone. Only the source and
+  destination gates of a wire are routable through; all other objects block routing.
+. The cost model penalises wire–wire crossings, wrong-side gate entry (entering to the
+  right of a gate input port), and direction changes, so paths avoid crossovers, enter
+  gates from the left, and have minimal bends (a straight line or a single Z).
+. Previously-routed wires are obstacles. A horizontal segment MUST NOT run along or cross
+  a vertical segment of a different source, and vice versa, unless unavoidable.
+. Parallel wire segments MUST be separated into distinct tracks with a minimum spacing of
+  `MIN_WIRE_SPACING` between adjacent parallels, so bundles remain individually legible.
+  The renderer favours readability (wider channels) over compactness.
+
+[#minimum-dogleg-height]
+==== Minimum Dogleg Height (`MIN_DOGLEG`)
+
+When a wire must dogleg (its source Y differs from its target port Y), the vertical segment of the dogleg MUST be at least `MIN_DOGLEG` (30px) tall. Doglegs shorter than `MIN_DOGLEG` are visually ambiguous and MUST be avoided.
+
+The renderer enforces this by:
+
+. **Position optimisation**: Shifting gates vertically to align ports with their sources (eliminating doglegs entirely) or ensuring at least `MIN_DOGLEG` of vertical distance.
+. **Dogleg enforcement**: After position optimisation, any remaining small dogleg (where `0 < |sourceY - portY| < MIN_DOGLEG`) triggers a gate height expansion for that specific port, placing it at the source Y position (straight-through) or at source Y ± MIN_DOGLEG (minimum-height dogleg).
+
+A dogleg of 0px (source Y matches target Y exactly) is a straight-through wire and is always acceptable.
+
+[#gate-sizing-principle]
+==== Gate Sizing Principle
+
+A gate's body height is a function of its *port count only* — it grows to give each input port room
+(`MIN_PORT_GAP` between ports plus edge padding), and for **no other reason**. A gate MUST NOT be
+enlarged merely to make far-apart input sources line up with its ports.
+
+When a gate's input sources are spread farther apart than its (port-count-sized) body can span, the
+incoming wires dogleg to reach the ports. Such a dogleg MUST still respect <<_minimum_dogleg_height_min_dogleg,`MIN_DOGLEG`>>
+(a clean Z, never a short jog), and the gate is positioned so the wires are straight where the body
+can reach the source and a clean dogleg otherwise.
+
+NOTE: *Tension with the no-dogleg goal.* For a fixed-height gate, two sources whose separation falls
+between the body's usable inner span and that span plus `MIN_DOGLEG` cannot *both* be reached by a
+straight or clean-`MIN_DOGLEG` wire — one wire is forced into the sub-`MIN_DOGLEG` band. The only
+ways to make both wires clean are (a) grow the gate (violates this principle), or (b) reposition the
+upstream *inputs* so their outputs align with the compact gate's ports (*gate-aware input placement*).
+The latter is the correct resolution: gate size stays port-count-driven and the inputs, which have
+free vertical slots in the input column, move to align. Until gate-aware input placement lands, the
+renderer expands the gate as a stopgap (see <<gate-height-adjustment>>) — a known deviation from this
+principle, tracked in `IMPLEMENTATION.md`.
+
+[#gate-height-adjustment]
+==== Gate Height Adjustment (current stopgap)
+
+When a multi-input gate (AND, OR) has input ports that are close to their upstream source Y positions, the gate height is expanded so that the input ports align with their sources. This eliminates small doglegs on incoming wires. (This expansion is the stopgap noted in <<gate-sizing-principle>>; the target behaviour keeps the gate at its port-count height and instead aligns the inputs.)
+
+The algorithm:
+
+. Sort the gate's input sources by their output Y position (ascending).
+. Compute ideal port Y positions, enforcing a minimum vertical gap (`MIN_PORT_GAP` = 22px) between adjacent ports.
+. Calculate the required gate height to contain all ideal ports with top and bottom padding of `MIN_PORT_GAP`.
+. If the required height does not exceed the base gate height by more than `MIN_PORT_GAP × numInputs`, expand the gate and place ports at their ideal Y positions.
+. If the expansion would be too large (sources span many rows), the gate keeps its base evenly-spaced ports.
+
+For gates that were not expanded, a position optimisation pass shifts the gate vertically (within ±`MIN_DOGLEG`) to minimise doglegs. The optimisation uses a weighted score:
+
+* A wire where source Y matches port Y (|diff| < 1px) scores **0** — this is a straight-through wire, the ideal outcome.
+* A wire where 1px ≤ |diff| < `MIN_DOGLEG` scores **(MIN_DOGLEG - |diff|)²** — small doglegs are heavily penalised.
+* A wire where |diff| ≥ `MIN_DOGLEG` scores **0** — large doglegs are visually clear and acceptable.
+
+The optimisation finds the vertical shift that minimises the total score across all input ports of the gate.
+
+For single-input gates (NOT, single-input AND/OR), the entire gate is shifted so that its input port aligns exactly with its source's output Y, producing a straight-through wire with no dogleg.
+
+After all gate position adjustments, output nodes are re-aligned to their source gate outputs to maintain straight-through output wires.
+
+[#straight-outputs]
+==== Output Straight-Through
+
+Output ports SHOULD be positioned so that their input Y aligns with the source gate's output Y, so the wire from a gate to its output port is a straight horizontal line. When two outputs share (or nearly share) a source Y they cannot both be straight; the lower one is pushed down by at least `MIN_DOGLEG` (never a small jog) — see <<output-ordering>>.
+
+[#output-ordering]
+==== Output Ordering
+
+The vertical order of output ports in the final column is controlled by the
+`OUTPUT_ORDER` option:
+
+* `DECLARATION` (default) — outputs are stacked in the order they are declared (O1, O2,
+  …) from top to bottom. Predictable, but output wires may need to cross or dogleg to
+  reach a source on the opposite side.
+* `AUTO` — outputs are reordered by the Y position of the gate that drives them (the same
+  barycentre principle applied to inputs in <<row-optimisation>>). Outputs then stack in
+  the order their wires arrive, so output wires fan out without crossing. Note: AUTO can
+  increase output-column congestion in some diagrams, so it is opt-in rather than default.
+
+In both modes outputs in the same column are placed greedily in the chosen order: each is
+placed at its source Y where possible, otherwise pushed down just enough to clear the
+previous output, with any deviation kept at 0 or `>= MIN_DOGLEG`.
+
+[#or-curve-ports]
+==== OR Gate Curve Ports
+
+The OR gate's left edge is a concave curve that bulges rightward. Unlike the AND gate
+(straight left edge), the OR gate's input ports sit **on the curve**, and incoming wires
+MUST terminate on the curve in all cases — a wire never stops short of, or overshoots, the
+curve.
+
+* For each OR input at grid-aligned Y, the input-port X is the curve's X at that Y
+  (`bbox-left + curveDepth(Y)`). The connecting wire's final point is this curve point.
+* The curve has a fixed maximum depth (`OR_CURVE_DEPTH`, ~10px) independent of the gate
+  height, so the concavity reads consistently regardless of the number of inputs or the
+  gate's expanded height.
+* The gate's **bounding box, right-edge output port, and every port Y position MUST stay
+  on the 5px grid**. Only the input-port X (the curve tap) is exempt, since it follows the
+  curve.
+
+[#common-subexpression-sharing]
+==== Common Subexpression Sharing
+
+The renderer MUST deduplicate structurally identical subexpressions into a single gate node. Two subexpressions are structurally identical if they have the same gate type and the same set of resolved input IDs after sorting inputs for commutative operators (AND, OR).
+
+When multiple outputs reference the same logical subexpression, the renderer MUST create one gate node and route wires from that node's output to all downstream consumers. This prevents overlapping gate nodes at identical positions and redundant wire routing.
+
+Example:
+
+[source]
+----
+O1 = A AND B
+O4 = NOT (A AND B)
+----
+
+The subexpression `A AND B` is referenced by both O1 and O4. The renderer MUST create a single AND gate for `A AND B` and fan out its output to both O1 and the NOT gate feeding O4, rather than creating two separate AND gates at the same grid position.
+
+For non-commutative operators (NOT) and future derived operators (NAND, NOR, XOR, XNOR), deduplication MUST preserve input ordering. Two expressions are identical only if their inputs appear in the same gate-specific order.
+
+[#symmetric-channels]
+[#fan-in-channels]
+==== Multi-Input Fan-In Channels
+
+When several wires dogleg into the same gate, each gets its own vertical channel just to
+the left of the gate, rather than all crowding into one bundle. The channels are:
+
+* **Evenly spaced** — adjacent channels are `FANIN_SPACING` (15px, the same as the port
+  gap) apart, so the fan-in is never more crowded than the ports it feeds. Because the
+  channels live in the gap immediately left of the gate, this is how the layout keeps a
+  consistent gap without having to physically move the gate further right.
+* **Nested** — wires arriving from above the gate and wires arriving from below are nested
+  independently, with the most extreme source (topmost / bottommost) turning closest to
+  the gate and progressively inner sources turning further left. This is the ordering that
+  is provably crossing-free for a single source column, and it reads symmetrically between
+  the top and bottom halves of the gate.
+* **Obstacle-avoiding** — each wire does not take one fixed channel position; it SEARCHES from its
+  ideal nested channel leftward for the gate-most position that clears all gate bodies (so a wire
+  whose source row is blocked by a gate turns *before* that obstacle instead of the group giving up).
+* **Validated** — a channel is only used if it clears all gate bodies and does not overlap a wire from
+  a different net; a group keeps its routed geometry if any wire finds no valid channel, and the whole
+  group reshape is reverted if it would add a crossing, so the optimisation never introduces a new
+  collision or crossover.
+
+[#output-placement]
+==== Obstacle-Aware Output Placement
+
+An output whose port Y falls inside the vertical shadow of a gate its incoming wire must cross is
+forced to dodge that gate — a down-and-up / up-and-over detour that also tends to land on unrelated
+wires' lines. When this happens the renderer moves the output to the nearest Y clear of every crossed
+gate's shadow and redraws the wire as one clean H–V–H. The move is applied only when a clear position
+and route exist that are strictly simpler (2 bends versus the detour's more) and validate through gate
+clearance, the wire-separation contract, sibling-output spacing, a legal dogleg, and a no-new-crossing
+guard; otherwise it is reverted. So it can only ever simplify a forced detour and never introduces a
+crossing, crowd, overlap, or sub-`MIN_DOGLEG` dogleg.
+
+[#input-unwrap]
+==== Obstacle-Aware Input Un-Wrap
+
+The mirror of output placement, on the source side. A single-consumer input feeds one port of a gate,
+but a sibling block that also feeds that gate — an SR seal-in latch or a sub-`OR` — can sit in the
+horizontal span between them, occupying the input's straight-line Y. The router is then forced to wrap
+that input up-and-over (or through) the block, landing its wire across the block's own I/O (e.g. a
+cross-trip input into a trip `OR`, wrapped over the seal-in `SR`, crossing both the latch's `Q`-out and
+its set/reset-in). When this happens the renderer moves the input's *source* Y to the near outer edge of
+that shadow and redraws the wire as one clean H–V–H entering the fixed port from the correct side. It
+searches source Ys outward from the port and keeps the fewest-crossing fully-clear route — a partial
+un-wrap that merely lands on the block's other input wire is not the target. Because only that one wire
+moves, its own crossing count is the exact whole-diagram delta, so the move is kept only when it
+strictly reduces crossings and validates through gate clearance, the wire-separation contract,
+sibling-input spacing, and a legal dogleg; otherwise it is reverted. So it can only ever remove a wrap
+crossing and never introduces a crossing, crowd, overlap, or sub-`MIN_DOGLEG` dogleg.
+
+[#fan-out-dots]
+==== Fan-Out Junction Dots
+
+When one source drives several destinations, sibling branches whose vertical channels fall
+within `FANIN_SPACING` of each other SHOULD share a single trunk channel (same-source
+overlap is intended and reads as one trunk). A connection point is marked with a junction
+dot at each true T-intersection; junction dots within a few pixels of each other are merged
+into one so a split reads as a single clean dot rather than a cluster.
+
+[#crossover-minimisation]
+==== Crossover Minimisation
+
+Crossing count is a *measured optimisation objective*, not a side-effect of ordering heuristics. The
+renderer generates more than one candidate layout and keeps the one that measures best on the drawn
+geometry — because the classic combinatorial layer-crossing count diverges from the crossings actually
+drawn once gate heights, multi-port entry and routing doglegs are taken into account. Candidates span
+two orthogonal dimensions: input **ordering** — `heuristic` (barycentre + contiguity — always a
+candidate, so the result can never be worse than it) and `crossmin` (a Sugiyama median/transpose
+optimiser on a dummy-expanded layered graph, port-aware so fixed-port blocks stay uncrossed) — and
+long-edge **lane packing** (loose / tight, see the pipeline). The winner is chosen lexicographically by
+**fewest sub-min doglegs, then fewest crossings, then fewest bends, then smallest height**. Because the
+loose-heuristic candidate is always present and always dogleg-free, the winner never has more doglegs
+or crossings than it; a tighter/alternate candidate wins only when it strictly improves. Candidates
+beyond loose-heuristic are computed lazily (e.g. `crossmin` only when `heuristic` is not already
+crossing-free), keeping the common case cheap.
+
+Ordering constraints the candidates honour: a **fixed-port block's** sources are ordered to match its
+port order (S above R, …) so its inputs never cross; each gate's single-consumer inputs stay
+**contiguous** so a large fan-in enters straight; a reconvergent gate settles between its inputs and
+consumers so its outputs don't dogleg back across another gate's fan-out.
+
+Rendered crossings per diagram MUST NOT exceed a recorded **ceiling** (guarded by the test suite);
+most diagrams must render crossing-free, and lowering a ceiling is a reviewed improvement. When wires
+from opposite sides of a gate converge, the renderer assigns channel positions to minimise crossings.
+
+[#wire-wire-crossings]
+==== Wire-Wire Crossing Avoidance
+
+Wire routing MUST consider previously-routed wires as obstacles. When routing a horizontal segment, the renderer MUST avoid crossing vertical segments of wires from different sources. When routing a vertical segment, the renderer MUST avoid crossing horizontal segments of wires from different sources.
+
+When a crossing is unavoidable (the wire must pass through a region occupied by another wire), the renderer MUST prioritise clean straight-through wires over doglegs — a straight line crossing a vertical segment is visually clearer than a small dogleg crossing the same segment.
+
+[#inversion-bubble-layout]
+==== Inversion Bubble Layout
+
+When `OPTION INVERSION = BUBBLES` is set:
+
+. NOT gates are not placed as separate columns. Instead, the affected port is marked with a bubble.
+. The wire from the NOT's source connects directly to the bubbled port.
+. The inversion bubble MUST sit fully **outside the gate body, just to the left of the gate
+  edge**, in reserved horizontal space between the incoming wire and the gate. It MUST NOT
+  overlap the gate body.
+. **Input-side bubbles**: When a NOT operation feeds into a gate input, the bubble's inner
+  (right) edge touches the gate edge — the straight bounding-box left edge for AND/NOT, or
+  the **curve tap point** for OR — and the incoming wire terminates at the bubble's outer
+  (left) edge. Layout reserves space so the bubble does not collide with the gate body or
+  the curve.
+. **Output-side bubbles**: When a NOT operation wraps a gate's output, the bubble sits just
+  right of the gate's right edge; the bubble's left edge touches the gate body and the wire
+  starts from the bubble's right edge.
+. **Output node bubbles**: When a NOT operation feeds directly into an output node, the
+  bubble sits just left of the output node's input port, like a gate input-side bubble.
+. The bubble does not affect the vertical position of any port -- Y positions are computed as normal.
+. The NOT gate's column is eliminated, and the source signal is treated as if it directly connects to the target port (with inversion). This reduces the total column count when many NOT operations are present.
+
+===== Double-Inversion Cancellation
+
+Consecutive `NOT` operations are algebraically simplified before bubble placement:
+
+* An even number of consecutive `NOT` operations cancels entirely. No bubble is rendered, and the source signal connects directly without inversion.
+* An odd number of consecutive `NOT` operations reduces to a single inversion, rendered as one bubble.
+
+Examples:
+
+* `NOT NOT I1` → `I1` (no bubble)
+* `NOT NOT NOT I1` → `NOT I1` (one bubble)
+
+[#input-bar-layout]
+==== Input Bar Layout
+
+When `OPTION GATE_INPUT_STYLE = BARS` is set for a multi-input gate (3+ inputs):
+
+. The gate body height remains the 2-input base height (44px for AND/OR).
+. A vertical bar is drawn 12px to the left of the gate body edge, spanning the full height of the gate body.
+. Bar stroke-width: 2.5px, colour: `#2c3e50`.
+. The first two inputs render as normal ports at their usual positions on the left side of the gate body.
+. Additional inputs (3rd, 4th, ...) tap into the vertical bar at evenly-spaced Y positions within the gate body bounds.
+. Each bar tap has a short horizontal stub (6px) from the bar to the gate edge.
+. Wires from source signals connect at the left end of the bar tap stubs.
+. Wire routing treats the bar + stubs as part of the gate bounding box for obstacle avoidance.
+. Row optimisation, gate height adjustment, position optimisation, and dogleg enforcement all apply to bar input ports the same as regular input ports.
+
+=== Layer Visibility
+
+The rendered diagram supports multiple *layers* that can be independently shown or hidden:
+
+[cols="1m,3m,2m"]
+|===
+| Layer | Content | Default
+| `gates` | Gate bodies, wires, and port markers | Visible
+| `labels` | `.Name` and `.Description` text on input and output ports | Visible
+| `ids` | Bare identifiers (e.g. `I1`, `O1`) when labels layer is hidden, or as supplementary identifiers | Hidden
+|===
+
+Layers are toggled via CSS classes on the root `<svg>` element:
+
+* `ldl-layer-labels` -- controls visibility of `.ldl-label` elements.
+* `ldl-layer-ids` -- controls visibility of `.ldl-id` elements.
+
+When the labels layer is active, `.ldl-label` elements are visible and `.ldl-id` elements are hidden by default. When the labels layer is inactive, `.ldl-id` elements are shown as the primary reference.

package/spec/sections/lexical-conventions.adoc

@@ -0,0 +1,68 @@
+== Lexical Conventions
+
+=== Character Set
+
+LDL source files are UTF-8 text.
+
+=== Keywords
+
+The following keywords are reserved and MUST NOT be used as identifiers:
+
+[cols="1m,1m,1m,1m,1m,1m"]
+|===
+| AND | OR | NOT | NAND | NOR | XOR
+| XNOR | IMPORT | SYMBOL | PORT | INPUT | OUTPUT
+| BIDI | ATTRIBUTE | TEMPLATE | LINK | AS | FROM
+| OPTION | STYLE | END | STYLESHEET | CONNECT |
+|===
+
+=== Identifiers
+
+An identifier is a sequence of letters, digits, and underscores, beginning with a letter or underscore.
+
+[literal]
+....
+IDENTIFIER := [a-zA-Z_][a-zA-Z0-9_]*
+....
+
+=== Literals
+
+[cols="2m,3m,2m"]
+|===
+| Kind | Syntax | Example
+| Integer | `[0-9]+` | `30`
+| Float | `[0-9]+\.[0-9]+` | `1.5`
+| String | `"..."` | `"Main Trip"`
+| Math String | `"..$..$.."` | `"Phase $I_a$ current"`
+| Duration | `<number> <unit>` | `30 s`, `100 ms`
+| Boolean | `TRUE` \| `FALSE` | `TRUE`
+|===
+
+Duration units: `ms` (milliseconds), `s` (seconds), `m` (minutes).
+
+=== Comments
+
+A line comment begins with `//` and extends to end of line.
+
+[literal]
+....
+// This is a comment
+....
+
+A block comment begins with `/*` and ends with `*/`. Block comments nest.
+
+[literal]
+....
+/* This is a
+   block comment */
+....
+
+=== Math Delimiters
+
+Within string-valued attributes (`.Name` and `.Description`), TeX math notation is enclosed in dollar signs:
+
+* `$...$` -- Inline TeX math expression.
+* Inside math content, `\$` renders as a literal dollar sign (TeX syntax).
+* Outside math content, `\\$` in LDL source produces `\$`, which the segment parser treats as a literal dollar sign.
+
+Math delimiters are not recognized in expression code, only in quoted string attribute values.

package/spec/sections/objects.adoc

@@ -0,0 +1,31 @@
+== Objects
+
+An *object* is an instance of a symbol. Every gate and composite element in a diagram is an object.
+
+=== Object Declaration
+
+An object is declared by referencing its symbol type, optionally with an identifier:
+
+[literal]
+....
+SYMBOL_NAME#ID
+....
+
+[cols="2m,5m,3m"]
+|===
+| Part | Meaning | Required
+| `SYMBOL_NAME` | The symbol type | Yes
+| `#ID` | A unique identifier for CSS targeting and cross-reference | No
+|===
+
+If `#ID` is omitted, the renderer assigns an anonymous identifier.
+
+=== Examples
+
+[literal]
+....
+AND#G1
+NOT#INV3
+SVT#1
+TIMER#T2
+....