diff --git a/.gitignore b/.gitignore index 8c149245..b762a4c2 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,8 @@ website/LICENSE !AGENTS.md !docs/specs/internal-match-game-analysis.md !docs/plans/internal-match-game-analysis-p0-p1.md +!docs/specs/double-elimination-connector-routing.md +!docs/plans/double-elimination-connector-routing.md !agents/**/*.md !skills/**/*.md /tmp/ diff --git a/apps/web/src/components/competition/double-elimination-bracket-layout.ts b/apps/web/src/components/competition/double-elimination-bracket-layout.ts index f353bee6..97884a11 100644 --- a/apps/web/src/components/competition/double-elimination-bracket-layout.ts +++ b/apps/web/src/components/competition/double-elimination-bracket-layout.ts @@ -17,6 +17,8 @@ export const DOUBLE_ELIMINATION_BRACKET_GEOMETRY = { boardPadding: 12, columnWidth: 228, columnGap: 40, + // Matches the widest focused connector underlay so parallel routes stay legible. + connectorRailClearance: 5, cardBorderWidth: SERIES_SCORE_CARD_GEOMETRY.borderWidth, cardHeight: SERIES_SCORE_CARD_GEOMETRY.height, cardHeaderHeight: SERIES_SCORE_CARD_GEOMETRY.headerHeight, @@ -109,6 +111,29 @@ interface NormalizedRound { seriesIds: SeriesId[]; } +interface ConnectorRoute { + connector: SeriesConnectorView; + key: string; + kind: BracketConnectorKind; + targetColumn: number; + targetNodeY: number; + sourceX: number; + sourceY: number; + targetX: number; + targetY: number; +} + +interface SeparateWinnerRailChoice { + verticalXs: [number, number]; + crossings: number; + distanceFromBaseline: number; + distanceFromCenter: number; +} + +type OrthogonalSegment = + | { orientation: "horizontal"; fixed: number; start: number; end: number } + | { orientation: "vertical"; fixed: number; start: number; end: number }; + const STAGE_ORDER: Record = { upper: 0, lower: 1, @@ -126,6 +151,9 @@ const CONNECTOR_SELECTION_ORDER: Record< "slot-b": 3, }; +// A focused 5px underlay extends 2.5px from its centerline. +const CONNECTOR_RAIL_EDGE_INSET = 3; + export function createDoubleEliminationBracketLayout( projection: DoubleEliminationCompetitionProjection, configuration: DoubleEliminationBracketConfiguration, @@ -540,56 +568,53 @@ function buildConnectors( nodeById: Map, ): BracketConnectorLayout[] | null { const geometry = DOUBLE_ELIMINATION_BRACKET_GEOMETRY; - const connectorsByTargetColumn = new Map< - number, - Array<{ - connector: SeriesConnectorView; - source: BracketNodeLayout; - target: BracketNodeLayout; - }> - >(); + const routes: ConnectorRoute[] = []; + const routesByTargetColumn = new Map(); for (const connector of projection.connectors) { const source = nodeById.get(connector.from.seriesId); const target = nodeById.get(connector.to.seriesId); if (!source || !target || target.column <= source.column) return null; - const routes = connectorsByTargetColumn.get(target.column) ?? []; - routes.push({ connector, source, target }); - connectorsByTargetColumn.set(target.column, routes); + const route = { + connector, + key: connectorKey(connector), + kind: connectorKind(connector.from.select), + targetColumn: target.column, + targetNodeY: target.y, + sourceX: source.x + source.width, + sourceY: connectorAnchorY(source, connector.from.select), + targetX: target.x, + targetY: targetSlotY(target, connector.to.slot), + } satisfies ConnectorRoute; + routes.push(route); + const columnRoutes = routesByTargetColumn.get(target.column) ?? []; + columnRoutes.push(route); + routesByTargetColumn.set(target.column, columnRoutes); } const verticalXByConnector = new Map(); - for (const routes of connectorsByTargetColumn.values()) { - routes.sort( + for (const columnRoutes of routesByTargetColumn.values()) { + columnRoutes.sort( (left, right) => - connectorAnchorY(right.source, right.connector.from.select) - - connectorAnchorY(left.source, left.connector.from.select) || - targetSlotY(right.target, right.connector.to.slot) - - targetSlotY(left.target, left.connector.to.slot) || - connectorKey(left.connector).localeCompare(connectorKey(right.connector)), + right.sourceY - left.sourceY || + right.targetY - left.targetY || + left.key.localeCompare(right.key), ); - routes.forEach(({ connector, target }, index) => { + columnRoutes.forEach(({ key, targetX }, index) => { verticalXByConnector.set( - connectorKey(connector), - target.x - + key, + targetX - geometry.columnGap + - (geometry.columnGap * (index + 1)) / (routes.length + 1), + (geometry.columnGap * (index + 1)) / (columnRoutes.length + 1), ); }); } + if (!alignWinnerBundleRails(routes, verticalXByConnector)) return null; const result: BracketConnectorLayout[] = []; - for (const connector of projection.connectors) { - const source = nodeById.get(connector.from.seriesId); - const target = nodeById.get(connector.to.seriesId); - if (!source || !target || target.column <= source.column) return null; - - const sourceX = source.x + source.width; - const targetX = target.x; - const sourceY = connectorAnchorY(source, connector.from.select); - const targetY = targetSlotY(target, connector.to.slot); - const verticalX = verticalXByConnector.get(connectorKey(connector)); + for (const route of routes) { + const { connector, key, kind, sourceX, sourceY, targetX, targetY } = route; + const verticalX = verticalXByConnector.get(key); if (verticalX === undefined) return null; - const kind = connectorKind(connector.from.select); result.push({ fromSeriesId: connector.from.seriesId, select: connector.from.select, @@ -622,6 +647,324 @@ function buildConnectors( ); } +function alignWinnerBundleRails( + routes: readonly ConnectorRoute[], + verticalXByConnector: Map, +): boolean { + const winnersByTarget = new Map(); + for (const route of routes) { + if (route.kind !== "winner") continue; + const winners = winnersByTarget.get(route.connector.to.seriesId) ?? []; + winners.push(route); + winnersByTarget.set(route.connector.to.seriesId, winners); + } + + const bundles = [...winnersByTarget.values()] + .filter( + (winners) => + winners.length === 2 && + winners[0].connector.to.slot !== winners[1].connector.to.slot, + ) + .sort( + (left, right) => + left[0].targetColumn - right[0].targetColumn || + left[0].targetNodeY - right[0].targetNodeY || + left[0].key.localeCompare(right[0].key), + ); + + for (const bundle of bundles) { + const preferredX = + bundle[0].targetX - DOUBLE_ELIMINATION_BRACKET_GEOMETRY.columnGap / 2; + if ( + intervalsOverlap( + bundle[0].sourceY, + bundle[0].targetY, + bundle[1].sourceY, + bundle[1].targetY, + ) + ) { + const assignment = chooseSeparateWinnerRails( + bundle, + routes, + verticalXByConnector, + preferredX, + ); + if (!assignment) return false; + for (const [key, verticalX] of assignment) { + verticalXByConnector.set(key, verticalX); + } + continue; + } + const verticalX = chooseWinnerBundleRail( + bundle, + routes, + verticalXByConnector, + preferredX, + ); + if (verticalX === null) return false; + for (const route of bundle) verticalXByConnector.set(route.key, verticalX); + } + return true; +} + +function chooseWinnerBundleRail( + bundle: readonly ConnectorRoute[], + routes: readonly ConnectorRoute[], + verticalXByConnector: Map, + preferredX: number, +): number | null { + const previousRails = bundle.map((route) => + verticalXByConnector.get(route.key), + ); + if (previousRails.some((verticalX) => verticalX === undefined)) return null; + const previousScore = connectorConflictScore(routes, verticalXByConnector); + // Keep the existing crossing budget, then favor stroke-clear rails nearest center. + let best: + | { + verticalX: number; + crossings: number; + clearanceConflicts: number; + distanceFromCenter: number; + } + | null = null; + + for (const candidateX of winnerRailCandidates(preferredX)) { + for (const route of bundle) { + verticalXByConnector.set(route.key, candidateX); + } + const score = connectorConflictScore(routes, verticalXByConnector); + if ( + score.overlaps !== 0 || + score.crossings > previousScore.crossings || + score.clearanceConflicts > previousScore.clearanceConflicts + ) { + continue; + } + const distanceFromCenter = Math.abs(candidateX - preferredX); + if ( + !best || + score.clearanceConflicts < best.clearanceConflicts || + (score.clearanceConflicts === best.clearanceConflicts && + (score.crossings < best.crossings || + (score.crossings === best.crossings && + distanceFromCenter < best.distanceFromCenter))) + ) { + best = { + verticalX: candidateX, + crossings: score.crossings, + clearanceConflicts: score.clearanceConflicts, + distanceFromCenter, + }; + } + } + + if (best) return best.verticalX; + + bundle.forEach((route, index) => { + const previousX = previousRails[index]; + if (previousX !== undefined) { + verticalXByConnector.set(route.key, previousX); + } + }); + return null; +} + +function winnerRailCandidates(preferredX: number): number[] { + const geometry = DOUBLE_ELIMINATION_BRACKET_GEOMETRY; + const maximumOffset = + geometry.columnGap / 2 - CONNECTOR_RAIL_EDGE_INSET; + const candidates = [preferredX]; + for (let offset = 1; offset <= maximumOffset; offset += 1) { + candidates.push(preferredX - offset, preferredX + offset); + } + return candidates; +} + +function chooseSeparateWinnerRails( + bundle: readonly ConnectorRoute[], + routes: readonly ConnectorRoute[], + verticalXByConnector: Map, + preferredX: number, +): Map | null { + const orderedBundle = [...bundle].sort( + (left, right) => + left.sourceY - right.sourceY || + left.targetY - right.targetY || + left.key.localeCompare(right.key), + ); + const previousRails: number[] = []; + for (const route of orderedBundle) { + const previousX = verticalXByConnector.get(route.key); + if (previousX === undefined) return null; + previousRails.push(previousX); + } + + const previousScore = connectorConflictScore(routes, verticalXByConnector); + const bundleKeys = new Set(orderedBundle.map(({ key }) => key)); + const candidates = [ + ...new Set([...previousRails, ...winnerRailCandidates(preferredX)]), + ]; + let best: SeparateWinnerRailChoice | null = null; + + for (const firstX of candidates) { + for (const secondX of candidates) { + if (firstX === secondX) continue; + verticalXByConnector.set(orderedBundle[0].key, firstX); + verticalXByConnector.set(orderedBundle[1].key, secondX); + + const bundleScore = connectorConflictScore( + routes, + verticalXByConnector, + bundleKeys, + ); + const score = connectorConflictScore(routes, verticalXByConnector); + if ( + bundleScore.overlaps !== 0 || + bundleScore.clearanceConflicts !== 0 || + score.overlaps !== 0 || + score.crossings > previousScore.crossings + ) { + continue; + } + + const distanceFromBaseline = + Math.abs(firstX - previousRails[0]) + + Math.abs(secondX - previousRails[1]); + const distanceFromCenter = + Math.abs(firstX - preferredX) + Math.abs(secondX - preferredX); + const candidate: SeparateWinnerRailChoice = { + verticalXs: [firstX, secondX], + crossings: score.crossings, + distanceFromBaseline, + distanceFromCenter, + }; + if (!best || compareSeparateWinnerRailChoices(candidate, best) < 0) { + best = candidate; + } + } + } + + orderedBundle.forEach((route, index) => { + verticalXByConnector.set(route.key, previousRails[index]); + }); + if (!best) return null; + return new Map( + orderedBundle.map((route, index) => [route.key, best.verticalXs[index]]), + ); +} + +function compareSeparateWinnerRailChoices( + left: SeparateWinnerRailChoice, + right: SeparateWinnerRailChoice, +): number { + return ( + left.crossings - right.crossings || + left.distanceFromBaseline - right.distanceFromBaseline || + left.distanceFromCenter - right.distanceFromCenter || + left.verticalXs[0] - right.verticalXs[0] || + left.verticalXs[1] - right.verticalXs[1] + ); +} + +function connectorConflictScore( + routes: readonly ConnectorRoute[], + verticalXByConnector: ReadonlyMap, + focusedRouteKeys?: ReadonlySet, +): { crossings: number; overlaps: number; clearanceConflicts: number } { + let crossings = 0; + let overlaps = 0; + let clearanceConflicts = 0; + for (let leftIndex = 0; leftIndex < routes.length; leftIndex += 1) { + const leftX = verticalXByConnector.get(routes[leftIndex].key); + if (leftX === undefined) continue; + const leftSegments = connectorRouteSegments(routes[leftIndex], leftX); + for ( + let rightIndex = leftIndex + 1; + rightIndex < routes.length; + rightIndex += 1 + ) { + if ( + focusedRouteKeys && + !focusedRouteKeys.has(routes[leftIndex].key) && + !focusedRouteKeys.has(routes[rightIndex].key) + ) { + continue; + } + const rightX = verticalXByConnector.get(routes[rightIndex].key); + if (rightX === undefined) continue; + const rightSegments = connectorRouteSegments(routes[rightIndex], rightX); + for (const left of leftSegments) { + for (const right of rightSegments) { + if (left.orientation === right.orientation) { + const overlapLength = + Math.min(left.end, right.end) - Math.max(left.start, right.start); + if (left.fixed === right.fixed && overlapLength > 0) { + overlaps += 1; + } else if ( + left.orientation === "vertical" && + overlapLength > 0 && + Math.abs(left.fixed - right.fixed) < + DOUBLE_ELIMINATION_BRACKET_GEOMETRY.connectorRailClearance + ) { + clearanceConflicts += 1; + } + continue; + } + const horizontal = + left.orientation === "horizontal" ? left : right; + const vertical = left.orientation === "vertical" ? left : right; + if ( + vertical.fixed > horizontal.start && + vertical.fixed < horizontal.end && + horizontal.fixed > vertical.start && + horizontal.fixed < vertical.end + ) { + crossings += 1; + } + } + } + } + } + return { crossings, overlaps, clearanceConflicts }; +} + +function connectorRouteSegments( + route: ConnectorRoute, + verticalX: number, +): OrthogonalSegment[] { + return [ + orthogonalSegment("horizontal", route.sourceY, route.sourceX, verticalX), + orthogonalSegment("vertical", verticalX, route.sourceY, route.targetY), + orthogonalSegment("horizontal", route.targetY, verticalX, route.targetX), + ]; +} + +function orthogonalSegment( + orientation: OrthogonalSegment["orientation"], + fixed: number, + first: number, + second: number, +): OrthogonalSegment { + return { + orientation, + fixed, + start: Math.min(first, second), + end: Math.max(first, second), + }; +} + +function intervalsOverlap( + firstStart: number, + firstEnd: number, + secondStart: number, + secondEnd: number, +): boolean { + return ( + Math.min(firstStart, firstEnd) < Math.max(secondStart, secondEnd) && + Math.min(secondStart, secondEnd) < Math.max(firstStart, firstEnd) + ); +} + function connectorLabel( connector: SeriesConnectorView, graph: ValidatedGraph, diff --git a/apps/web/test/double-elimination-bracket-layout.test.ts b/apps/web/test/double-elimination-bracket-layout.test.ts index 793cbf81..0c51d7d6 100644 --- a/apps/web/test/double-elimination-bracket-layout.test.ts +++ b/apps/web/test/double-elimination-bracket-layout.test.ts @@ -367,6 +367,7 @@ test("orders mobile groups as winners, losers, grand final, then reset final", ( shuffledLayout.mobileGroups.map((group) => group.seriesIds), orderedLayout.mobileGroups.map((group) => group.seriesIds), ); + assert.deepEqual(shuffledLayout.connectors, orderedLayout.connectors); assert.deepEqual( shuffledLayout.mobileGroups.flatMap((group) => group.seriesIds).sort(), shuffled.projection.series.map((series) => series.seriesId).sort(), @@ -474,11 +475,10 @@ test("returns null instead of throwing for an unknown connector discriminator", ); }); -test("keeps connector rails distinct and outside intervening card rectangles", () => { +test("keeps connector rails finite and outside intervening card rectangles", () => { const { projection } = eightTeamProjection(); const layout = requireLayout(projection, EIGHT_TEAM_LAYOUT); const nodes = new Map(layout.nodes.map((node) => [node.seriesId, node])); - const routesByTargetColumn = new Map(); for (const route of layout.connectors) { const source = nodes.get(route.fromSeriesId); @@ -511,23 +511,256 @@ test("keeps connector rails distinct and outside intervening card rectangles", ( false, ); } + } +}); - const rails = routesByTargetColumn.get(target.column) ?? []; - rails.push(route.verticalX); - routesByTargetColumn.set(target.column, rails); +test("aligns paired winner bends on one shared rail", () => { + const fourTeam = fourTeamProjection(); + const fourTeamLayout = requireLayout(fourTeam.projection, FOUR_TEAM_LAYOUT); + for (const targetSeriesId of [fourTeam.ids.WB_FINAL, fourTeam.ids.GF]) { + const routes = winnerRoutesTo(fourTeamLayout, targetSeriesId); + assert.equal(routes.length, 2); + assert.equal(routes[0].verticalX, routes[1].verticalX); } - for (const rails of routesByTargetColumn.values()) { - assert.equal(new Set(rails).size, rails.length); + const { projection, ids } = eightTeamProjection(); + const layout = requireLayout(projection, EIGHT_TEAM_LAYOUT); + + for (const targetSeriesId of [ + ids.WB_R2_M1, + ids.WB_R2_M2, + ids.WB_FINAL, + ids.LB_R3_M1, + ids.GF, + ]) { + const routes = winnerRoutesTo(layout, targetSeriesId); + assert.equal(routes.length, 2); + assert.equal( + routes[0].verticalX, + routes[1].verticalX, + `${targetSeriesId} winner routes must share one bend rail`, + ); + } +}); + +test("keeps reversed winner slots on deterministic non-overlapping rails", () => { + const { projection, ids } = fourTeamProjection(); + const reversed = cloneProjection(projection); + const firstWinner = reversed.connectors.find( + ({ from, to }) => + from.seriesId === ids.WB_R1_M1 && + from.select === "winner" && + to.seriesId === ids.WB_FINAL, + ); + const secondWinner = reversed.connectors.find( + ({ from, to }) => + from.seriesId === ids.WB_R1_M2 && + from.select === "winner" && + to.seriesId === ids.WB_FINAL, + ); + assert.ok(firstWinner); + assert.ok(secondWinner); + firstWinner.to = { seriesId: ids.WB_FINAL, slot: "B" }; + secondWinner.to = { seriesId: ids.WB_FINAL, slot: "A" }; + + const orderedLayout = requireLayout(reversed, FOUR_TEAM_LAYOUT); + const shuffled = cloneProjection(reversed); + shuffled.connectors = shuffledCopy(shuffled.connectors); + const shuffledLayout = requireLayout(shuffled, FOUR_TEAM_LAYOUT); + const routes = winnerRoutesTo(orderedLayout, ids.WB_FINAL); + + assert.equal(routes.length, 2); + assert.equal(new Set(routes.map(({ verticalX }) => verticalX)).size, 2); + assert.equal(countCollinearConnectorOverlaps(orderedLayout.connectors), 0); + assert.deepEqual(shuffledLayout.connectors, orderedLayout.connectors); +}); + +test("moves reversed winner rails clear of overlapping connector underlays", () => { + const { projection, ids } = eightTeamProjection(); + const reversed = cloneProjection(projection); + const firstWinner = reversed.connectors.find( + ({ from, to }) => + from.seriesId === ids.WB_R1_M1 && + from.select === "winner" && + to.seriesId === ids.WB_R2_M1, + ); + const secondWinner = reversed.connectors.find( + ({ from, to }) => + from.seriesId === ids.WB_R1_M2 && + from.select === "winner" && + to.seriesId === ids.WB_R2_M1, + ); + assert.ok(firstWinner); + assert.ok(secondWinner); + firstWinner.to = { seriesId: ids.WB_R2_M1, slot: "B" }; + secondWinner.to = { seriesId: ids.WB_R2_M1, slot: "A" }; + + const layout = requireLayout(reversed, EIGHT_TEAM_LAYOUT); + const shuffled = cloneProjection(reversed); + shuffled.connectors = shuffledCopy(shuffled.connectors); + const shuffledLayout = requireLayout(shuffled, EIGHT_TEAM_LAYOUT); + const winners = winnerRoutesTo(layout, ids.WB_R2_M1); + + assert.equal(winners.length, 2); + for (const winner of winners) { + for (const route of layout.connectors) { + if ( + route === winner || + !intervalsStrictlyOverlap( + winner.sourceY, + winner.targetY, + route.sourceY, + route.targetY, + ) + ) { + continue; + } + assert.ok( + Math.abs(winner.verticalX - route.verticalX) >= + DOUBLE_ELIMINATION_BRACKET_GEOMETRY.connectorRailClearance, + `${winner.fromSeriesId} winner rail ${winner.verticalX} is too close to ${route.fromSeriesId} ${route.kind} rail ${route.verticalX}`, + ); + } + } + assert.deepEqual(shuffledLayout.connectors, layout.connectors); +}); + +test("centers conflict-free paired winner bends in the routing gap", () => { + const fourTeam = fourTeamProjection(); + const fourTeamLayout = requireLayout(fourTeam.projection, FOUR_TEAM_LAYOUT); + const fourTeamGrandFinal = nodeFor(fourTeamLayout, fourTeam.ids.GF); + assert.deepEqual( + winnerRoutesTo(fourTeamLayout, fourTeam.ids.GF).map( + ({ verticalX }) => verticalX, + ), + [ + fourTeamGrandFinal.x - + DOUBLE_ELIMINATION_BRACKET_GEOMETRY.columnGap / 2, + fourTeamGrandFinal.x - + DOUBLE_ELIMINATION_BRACKET_GEOMETRY.columnGap / 2, + ], + ); + + const { projection, ids } = eightTeamProjection(); + const layout = requireLayout(projection, EIGHT_TEAM_LAYOUT); + + for (const targetSeriesId of [ids.LB_R3_M1, ids.GF]) { + const target = nodeFor(layout, targetSeriesId); + const expectedVerticalX = + target.x - DOUBLE_ELIMINATION_BRACKET_GEOMETRY.columnGap / 2; + const routes = winnerRoutesTo(layout, targetSeriesId); + + assert.equal(routes.length, 2); + assert.deepEqual( + routes.map(({ verticalX }) => verticalX), + [expectedVerticalX, expectedVerticalX], + ); + } +}); + +test("preserves baseline rails for loser and reset paths", () => { + const { projection } = eightTeamProjection({ resetFinal: true }); + const layout = requireLayout(projection, EIGHT_TEAM_RESET_LAYOUT); + const nodes = new Map(layout.nodes.map((node) => [node.seriesId, node])); + const routesByTargetColumn = new Map(); + + for (const route of layout.connectors) { + const target = nodes.get(route.toSeriesId); + assert.ok(target); + const routes = routesByTargetColumn.get(target.column) ?? []; + routes.push(route); + routesByTargetColumn.set(target.column, routes); + } + + for (const routes of routesByTargetColumn.values()) { + routes.sort( + (left, right) => + right.sourceY - left.sourceY || + right.targetY - left.targetY || + connectorLayoutKey(left).localeCompare(connectorLayoutKey(right)), + ); + routes.forEach((route, index) => { + if (route.kind === "winner") return; + assert.equal( + route.verticalX, + route.targetX - + DOUBLE_ELIMINATION_BRACKET_GEOMETRY.columnGap + + (DOUBLE_ELIMINATION_BRACKET_GEOMETRY.columnGap * (index + 1)) / + (routes.length + 1), + ); + }); + } +}); + +test("keeps paired winner rails clear of overlapping loser paths", () => { + const fourTeam = fourTeamProjection(); + const eightTeam = eightTeamProjection(); + const fixtures = [ + { + layout: requireLayout(fourTeam.projection, FOUR_TEAM_LAYOUT), + pairedWinnerTargets: new Set([ + fourTeam.ids.WB_FINAL, + fourTeam.ids.GF, + ]), + }, + { + layout: requireLayout(eightTeam.projection, EIGHT_TEAM_LAYOUT), + pairedWinnerTargets: new Set([ + eightTeam.ids.WB_R2_M1, + eightTeam.ids.WB_R2_M2, + eightTeam.ids.WB_FINAL, + eightTeam.ids.LB_R3_M1, + eightTeam.ids.GF, + ]), + }, + ]; + + for (const { layout, pairedWinnerTargets } of fixtures) { + for (const winner of layout.connectors) { + if ( + winner.kind !== "winner" || + !pairedWinnerTargets.has(winner.toSeriesId) + ) { + continue; + } + for (const loser of layout.connectors) { + if ( + loser.kind !== "loser" || + !intervalsStrictlyOverlap( + winner.sourceY, + winner.targetY, + loser.sourceY, + loser.targetY, + ) + ) { + continue; + } + assert.ok( + Math.abs(winner.verticalX - loser.verticalX) >= + DOUBLE_ELIMINATION_BRACKET_GEOMETRY.connectorRailClearance, + `${winner.fromSeriesId} winner rail ${winner.verticalX} is too close to ${loser.fromSeriesId} loser rail ${loser.verticalX}`, + ); + } + } } }); test("minimizes connector crossings without introducing segment overlaps", () => { - const { projection } = eightTeamProjection(); - const layout = requireLayout(projection, EIGHT_TEAM_LAYOUT); + const fourTeam = fourTeamProjection(); + const fourTeamReset = fourTeamProjection({ resetFinal: true }); + const eightTeam = eightTeamProjection(); + const eightTeamReset = eightTeamProjection({ resetFinal: true }); + const layouts = [ + requireLayout(fourTeam.projection, FOUR_TEAM_LAYOUT), + requireLayout(fourTeamReset.projection, FOUR_TEAM_RESET_LAYOUT), + requireLayout(eightTeam.projection, EIGHT_TEAM_LAYOUT), + requireLayout(eightTeamReset.projection, EIGHT_TEAM_RESET_LAYOUT), + ]; - assert.equal(countStrictConnectorCrossings(layout.connectors), 12); - assert.equal(countCollinearConnectorOverlaps(layout.connectors), 0); + assert.ok(countStrictConnectorCrossings(layouts[2].connectors) <= 12); + for (const layout of layouts) { + assert.equal(countCollinearConnectorOverlaps(layout.connectors), 0); + } }); test("aligns connector endpoints with the A and B entry row centers", () => { @@ -921,6 +1154,18 @@ function segment( }; } +function intervalsStrictlyOverlap( + firstStart: number, + firstEnd: number, + secondStart: number, + secondEnd: number, +): boolean { + return ( + Math.min(firstStart, firstEnd) < Math.max(secondStart, secondEnd) && + Math.min(secondStart, secondEnd) < Math.max(firstStart, firstEnd) + ); +} + function countStrictConnectorCrossings(routes: readonly ConnectorLayout[]): number { let crossings = 0; for (let leftIndex = 0; leftIndex < routes.length; leftIndex += 1) { @@ -1009,6 +1254,16 @@ function nodeFor( return node; } +function winnerRoutesTo( + layout: NonNullable>, + targetSeriesId: SeriesId, +) { + return layout.connectors.filter( + (route) => + route.kind === "winner" && route.toSeriesId === targetSeriesId, + ); +} + function routeFrom( layout: NonNullable>, id: SeriesId, @@ -1036,6 +1291,10 @@ function connectorIdentity( }; } +function connectorLayoutKey(connector: ConnectorLayout): string { + return `${connector.fromSeriesId}:${connector.select}:${connector.toSeriesId}:${connector.toSlot}`; +} + function mobileGroupKeys( layout: NonNullable>, ) { diff --git a/docs/plans/double-elimination-connector-routing.md b/docs/plans/double-elimination-connector-routing.md new file mode 100644 index 00000000..a3eb0c58 --- /dev/null +++ b/docs/plans/double-elimination-connector-routing.md @@ -0,0 +1,84 @@ +# Implementation Plan: Double-Elimination Connector Routing + +## Overview + +Replace per-edge winner rail staggering with deterministic, collision-aware winner +bundles while retaining the existing target-corridor `H-V-H` path model and the +current loser/reset routing behavior. + +## Architecture Decisions + +- Keep routing as a pure layout calculation; the React renderer consumes unchanged + `BracketConnectorLayout` paths. +- Allocate baseline rails first, then choose one rail for each same-target winner + bundle while leaving loser/reset coordinates unchanged. +- Score complete candidate paths by parallel-stroke clearance, strict crossings, + and distance from the corridor midpoint. +- Permit shared `verticalX` only when the participating vertical intervals do not + overlap; otherwise search the same corridor for the nearest deterministic pair + of separate rails with focused-stroke clearance. + +## Task List + +### Phase 1: Regression Contract + +- [x] Add tests proving quiet winner bundles use the corridor midpoint and all + shareable same-target winner paths remain aligned. +- [x] Replace target-column rail uniqueness with interval-aware segment assertions. +- [x] Cover reversed A/B input where overlapping vertical spans require the + deterministic separate-rail fallback. +- [x] Confirm the focused test fails with the current allocator. + +### Checkpoint: RED + +- [x] The new behavioral assertion fails for the expected unequal `verticalX`. +- [x] Existing tests remain unchanged except where their invariant is obsolete. + +### Phase 2: Bundle-Aware Allocator + +- [x] Represent connector routing inputs with precomputed source/target anchors. +- [x] Retain stable independent rails for loser/reset routes. +- [x] Group the two winners entering each target and select the nearest safe shared + rail without card penetration, forbidden overlap, or avoidable added crossings. +- [x] Fall back to the nearest deterministic, stroke-clear separate rails only + when the pair's own vertical intervals overlap and cannot safely share a rail. + +### Checkpoint: GREEN + +- [x] Focused layout tests pass for four-team, eight-team, reset-final, and shuffled + input fixtures. +- [x] Strict crossing, collinear-overlap, and 5px parallel-clearance safeguards pass. + +### Phase 3: Verification and Review + +- [x] Run the full web suite, lint, and production build; document the unrelated + pre-existing full-lint failures while verifying changed files separately. +- [x] Inspect the diff for correctness, simplicity, security, performance, and + adherence to the approved spec. +- [x] Perform an independent review and address all required findings. + +### Checkpoint: Complete + +- [x] All success criteria in the spec are verified. +- [x] No unrelated files are modified. + +## Risks and Mitigations + +| Risk | Impact | Mitigation | +|---|---|---| +| Blind midpoint alignment adds crossings in busy upper rounds | High | Score complete candidate paths and move the winner bundle together to the nearest safe rail. | +| Shared rails create overlapping vertical segments | High | Check interval overlap before allowing a shared `verticalX`; search deterministic fallback rails with 5px clearance otherwise. | +| Visually parallel rails pass exact-coordinate tests but overlap at stroke width | High | Require 5px clearance across overlapping vertical runs and cover it for 4/8-team fixtures. | +| Routing changes depend on input array order | Medium | Sort routes and bundles by graph display order and retain shuffled-fixture equality tests. | +| A long connector bends through an intermediate card | High | Restrict every candidate to the target corridor and retain card-penetration assertions. | +| Reset-final slot carry-over is accidentally treated as a winner pair | Medium | Bundle only connectors whose computed kind is `winner`; keep reset paths independent. | + +## Dependencies + +```text +Regression contract -> bundle-aware rail allocator -> full verification -> review +``` + +## Open Questions + +None. diff --git a/docs/specs/double-elimination-connector-routing.md b/docs/specs/double-elimination-connector-routing.md new file mode 100644 index 00000000..96ee1edb --- /dev/null +++ b/docs/specs/double-elimination-connector-routing.md @@ -0,0 +1,134 @@ +# 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.