grid-router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geptyro
+
+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 @@
+# grid-router
+
+Orthogonal edge routing on a grid for node-link diagrams: A\* with
+per-direction cell occupancy, Steiner-style bus joins, and crossing "hops".
+Framework-free core + an optional Svelte 5 canvas where **the consumer owns
+the chips**.
+
+## Concepts
+
+- **Grid & occupancy** — the canvas is rasterized into square cells
+  (`res`, default 12px). Node boxes (inflated by `BOX_INFLATE`) hard-block
+  cells. Each free cell can host **one horizontal and one vertical** run;
+  same-direction reuse by another bus is practically prohibited, perpendicular
+  crossings pay a small toll. Lanes separate themselves; crossings happen only
+  where they're worth it.
+- **Buses & joins** — edges sharing `(source, bus)` form a bus. Later edges of
+  a bus seed their search from every cell the bus already routed (cost ~0), so
+  branches leave the trunk at the optimal point. `exitCost` prices opening a
+  *new* trunk out of a source: raise it to force merges even over shorter
+  direct paths.
+- **Endpoints are exclusive** — two buses never share a start/goal cell, so
+  stubs and arrowheads never stack.
+- **Nothing is dropped** — if a dense node row walls the grid off, a desperate
+  pass routes through obstacles at a huge cost and the result counts it in
+  `violations`. **`violations > 0` is a layout problem, not a router bug**:
+  the layout does not supply enough corridor space.
+- **Corridor supply** — `corridorGaps(res)` returns the empirically-validated
+  minimum `rowGap` / `chipGap` / `sidePad` the *layout* must provide so that
+  routing stays violation-free. A chip gap must fit one aligned free cell
+  column (`2·res + 2·inflate`); side padding keeps the outer columns routable.
+- **Hops** — crossings are disambiguated without geometry: each bus paints a
+  background-colored halo under its paths, cutting a small gap into every bus
+  drawn before it (the cut line reads as tunneling under). Per-bus grouping
+  keeps a bus's own T-junctions intact.
+- **Cost layers** — the router is deliberately agnostic of higher-level layout
+  concepts (lanes, sections, keep-out zones). `opts.costRegions` lets the
+  consumer express them anyway: rects with a per-cell `bias` — positive repels
+  routes, negative attracts them (e.g. a "lanes layer" biasing its corridors
+  negative). The step cost is floored, so negative biases are safe.
+- **Port constraints** — `opts.nodeSides` restricts which box sides a node's
+  edges may attach to (schematic pins, side-anchored UML). For POSITIONED
+  named ports, register tiny pad elements at the pin locations as their own
+  nodes (`mcu:pb0`) and connect edges to those — the body registers separately
+  as a pure obstacle (see the circuit example); small boxes are first-class.
+- **Pre-built layers** — `withLayers(base, portsLayer(…), keepOutLayer(…),
+  corridorLayer(…))` composes declarative routing facts into opts; falsy
+  entries are skipped so layers toggle inline
+  (`withLayers(base, zoneOn && keepOutLayer([zone]))`).
+
+## Core API (framework-free)
+
+```ts
+import { routeGrid, corridorGaps } from 'grid-router';
+
+const result = routeGrid(
+  boxes,   // Map<string, GridBox> — measured node rects (t/b/l/r/cx/cy)
+  edges,   // { id, source, target, bus?, data? }[]
+  width,   // routable canvas size in px
+  height,
+  { res: 12, costOwn: 0.02, costTurn: 1, exitCost: 0 } // defaults shown
+);
+// result.conns: { id, source, target, bus, data, d /* SVG path */ }[]
+// result.violations: number (0 = clean; see corridorGaps)
+// result.bottom, result.debug (occupancy cells for overlays)
+```
+
+## Svelte canvas
+
+The component draws **only connectors**. You lay out arbitrary chip markup in
+the default snippet and tag each connectable element with the provided
+`register` action; chip events stay on your own DOM. Size the component's
+container with CSS — it measures itself (no width/height props).
+
+```svelte
+<script lang="ts">
+  import { GridDiagram, type GridConn } from 'grid-router/svelte';
+
+  let hovered = $state<string | undefined>();
+  const edges = [{ id: 'e1', source: 'a', target: 'b', bus: 'ok', data: { tone: 'ok' } }];
+</script>
+
+<GridDiagram
+  {edges}
+  opts={{ res: 12 }}
+  connStyle={(c) => ({
+    color: (c.data as { tone?: string })?.tone === 'ok' ? '#3fb950' : '#8b94a1',
+    dashed: false,
+    arrowAt: 'end',
+    class: hovered && hovered !== c.id ? 'dim' : ''
+  })}
+  onconnenter={(c) => (hovered = c.id)}
+  onconnleave={() => (hovered = undefined)}
+  onrouted={({ violations, ms }) => console.log(violations, ms)}
+>
+  {#snippet children(register)}
+    <div class="my-layout">
+      <div use:register={'a'}>chip A</div>
+      <div use:register={'b'}>chip B</div>
+    </div>
+  {/snippet}
+</GridDiagram>
+
+<style>
+  /* consumer-driven highlight: connStyle classes land on package paths */
+  :global(path.dim) { opacity: 0.15; }
+</style>
+```
+
+Layout contract: use the published CSS vars `--gr-row-gap` / `--gr-chip-gap`
+(from `corridorGaps(res)`) as your row/chip gaps, and set `--grid-diagram-bg`
+to your panel background so crossing hops cut with the right color.
+
+## Examples
+
+```sh
+cd examples && npm install && npm run dev   # http://localhost:5200
+```
+
+- **Electronic circuit** — nets as buses (VCC/GND rails share trunks), no
+  arrowheads (`arrowAt: 'none'`), hover a wire to trace its whole net.
+- **Org chart** — one bus per manager, reporting lines merge; hover a line to
+  light the whole team.
+- **Pipeline + cost layers** — absolutely-positioned left→right DAG; toggle a
+  maintenance keep-out zone (`costRegions`) and watch routes detour, or hit
+  *randomize layout* — chips scatter and the router re-routes live (the
+  `revision` prop triggers re-measure when chips move without resizing the
+  canvas).
+
+## Development
+
+```sh
+npm install
+npm run build   # tsc → dist (core)
+npm test        # vitest
+```
+
+The Svelte entry ships as source (`src/svelte`) and is compiled by the
+consumer's bundler (Vite + svelte plugin resolve the `svelte` export
+condition).

package/dist/corridors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Corridor supply rules — the layout side of the routing contract.
+ *
+ * The router can only use free cells; the LAYOUT decides how many exist. These
+ * formulas are the empirically-validated minimums (violations = 0 across cell
+ * sizes 6–12 on real diagrams):
+ *
+ * - rowGap: a gap between node rows must hold several free horizontal lanes
+ *   after box inflation eats its borders;
+ * - chipGap: a gap between nodes in a row must fit at least one ALIGNED free
+ *   cell column (2·res + 2·inflate), or a dense row walls the grid off;
+ * - sidePad: canvas side padding keeps the outer columns routable so paths
+ *   can go AROUND a row instead of only through it.
+ */
+export interface CorridorGaps {
+    rowGap: number;
+    chipGap: number;
+    sidePad: number;
+}
+export declare function corridorGaps(res: number, inflate?: number): CorridorGaps;

package/dist/corridors.js

@@ -0,0 +1,8 @@
+import { BOX_INFLATE } from './router.js';
+export function corridorGaps(res, inflate = BOX_INFLATE) {
+    return {
+        rowGap: Math.max(34, 4.5 * res),
+        chipGap: Math.max(12, 2 * res + 2 * inflate),
+        sidePad: 1.5 * res
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { routeGrid, BOX_INFLATE, type GridBox, type GridEdge, type GridConn, type GridOpts, type GridResult, type GridDebugCell, type BoxSide } from './router.js';
+export { corridorGaps, type CorridorGaps } from './corridors.js';
+export { withLayers, portsLayer, keepOutLayer, corridorLayer, type Rect, type RouterLayer } from './layers.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { routeGrid, BOX_INFLATE } from './router.js';
+export { corridorGaps } from './corridors.js';
+export { withLayers, portsLayer, keepOutLayer, corridorLayer } from './layers.js';

package/dist/layers.d.ts

@@ -0,0 +1,39 @@
+import type { BoxSide, GridOpts } from './router.js';
+/**
+ * Layers: pre-built, composable producers of declarative routing facts.
+ *
+ * The router core stays agnostic — it only understands two substrates:
+ * per-cell cost bias (`costRegions`) and per-node port constraints
+ * (`nodeSides`). A layer is a small factory that expresses a CONSUMER concept
+ * (keep-out zone, preferred corridor, schematic pins…) in those substrates;
+ * `withLayers` merges any number of them into the opts.
+ *
+ *     const opts = withLayers(
+ *       { res: 12 },
+ *       portsLayer({ r1: ['left', 'right'] }),
+ *       maintenance && keepOutLayer([zoneRect])
+ *     );
+ */
+export interface Rect {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+}
+export interface RouterLayer {
+    costRegions?: NonNullable<GridOpts['costRegions']>;
+    nodeSides?: Record<string, BoxSide[]>;
+}
+/** Merge layers into base opts. Falsy entries are skipped, so layers can be
+ * toggled inline: `withLayers(base, zoneOn && keepOutLayer([zone]))`. */
+export declare function withLayers(base: GridOpts, ...layers: (RouterLayer | false | null | undefined)[]): GridOpts;
+/** Port constraints: which box sides each node's edges may attach to
+ * (schematic pins, UML side-anchoring, …). */
+export declare function portsLayer(sides: Record<string, BoxSide[]>): RouterLayer;
+/** Keep-out zones: routes strongly avoid these rects (they still cross when
+ * there is no alternative — routing never fails). */
+export declare function keepOutLayer(rects: Rect[], bias?: number): RouterLayer;
+/** Preferred corridors: routes are gently attracted into these rects — the
+ * "lanes layer": express your layout's gaps as corridors and buses gravitate
+ * there. Negative bias is floored by the router, so any value is safe. */
+export declare function corridorLayer(rects: Rect[], bias?: number): RouterLayer;

package/dist/layers.js

@@ -0,0 +1,36 @@
+/** Merge layers into base opts. Falsy entries are skipped, so layers can be
+ * toggled inline: `withLayers(base, zoneOn && keepOutLayer([zone]))`. */
+export function withLayers(base, ...layers) {
+    const costRegions = [...(base.costRegions ?? [])];
+    const nodeSides = { ...(base.nodeSides ?? {}) };
+    for (const l of layers) {
+        if (!l)
+            continue;
+        if (l.costRegions)
+            costRegions.push(...l.costRegions);
+        if (l.nodeSides)
+            Object.assign(nodeSides, l.nodeSides);
+    }
+    const out = { ...base };
+    if (costRegions.length)
+        out.costRegions = costRegions;
+    if (Object.keys(nodeSides).length)
+        out.nodeSides = nodeSides;
+    return out;
+}
+/** Port constraints: which box sides each node's edges may attach to
+ * (schematic pins, UML side-anchoring, …). */
+export function portsLayer(sides) {
+    return { nodeSides: sides };
+}
+/** Keep-out zones: routes strongly avoid these rects (they still cross when
+ * there is no alternative — routing never fails). */
+export function keepOutLayer(rects, bias = 40) {
+    return { costRegions: rects.map((r) => ({ ...r, bias })) };
+}
+/** Preferred corridors: routes are gently attracted into these rects — the
+ * "lanes layer": express your layout's gaps as corridors and buses gravitate
+ * there. Negative bias is floored by the router, so any value is safe. */
+export function corridorLayer(rects, bias = -0.4) {
+    return { costRegions: rects.map((r) => ({ ...r, bias })) };
+}

package/dist/router.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Orthogonal edge router on a grid.
+ *
+ * Rasterizes a canvas into square cells and routes every edge with A*:
+ *
+ * - node rects ("boxes", inflated) hard-block cells;
+ * - per-direction occupancy: a cell can host ONE horizontal and ONE vertical
+ *   run — another bus reusing the same direction pays a near-prohibitive
+ *   penalty (soft block, so routing never fails), while perpendicular
+ *   crossings only pay a small toll → lanes separate themselves and crossings
+ *   happen only where they're worth it;
+ * - same-bus discount + tree seeding: a bus's later edges branch from the
+ *   OPTIMAL point of the already-routed trunk (Steiner-style joins), and
+ *   `exitCost` prices opening a new trunk out of a source, so merges can win
+ *   even over shorter direct paths;
+ * - turn penalty biases toward long straight runs;
+ * - endpoints are exclusive per bus (no stacked stubs/arrowheads);
+ * - an edge is NEVER dropped: when a node row walls the grid off, a desperate
+ *   pass routes through obstacles at a huge cost and reports a violation.
+ *
+ * Pure geometry: the caller measures its DOM into {@link GridBox}es and
+ * renders the returned SVG path strings. Framework-free.
+ */
+export interface GridBox {
+    t: number;
+    b: number;
+    l: number;
+    r: number;
+    cx: number;
+    cy: number;
+}
+export interface GridEdge {
+    id: string;
+    source: string;
+    target: string;
+    /** Bus discriminator: edges sharing (source, bus) merge into one trunk
+     * tree. Defaults to the source alone. */
+    bus?: string;
+    /** Opaque consumer payload, passed through untouched onto the conn. */
+    data?: unknown;
+}
+export interface GridConn {
+    id: string;
+    source: string;
+    target: string;
+    /** Full bus key (`source|bus`) — stable grouping handle for rendering
+     * (e.g. crossing-hop halos are painted per bus). */
+    bus: string;
+    data?: unknown;
+    /** Orthogonal SVG path: source contact → routed cells → target contact. */
+    d: string;
+}
+export interface GridDebugCell {
+    x: number;
+    y: number;
+    kind: 'chip' | 'h' | 'v' | 'hv' | 'bad';
+}
+export interface GridResult {
+    conns: GridConn[];
+    /** deepest y any path reaches (callers reserve layout height for it) */
+    bottom: number;
+    /** lane-sharing incidents (should be 0 — non-zero means the layout does
+     * not supply enough corridor space, see corridorGaps()) */
+    violations: number;
+    debug: {
+        res: number;
+        cols: number;
+        rows: number;
+        cells: GridDebugCell[];
+    };
+}
+/** Box inflation in px: routed runs keep this clearance off every box. */
+export declare const BOX_INFLATE = 3;
+export interface GridOpts {
+    /** grid cell size in px (default 12) */
+    res?: number;
+    /** cost per cell when riding cells the bus already owns (default 0.02) */
+    costOwn?: number;
+    /** penalty per 90° turn (default 1) */
+    costTurn?: number;
+    /** penalty for opening a NEW trunk out of a source (default 0) — raise it
+     * to make a bus's edges merge even when direct paths would be shorter */
+    exitCost?: number;
+    /**
+     * Cost layers: arbitrary rects (px) adding a per-cell bias to every step
+     * inside them — positive repels routes, negative attracts them. This is
+     * the generic hook for consumer concepts the router deliberately does not
+     * know about (e.g. a "lanes" layer biasing corridors negative, keep-out
+     * zones, preferred highways). The effective step cost is floored so
+     * negative biases can't break A*.
+     */
+    costRegions?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+        bias: number;
+    }[];
+    /**
+     * Port constraints: restrict which box sides edges may attach to, per node
+     * id (schematic semantics — a horizontal resistor only connects via its
+     * left/right leads, an IC via its pin sides). Unlisted nodes accept all
+     * four sides. The desperate fallback relaxes the constraint rather than
+     * dropping the edge.
+     */
+    nodeSides?: Record<string, BoxSide[]>;
+}
+export type BoxSide = 'top' | 'bottom' | 'left' | 'right';
+export declare function routeGrid(boxes: Map<string, GridBox>, edges: GridEdge[], width: number, height: number, opts?: GridOpts): GridResult;