@zombie-mermaid/ascii-renderer 2.2.1

package/src/edge-bundling.ts

@@ -0,0 +1,435 @@
+// ============================================================================
+// ASCII renderer — edge bundling for parallel links
+//
+// Analyzes edges to find parallel links (A & B --> C or A --> B & C) and
+// groups them into bundles. Bundled edges share a visual junction point
+// where they merge/split, creating cleaner diagrams.
+//
+// This module provides:
+//   - analyzeEdgeBundles(): Finds and creates bundles from graph edges
+//   - calculateJunctionPoint(): Computes optimal merge/split locations
+//   - routeBundledEdges(): Routes edges through junction points
+// ============================================================================
+
+import type {
+  AsciiGraph,
+  AsciiNode,
+  AsciiEdge,
+  EdgeBundle,
+  GridCoord,
+  CardinalDirection,
+} from './types.ts'
+import {
+  Up,
+  Down,
+  Left,
+  Right,
+  Middle,
+  gridCoordDirection,
+  requireCardinalDirection,
+} from './types.ts'
+import { getNodeSubgraph, requireGridCoord } from './grid.ts'
+import { routeEdge } from './pathfinder.ts'
+
+// ============================================================================
+// Bundle analysis
+// ============================================================================
+
+/**
+ * Analyze graph edges and create bundles for parallel links.
+ *
+ * Groups edges by:
+ * - Fan-in: Multiple edges sharing the same target (A & B --> C)
+ * - Fan-out: Multiple edges sharing the same source (A --> B & C)
+ *
+ * Only creates bundles when:
+ * - Graph direction is TD (top-down) - LR routing handles merging naturally
+ * - 2+ edges share the endpoint
+ * - All edges have the same style (solid/dotted/thick)
+ * - None of the edges have labels (labels would overlap at junction)
+ * - Edges are not self-loops
+ *
+ * @returns Array of bundles. Each edge can belong to at most one bundle.
+ */
+export function analyzeEdgeBundles(graph: AsciiGraph): EdgeBundle[] {
+  // Only bundle in TD direction - LR routing handles merging naturally at corners
+  if (graph.config.graphDirection !== 'TD') {
+    return []
+  }
+  const bundles: EdgeBundle[] = []
+  const bundledEdges = new Set<AsciiEdge>()
+
+  // Group edges by target (fan-in candidates)
+  const edgesByTarget = new Map<AsciiNode, AsciiEdge[]>()
+  for (const edge of graph.edges) {
+    // Skip self-loops
+    if (edge.from === edge.to) continue
+
+    const existing = edgesByTarget.get(edge.to) ?? []
+    existing.push(edge)
+    edgesByTarget.set(edge.to, existing)
+  }
+
+  // Create fan-in bundles
+  for (const [target, edges] of edgesByTarget) {
+    if (edges.length < 2) continue
+    if (!canBundle(edges, graph)) continue
+
+    // Check if all edges are already bundled
+    if (edges.some((e) => bundledEdges.has(e))) continue
+
+    const bundle: EdgeBundle = {
+      type: 'fan-in',
+      edges: [...edges],
+      sharedNode: target,
+      otherNodes: edges.map((e) => e.from),
+      junctionPoint: null,
+      sharedPath: [],
+      junctionDir: Middle,
+      sharedNodeDir: Middle,
+    }
+
+    // Mark edges as bundled
+    for (const edge of edges) {
+      edge.bundle = bundle
+      bundledEdges.add(edge)
+    }
+
+    bundles.push(bundle)
+  }
+
+  // Group edges by source (fan-out candidates)
+  const edgesBySource = new Map<AsciiNode, AsciiEdge[]>()
+  for (const edge of graph.edges) {
+    // Skip self-loops and already bundled edges
+    if (edge.from === edge.to) continue
+    if (bundledEdges.has(edge)) continue
+
+    const existing = edgesBySource.get(edge.from) ?? []
+    existing.push(edge)
+    edgesBySource.set(edge.from, existing)
+  }
+
+  // Create fan-out bundles
+  for (const [source, edges] of edgesBySource) {
+    if (edges.length < 2) continue
+    if (!canBundle(edges, graph)) continue
+
+    const bundle: EdgeBundle = {
+      type: 'fan-out',
+      edges: [...edges],
+      sharedNode: source,
+      otherNodes: edges.map((e) => e.to),
+      junctionPoint: null,
+      sharedPath: [],
+      junctionDir: Middle,
+      sharedNodeDir: Middle,
+    }
+
+    // Mark edges as bundled
+    for (const edge of edges) {
+      edge.bundle = bundle
+      bundledEdges.add(edge)
+    }
+
+    bundles.push(bundle)
+  }
+
+  return bundles
+}
+
+/**
+ * Check if a group of edges can be bundled together.
+ * Returns false if edges have different styles, any have labels,
+ * or if the edges span subgraph boundaries (which creates complex routing).
+ */
+function canBundle(edges: AsciiEdge[], graph: AsciiGraph): boolean {
+  if (edges.length < 2) return false
+
+  const firstStyle = edges[0]!.style
+  const firstFromSg = getNodeSubgraph(graph, edges[0]!.from)
+  const firstToSg = getNodeSubgraph(graph, edges[0]!.to)
+
+  for (const edge of edges) {
+    // Different styles can't be bundled (would look confusing)
+    if (edge.style !== firstStyle) return false
+
+    // Edges with labels can't be bundled (labels would overlap at junction)
+    if (edge.text.length > 0) return false
+
+    // Don't bundle if edges span different subgraph boundaries
+    // (creates complex routing that doesn't look good)
+    const fromSg = getNodeSubgraph(graph, edge.from)
+    const toSg = getNodeSubgraph(graph, edge.to)
+    if (fromSg !== firstFromSg || toSg !== firstToSg) return false
+
+    // Don't bundle if source and target are in different subgraphs
+    // (cross-boundary edges have special routing needs)
+    if (fromSg !== toSg) return false
+  }
+
+  // A group formed by shared-target (fan-in) or shared-source (fan-out)
+  // grouping can still contain two edges that ALSO share the other
+  // endpoint — true parallel/multi-edges (e.g. two unlabeled `A --> B`
+  // edges), not a genuine fan-in/fan-out. Folding those into one shared
+  // trunk+junction would visually merge them into a single line (the same
+  // "second edge silently wins" defect this bundling feature is supposed
+  // to avoid — see #329), rather than the distinct offset lanes
+  // assignParallelEdgeLanes (edge-routing.ts) already gives them. Detect it
+  // generically: the group is fan-in (shared `.to`) or fan-out (shared
+  // `.from`) by construction (see analyzeEdgeBundles' two call sites), so
+  // checking whichever endpoint *isn't* uniformly shared for duplicates
+  // catches both cases without the caller having to say which one it is.
+  const sameTarget = edges.every((e) => e.to === edges[0]!.to)
+  const otherEndpoints = sameTarget
+    ? edges.map((e) => e.from)
+    : edges.map((e) => e.to)
+  if (new Set(otherEndpoints).size !== otherEndpoints.length) return false
+
+  // The duplicate check above only catches an *ordered*-pair duplicate. A
+  // reverse-direction sibling (`B --> A` alongside `A --> B`, #629) reaches
+  // a fan-in/fan-out group with a *distinct* other endpoint and slips past
+  // it, even though assignParallelEdgeLanes has already committed that pair
+  // to two distinct lanes — and a lane is a fixed offset from the pair's
+  // own center path, not from wherever a trunk would have moved its sibling
+  // to. So no edge assigned to a lane group ever gets bundled.
+  //
+  // Defensive: currently unreachable, and deliberately kept anyway. A
+  // reverse-direction lane is only assigned when the pair sits side by side
+  // on one grid row (edge-routing.ts's sharesHorizontalChannel), which is
+  // exactly what the rank-ordering check below already rejects — every
+  // source must be strictly above the shared target (or every target
+  // strictly below the shared source). Those two conditions happen to be
+  // complementary today; nothing structural keeps them that way.
+  /* v8 ignore next */
+  if (edges.some((e) => e.parallelLane)) return false
+
+  // Bundling assumes every source sits strictly before the shared target
+  // along the graph-direction axis for fan-in (TD: above it; LR: left of
+  // it), or every target sits strictly after the shared source for
+  // fan-out — calculateJunctionPoint places the junction on that side of
+  // the shared node and routeBundledEdges exits/enters it accordingly. The
+  // grid layout can violate that: a node's rank gets pinned by whichever
+  // incoming edge's source is placed first (placeReachableChildren in
+  // grid.ts never revisits an already-placed node), so a "diamond" like
+  // `Queue --> Worker` plus `Queue --> Retry --> Worker` can leave Worker
+  // at the SAME rank as Retry instead of one rank after it (#454).
+  // Bundling that pair would route Retry's edge through the same
+  // trunk+arrowhead as Queue's, silently swallowing Retry's own arrowhead
+  // into a line that looks like it belongs solely to Queue. Refuse to
+  // bundle whenever any edge doesn't actually satisfy the "before the
+  // target" / "after the source" assumption; routed independently instead,
+  // it gets its own distinct, visible arrowhead into/out of the shared node.
+  // `analyzeEdgeBundles` (this function's only caller) already gates on
+  // `graphDirection === 'TD'` before ever calling `canBundle`, so the 'LR'
+  // arm is unreachable today — kept for whenever LR bundling support
+  // lands, matching this comment block's own "TD: above it; LR: left of
+  // it" framing above.
+  /* v8 ignore next */
+  const axis: 'x' | 'y' = graph.config.graphDirection === 'LR' ? 'x' : 'y'
+  const sharedNode = sameTarget ? edges[0]!.to : edges[0]!.from
+  const sharedCoord = sharedNode.gridCoord
+  // Grid layout always runs before bundling — every node reaching this
+  // point has a gridCoord (see `requireGridCoord`'s own use lower in this
+  // file for the same assumption). Defensive only; not reachable from any
+  // real diagram.
+  /* v8 ignore next */
+  if (!sharedCoord) return false
+  for (const edge of edges) {
+    const otherNode = sameTarget ? edge.from : edge.to
+    const otherCoord = otherNode.gridCoord
+    /* v8 ignore next */
+    if (!otherCoord) return false
+    if (sameTarget) {
+      // fan-in: source must be strictly before the shared target
+      if (otherCoord[axis] >= sharedCoord[axis]) return false
+    } else {
+      // fan-out: target must be strictly after the shared source. The
+      // fan-in violation above is reachable via a plain diamond (a shared
+      // target reached both directly and via a detour — see #454's own
+      // repro and this file's regression test) because rank assignment
+      // can shortchange whichever of two *competing parents* gets visited
+      // second. The mirror-image fan-out violation would need a target's
+      // rank to land at or before its own source's — topologically only
+      // possible with an actual cycle, not exercised by any sample in
+      // this repo. Kept for symmetry with the fan-in case above (and
+      // because a cycle isn't inherently invalid mermaid syntax) rather
+      // than assumed impossible.
+      /* v8 ignore next */
+      if (otherCoord[axis] <= sharedCoord[axis]) return false
+    }
+  }
+
+  return true
+}
+
+// ============================================================================
+// Junction point calculation
+// ============================================================================
+
+/**
+ * Calculate the optimal junction point for a bundle.
+ *
+ * For fan-in (A & B --> C):
+ *   - Junction is placed between the sources and the target
+ *   - In TD: above the target, horizontally centered between sources
+ *   - In LR: left of the target, vertically centered between sources
+ *
+ * For fan-out (A --> B & C):
+ *   - Junction is placed between the source and the targets
+ *   - In TD: below the source, horizontally centered between targets
+ *   - In LR: right of the source, vertically centered between targets
+ */
+export function calculateJunctionPoint(
+  graph: AsciiGraph,
+  bundle: EdgeBundle,
+): GridCoord {
+  const dir = graph.config.graphDirection
+  const sharedCoord = requireGridCoord(bundle.sharedNode)
+
+  if (bundle.type === 'fan-in') {
+    // Junction is BEFORE the shared target
+    // Calculate center of sources
+    if (dir === 'TD') {
+      // Junction above target, centered between sources
+      // Place it one row above the target's entry point
+      const junctionY = sharedCoord.y - 1
+      // X is centered between sources, but clamped to shared node's X for alignment
+      const junctionX = sharedCoord.x + 1 // Align with target's center
+
+      return { x: junctionX, y: junctionY }
+    } else {
+      // LR: Junction left of target, centered between sources
+      const junctionX = sharedCoord.x - 1
+      const junctionY = sharedCoord.y + 1 // Align with target's center
+
+      return { x: junctionX, y: junctionY }
+    }
+  } else {
+    // fan-out: Junction is AFTER the shared source
+    if (dir === 'TD') {
+      // Junction below source, will then split to targets
+      const junctionY = sharedCoord.y + 3 // Just below source's 3x3 block
+      const junctionX = sharedCoord.x + 1 // Align with source's center
+
+      return { x: junctionX, y: junctionY }
+    } else {
+      // LR: Junction right of source
+      const junctionX = sharedCoord.x + 3
+      const junctionY = sharedCoord.y + 1
+
+      return { x: junctionX, y: junctionY }
+    }
+  }
+}
+
+// ============================================================================
+// Bundled edge routing
+// ============================================================================
+
+/**
+ * Route all edges in a bundle through the junction point.
+ *
+ * For fan-in bundles:
+ *   1. Route each source → junction (stored in edge.pathToJunction)
+ *   2. Route junction → target (stored in bundle.sharedPath)
+ *
+ * For fan-out bundles:
+ *   1. Route source → junction (stored in bundle.sharedPath)
+ *   2. Route junction → each target (stored in edge.pathToJunction)
+ */
+export function routeBundledEdges(graph: AsciiGraph, bundle: EdgeBundle): void {
+  const dir = graph.config.graphDirection
+
+  // Calculate and store junction point
+  bundle.junctionPoint = calculateJunctionPoint(graph, bundle)
+  const junction = bundle.junctionPoint
+
+  // Determine directions based on graph direction and bundle type
+  if (bundle.type === 'fan-in') {
+    // Sources converge to junction, then junction to target
+    bundle.junctionDir = dir === 'TD' ? Up : Left
+    bundle.sharedNodeDir = dir === 'TD' ? Down : Right
+
+    // Route junction → target (shared path). Anchor offsets (top/left
+    // center of target, bottom/right center of source below) are computed
+    // via gridCoordDirection — the same per-direction offset edge-routing.ts
+    // uses — instead of each bundling call reimplementing its own
+    // arithmetic. routeEdge (pathfinder.ts, also used by edge-routing.ts)
+    // tries an unobstructed direct path before falling back to A*. Note
+    // that `targetDir` here is the *arrival* anchor at the target, not
+    // necessarily the true departure direction from `junction` — routeEdge
+    // handles that by trying both L-corner orientations internally (see
+    // tryDirectPath in pathfinder.ts) rather than trusting this value as a
+    // routing axis.
+    const targetCoord = requireGridCoord(bundle.sharedNode)
+    const targetDir: CardinalDirection = requireCardinalDirection(
+      dir === 'TD' ? Up : Left,
+    )
+    const targetEntry = gridCoordDirection(targetCoord, targetDir)
+
+    const sharedPath = routeEdge(graph, junction, targetEntry, targetDir)
+    bundle.sharedPath = sharedPath ?? [junction, targetEntry]
+
+    // Route each source → junction
+    for (const edge of bundle.edges) {
+      const sourceCoord = requireGridCoord(edge.from)
+      const sourceDir: CardinalDirection = requireCardinalDirection(
+        dir === 'TD' ? Down : Right,
+      )
+      const sourceExit = gridCoordDirection(sourceCoord, sourceDir)
+
+      const pathToJunction = routeEdge(graph, sourceExit, junction, sourceDir)
+      edge.pathToJunction = pathToJunction ?? [sourceExit, junction]
+
+      // Set edge directions for proper drawing
+      edge.startDir = sourceDir
+      edge.endDir = targetDir
+
+      // Build full path for grid size calculation: source → junction → target
+      edge.path = [...edge.pathToJunction, ...bundle.sharedPath.slice(1)]
+    }
+  } else {
+    // fan-out: Source to junction, then junction splits to targets
+    bundle.junctionDir = dir === 'TD' ? Down : Right
+    bundle.sharedNodeDir = dir === 'TD' ? Up : Left
+
+    // Route source → junction (shared path)
+    const sourceCoord = requireGridCoord(bundle.sharedNode)
+    const sourceDir: CardinalDirection = requireCardinalDirection(
+      dir === 'TD' ? Down : Right,
+    )
+    const sourceExit = gridCoordDirection(sourceCoord, sourceDir)
+
+    const sharedPath = routeEdge(graph, sourceExit, junction, sourceDir)
+    bundle.sharedPath = sharedPath ?? [sourceExit, junction]
+
+    // Route junction → each target
+    for (const edge of bundle.edges) {
+      const targetCoord = requireGridCoord(edge.to)
+      const targetDir: CardinalDirection = requireCardinalDirection(
+        dir === 'TD' ? Up : Left,
+      )
+      const targetEntry = gridCoordDirection(targetCoord, targetDir)
+
+      const pathToJunction = routeEdge(graph, junction, targetEntry, targetDir)
+      edge.pathToJunction = pathToJunction ?? [junction, targetEntry]
+
+      // Set edge directions
+      edge.startDir = sourceDir
+      edge.endDir = targetDir
+
+      // Build full path for grid size calculation: source → junction → target
+      edge.path = [...bundle.sharedPath, ...edge.pathToJunction.slice(1)]
+    }
+  }
+}
+
+/**
+ * Process all bundles in a graph: calculate junction points and route edges.
+ */
+export function processBundles(graph: AsciiGraph): void {
+  for (const bundle of graph.bundles) {
+    routeBundledEdges(graph, bundle)
+  }
+}

package/src/edge-cell-styles.ts

@@ -0,0 +1,209 @@
+// ============================================================================
+// ASCII renderer — cross-style edge overlap detection
+//
+// `graph.grid` (grid-occupancy.ts) only tracks *node* occupancy, so two
+// unrelated edges (different source and target — no reason for
+// `analyzeEdgeBundles` to group them, and A* itself only avoids node cells)
+// can independently route through the same empty cell. When both edges have
+// the *same* line style that's harmless — it just looks like one clean
+// shared line, which `analyzeEdgeBundles`'s "LR routing handles merging
+// naturally at corners" comment and its own trunk-sharing tests rely on
+// intentionally. It's only a real defect when the styles *differ*: a solid
+// cell and a dotted cell can't both be drawn at the same grid position, so
+// one silently overwrites the other and the reader can't tell two distinct
+// connections are there at all.
+//
+// This module tracks, per *open, non-node* cell, which single style has
+// claimed it (first claim wins) so grid.ts can detect a genuine cross-style
+// collision after routing an edge and reroute just that edge around it —
+// see `rerouteAroundStyleConflicts` in grid.ts.
+//
+// Node-occupied cells are deliberately excluded from tracking: an edge's
+// path always includes its own source/target node's border cell (that's
+// how it connects to the box at all), so two edges sharing a node — one
+// incoming, one outgoing, as in a retry loop's `B -->|No| D; D -.-> A` —
+// legitimately share that exact port cell. The character actually drawn
+// there comes from the node's own box-drawing code, not either edge's line
+// style, so it was never a real conflict. Blocking it wouldn't even help:
+// an edge always returns to its own node's fixed attachment point
+// regardless of grid occupancy, so re-routing around a node-owned "conflict"
+// just finds the identical cell again on every retry.
+// ============================================================================
+
+import type { AsciiEdge, AsciiEdgeStyle, GridCoord } from './types.ts'
+import { gridKey } from './types.ts'
+import { isOccupied, pathCells, type Grid } from './grid-occupancy.ts'
+
+/** Cells already claimed by a drawn edge, keyed by "x,y", storing which
+ * single line style is drawn there. */
+export type EdgeCellStyles = Map<string, AsciiEdgeStyle>
+
+export function createEdgeCellStyles(): EdgeCellStyles {
+  return new Map()
+}
+
+/**
+ * The first open (non-node-occupied) cell in `path` already claimed by a
+ * *different* style than `style`. Same-style overlap is not reported — see
+ * module doc.
+ */
+export function findStyleConflict(
+  grid: Grid,
+  cellStyles: EdgeCellStyles,
+  path: readonly GridCoord[],
+  style: AsciiEdgeStyle,
+): GridCoord | null {
+  for (const cell of pathCells(path)) {
+    if (isOccupied(grid, cell)) continue
+    const existing = cellStyles.get(gridKey(cell))
+    if (existing !== undefined && existing !== style) return cell
+  }
+  return null
+}
+
+/**
+ * Record every open (non-node-occupied) cell in `path` as claimed by
+ * `style`. First claim per cell wins — a later same-style edge through the
+ * same cell is a harmless no-op, and a later different-style edge is
+ * caught by `findStyleConflict` before this ever runs for it.
+ */
+export function claimPathCells(
+  grid: Grid,
+  cellStyles: EdgeCellStyles,
+  path: readonly GridCoord[],
+  style: AsciiEdgeStyle,
+): void {
+  for (const cell of pathCells(path)) {
+    if (isOccupied(grid, cell)) continue
+    const key = gridKey(cell)
+    if (!cellStyles.has(key)) cellStyles.set(key, style)
+  }
+}
+
+// ============================================================================
+// Chain-edge overlap detection (independent of style)
+// ============================================================================
+//
+// The cross-*style* conflict above only fires when two overlapping edges
+// draw different characters — a same-style overlap silently draws the same
+// glyph twice, which this module's own doc calls harmless, and it usually
+// is: `analyzeEdgeBundles`'s own fan-in/fan-out trunk sharing is same-style
+// by construction, and a "complete bipartite" crossing like `A & B --> C &
+// D` (see ascii.test.ts's `ampersand_lhs_and_rhs` golden file) *deliberately*
+// routes two edges that share neither endpoint (`A --> D` and `B --> C`)
+// through the same shared crossbar — that is the intended, faithful
+// rendering of that shape, not a defect.
+//
+// It stops being harmless in one specific shape a plain "shares an
+// endpoint" check can't distinguish from that crossing pattern: a *chain*
+// through a shared intermediate node, `A --> B` then `B --> C`, each routed
+// independently. When their corners happen to coincide, `A`'s incoming leg
+// and `C`'s outgoing leg trace the exact same column/row beyond the shared,
+// node-owned port cell and read as one continuous `A --> C` connector
+// (#1067, "System Architecture": `Mobile App --> API Gateway` and
+// `API Gateway --> User Service` sharing one on-screen row with no visual
+// break, even though there is no `Mobile App --> User Service` edge in the
+// source). Unlike the crossing pattern above, a chain's two edges have no
+// reason to share open-space cells at all beyond that one port — so this
+// check is scoped *only* to chain pairs (`isChainPair` below), not to every
+// pair of edges that merely shares neither endpoint; widening it to that
+// general case is exactly what broke the ampersand golden file during this
+// fix's own development.
+
+/** Cells already claimed by drawn edges, keyed by "x,y", storing every edge
+ * (by reference) that drew there — independent of `EdgeCellStyles` above,
+ * which tracks *style* rather than edge identity.
+ *
+ * Stores a `Set`, not a single edge: `graph.edges` order means an edge
+ * unrelated to any chain can claim a cell before a real chain pair's own
+ * edges do, and a single-owner map would let that unrelated edge's claim
+ * hide the chain pair's overlap from `findUnrelatedOverlap` entirely. See
+ * that function's own doc.
+ */
+export type EdgeCellOwners = Map<string, Set<AsciiEdge>>
+
+export function createEdgeCellOwners(): EdgeCellOwners {
+  return new Map()
+}
+
+/**
+ * Whether `a` and `b` form a chain through a shared intermediate node: one
+ * edge's target is the other's source. Deliberately narrower than "shares
+ * any endpoint" — a fan-in/fan-out pair (shared `from` or shared `to`) is
+ * excluded on purpose, since that is exactly the shape a legitimate shared
+ * trunk (bundled or not — see module doc) already routes through common
+ * cells for.
+ */
+function isChainPair(a: AsciiEdge, b: AsciiEdge): boolean {
+  return a.to === b.from || b.to === a.from
+}
+
+/**
+ * Minimum number of open, non-node cells a chain pair must share before it
+ * counts as a real conflict. A single shared cell is an ordinary crossing
+ * (two independent lines passing through the same point, which still reads
+ * as two lines) — it takes a *run* of shared cells, long enough to read as
+ * one continuous connector, to actually mislead a reader. Chosen to be the
+ * smallest value that catches a shared corner-to-corner leg (at least 2
+ * collinear cells) while still letting a lone crossing through.
+ */
+const MIN_CHAIN_OVERLAP = 2
+
+/**
+ * The first open (non-node-occupied) cell in `path` already claimed by a
+ * different edge that forms a chain with `edge` (`isChainPair`) — but only
+ * once *that specific chain partner's* total overlap with `edge` reaches
+ * `MIN_CHAIN_OVERLAP` cells (see that constant's doc). Each distinct owner
+ * of a cell is checked and counted independently — a cell can hold several
+ * edges' claims (see `EdgeCellOwners`'s own doc), and an unrelated same-style
+ * edge sharing a cell must not hide a real chain partner's overlap that also
+ * claimed it. Returns `null` when no chain partner's overlap reaches the
+ * threshold.
+ */
+export function findUnrelatedOverlap(
+  grid: Grid,
+  owners: EdgeCellOwners,
+  path: readonly GridCoord[],
+  edge: AsciiEdge,
+): GridCoord | null {
+  const overlapCounts = new Map<AsciiEdge, number>()
+  const firstConflicts = new Map<AsciiEdge, GridCoord>()
+  for (const cell of pathCells(path)) {
+    if (isOccupied(grid, cell)) continue
+    const cellOwners = owners.get(gridKey(cell))
+    if (cellOwners === undefined) continue
+    for (const owner of cellOwners) {
+      if (owner === edge) continue
+      if (!isChainPair(owner, edge)) continue
+      overlapCounts.set(owner, (overlapCounts.get(owner) ?? 0) + 1)
+      if (!firstConflicts.has(owner)) firstConflicts.set(owner, cell)
+    }
+  }
+  for (const [owner, count] of overlapCounts) {
+    if (count >= MIN_CHAIN_OVERLAP) return firstConflicts.get(owner)!
+  }
+  return null
+}
+
+/**
+ * Record every open (non-node-occupied) cell in `path` as claimed by
+ * `edge`, alongside any edge(s) that already claimed it — see
+ * `EdgeCellOwners`'s own doc for why a cell can have more than one owner.
+ */
+export function claimPathOwners(
+  grid: Grid,
+  owners: EdgeCellOwners,
+  path: readonly GridCoord[],
+  edge: AsciiEdge,
+): void {
+  for (const cell of pathCells(path)) {
+    if (isOccupied(grid, cell)) continue
+    const key = gridKey(cell)
+    let cellOwners = owners.get(key)
+    if (cellOwners === undefined) {
+      cellOwners = new Set()
+      owners.set(key, cellOwners)
+    }
+    cellOwners.add(edge)
+  }
+}