# Spec: Double-Elimination Connector Routing ## Objective Make winner advancement lines in the desktop double-elimination bracket bend at a consistent horizontal position. Two winner lines entering the same match should read as one visual pair when their vertical spans can share a rail: use the center of the 40px inter-column corridor when it is safe, and move the pair together only when another connector would interfere. If an accepted A/B mapping reverses the source order and makes those spans overlap, preserve separate deterministic, stroke-clear rails instead of creating a collinear overlap. The primary user is a participant or organizer tracing advancement through a busy eight-team bracket. Success means the solid coral winner paths are visually aligned without degrading the existing dashed loser paths, card placement, or keyboard-driven connector highlighting. ## Approved Product Decisions - Treat the two `winner` connectors entering one Series as a semantic bundle. - Prefer `target.x - columnGap / 2` for a winner bundle. - If the preferred rail causes crossings, collinear overlap, or less than 5px of clearance from an overlapping parallel route, move a shareable bundle to the nearest safe rail. Retain separate rails only when the pair's own vertical spans overlap and therefore cannot safely share any rail; move those rails to the nearest deterministic positions needed to preserve the same 5px clearance. - Preserve the current loser/reset rail ordering unless moving one is required to maintain valid geometry. - Keep every connector as a separate `H-V-H` SVG path so focus highlighting and accessible labels remain independent. - Keep long-distance bends inside the corridor immediately before the target column; do not use the midpoint between source and target cards. ## Tech Stack - React 19, TypeScript 6, Vite 8, Tailwind CSS 4, and daisyUI under `apps/web` - Node's built-in test runner for the pure bracket layout calculation ## Commands - Focused layout tests: `pnpm --filter web exec node --test --experimental-strip-types test/double-elimination-bracket-layout.test.ts` - Full web tests: `pnpm --filter web test` - Web lint: `pnpm --filter web lint` - Web production build: `pnpm --filter web build:prod` - Development server: `pnpm --filter web start:dev` ## Project Structure - `apps/web/src/components/competition/double-elimination-bracket-layout.ts` validates the bracket graph, positions cards, assigns connector rails, and emits SVG path geometry. - `apps/web/src/components/competition/DoubleEliminationBracket.tsx` renders the computed paths and must not need routing-specific changes. - `apps/web/test/double-elimination-bracket-layout.test.ts` contains canonical four-team, eight-team, and reset-final fixtures plus geometry assertions. ## Code Style Keep routing deterministic and express geometry through small named helpers: ```ts const preferredX = target.x - geometry.columnGap / 2; const verticalX = nearestSafeRail(preferredX, bundle, occupiedRoutes); ``` Use existing layout types and semantic connector kinds. Do not add a dependency, DOM measurement, mutable global state, or renderer-specific routing behavior. ## Testing Strategy - Add regression tests before implementation and confirm they fail against the current per-edge rail allocator. - Assert observable geometry: safe winner pairs share a rail, quiet corridors use their exact midpoint, busy corridors keep a pair aligned, and mixed winner/loser entries remain distinguishable. - Cover reversed A/B winner input explicitly: it remains deterministic and uses separate rails without collinear overlap or focused-stroke clearance conflicts because no shared H-V-H rail is safe. - Replace the obsolete "all rails in a target column are unique" assertion with interval-aware overlap and 5px focused-stroke clearance protection. - Preserve deterministic output for shuffled input, finite path coordinates, target-corridor bounds, card avoidance, endpoint alignment, and canonical graph validation. - Verify four-team, eight-team, and reset-final layouts; run the complete web test, lint, and production build commands. ## Boundaries ### Always - Keep winner, loser, and reset connectors visually distinguishable by the existing solid/dashed patterns and brand tokens. - Keep connector rails strictly inside the target corridor. - Avoid strict segment crossings and collinear overlaps whenever a safe candidate exists. - Keep overlapping parallel winner and loser rails at least 5px apart, matching the widest focused connector underlay. - Produce the same layout regardless of projection input ordering. ### Ask First - Add dependencies or change the public projection contract. - Change bracket card dimensions, round columns, or the 40px column gap. - Redesign mobile bracket presentation or connector interaction behavior. ### Never - Route a connector through a match card. - Infer routing from Series codes; use canonical graph identity and topology. - Merge two logical connectors into one SVG path. - Modify unrelated competition or score-card behavior. ## Success Criteria - The two winner paths into `LB_R3_M1` bend at the corridor midpoint and share the same `verticalX`. - The winner paths into the grand final share the corridor midpoint when safe. - Every same-target winner pair whose vertical spans do not overlap shares one `verticalX`, using the nearest collision-safe rail when the midpoint is busy. - A reversed A/B pair with overlapping vertical spans retains deterministic separate rails, produces no collinear segment overlap, and remains at least 5px from every overlapping vertical route. - Loser/reset paths retain their baseline rails, and winner bundles remain at least 5px away where their vertical runs overlap. - All rails remain inside their target corridors without card penetration or collinear overlap. - Canonical four-team, eight-team, reset-final, and shuffled-input tests pass. - Full web tests and production build pass; changed-file lint passes, and any unrelated full-lint baseline failures are documented. ## Open Questions None. The user reviewed the proposed bundle-aware routing behavior and requested implementation.