Overview

What @workspace/bridge exports, how it is layered, and where each part is documented.

@workspace/bridge is the pure-TypeScript bridge package: rules, engine, parsers, notation, deal validation and PBN/LIN conversion. It has no React or DOM dependency.

Runtime dependencies: @workspace/shared (error base classes, string and function helpers) and zod (validation schemas). Everything else is plain functions and constants.

Quick start

The engine is the configured entry point for everything that depends on the teaching mode or the locale; direct sub-path imports give the context-free functions.

index.ts

const engine = createBridgeEngine(
  createBridgeContext({ teachingMode: "auction", locale: "fr" })
);

engine.notation.parseRanks("RDV"); // => ["K", "Q", "J"]
engine.auction.calculateContract(new AuctionBuilder().fromCompact("N / 1S pass 2S AP").build());

index.ts

getPlayersInTrickOrder("W"); // => ["W", "N", "E", "S"]
calculateContract(new AuctionBuilder().fromCompact("N / 1H pass pass pass").build());

See Usage for when to pick one over the other.

There is no root import: every symbol is reached through one of the sub-paths declared in the package exports map. Each rules module (auction, card, hands, locale, notation, play, player, rotation, teaching) is a sub-path whose index.ts exposes the public surface of its own folder; the other files of the folder stay internal, and the matching engine module binds the context-dependent functions.

Rule: each module is imported through its own path; there is no forwarding file. A file whose exports come from another folder without a definition of its own does not exist in the package: an index.ts only exposes its own folder, and a definition lives in exactly one module.

Rule: a function is public outside the engine if and only if it is independent of the context. A function that takes a CoreConfig, BridgeContext, TeachingMode, SuitVariant or Locale is only reachable through engine.<module>, which binds those arguments from the BridgeContext. The exceptions are the entry points createBridgeContext and createBridgeEngine (with the BridgeContext type), and validateDeal, which receives the mode as data of the deal it validates.

Import path	Contents	Page
`@workspace/bridge/engine`	`createBridgeEngine`, `createBridgeContext`, `BridgeContext` and module config types	Engine
`@workspace/bridge/auction`	Per-call view (`auctionEntries`, `auctionTurn`), building an auction, bid validation, contract calculation, bid parsing (`BidInput`, `CallInput`), contract level, opener and counter status (`isCounterStatus`), expected result	Auction
`@workspace/bridge/card`	Card/rank/suit parsing and guards (`CardInput`, `CardParts`), rank sorting (`DEFAULT_RANK_ORDER`), suit display order	Card
`@workspace/bridge/hands`	Hand analysis, conversions, `areEmpty`, queries, transforms, HCP and Top-Honor-Tricks computers, PBN hand strings; completeness and filling are on `engine.hands`	Hands
`@workspace/bridge/locale`	The rank mapping reader and the suit mapping tables	Notation
`@workspace/bridge/notation`	`PETIT_BRIDGE_RANK_ORDER`, `RankMapping`, `RankFormatter`; parsing and formatting are on `engine.notation`	Notation
`@workspace/bridge/play`	Trick building, trick winner, follow-suit rules, legal cards	Play
`@workspace/bridge/player`	Seat navigation, rotation, partnerships and roles	Player
`@workspace/bridge/rotation`	`createRotater` for deals and comment text, comment rotation matchers	Rotation
`@workspace/bridge/teaching`	`parseTeaching`, `canonicalizeDealShapeForMode`	Teaching
`@workspace/bridge/constants`	Suits, ranks, players, bids, vulnerability, scoring, defaults, board numbering, teaching constants	Constants
`@workspace/bridge/factories`	Factories for hands, random auctions and whole board games	Factories
`@workspace/bridge/errors`	Validation error types and factories, PBN error classes	Errors
`@workspace/bridge/lin`	LIN serialization (`serializeDealToLIN`)	LIN
`@workspace/bridge/pbn`	PBN file parsing and serialization, `DealCommentSummary`	PBN
`@workspace/bridge/schemas/*`	Zod schemas, one file per concept (see below)	Schemas
`@workspace/bridge/types`	All domain types	Types
`@workspace/bridge/testing`	`makeDeal`, builders with random defaults (`DealBuilder`, `AuctionBuilder`, …) and named scenarios for tests and docs	Testing
`@workspace/bridge/parsers`	Contract, scoring and vulnerability string parsers	Parsers
`@workspace/bridge/utils/*`	Stateless utilities that belong to no rules module, one file each (see below)	Utils
`@workspace/bridge/format/*`	Display formatting (see below)	Format
`@workspace/bridge/validation`	Full deal validation and save decision	Validation

`utils/*`

Sub-path	Contents
`utils/contract`	`getTrumpFromContract`, `formatContractForIndex`
`utils/scoring`	Scoring-mode guards and duplicate-bridge scoring (`computeDuplicateScore`, `duplicateScore`, `contractScore`)
`utils/vulnerability`	Per-player vulnerability status and guards, `isSideVulnerable`

Foundation — types, constants, errors.
Primitives — card, player, notation, format, parsers: stateless helpers.
Domain — auction, hands, play, rotation, teaching: game rules, some parameterised by a CoreConfig.
Cross-cutting — schemas, validation, utils, pbn, lin, factories, testing.
Integration — engine: resolves a CoreConfig from the BridgeContext and composes the 13 modules.

The teaching mode decides the CoreConfig (card count, valid ranks, auction kind, denominations, deck); the locale decides notation. Both are described in Game Modes.

Source layout

auction-contract.ts

auction-entries.ts

auction-state.ts

auction-summary.ts

auction-validation.ts

bid-pad-flags.ts

bid-parsing.ts

contract-level.ts

counter-status.ts

format-result-expected-label.ts

index.ts

is-result-reachable.ts

required-tricks.ts

resolve-expected-result.ts

engine.ts

index.ts

types.ts

auction-module.ts

constants-module.ts

context-module.ts

format-module.ts

hands-module.ts

notation-module.ts

parse-module.ts

pbn-module.ts

play-module.ts

player-module.ts

schemas-module.ts

stats-module.ts

bids.ts

board-numbering.ts

book.ts

card-set.ts

cards.ts

core-config.ts

defaults.ts

game-facts.ts

index.ts

locale.ts

pbn.ts

players.ts

result.ts

scoring.ts

teaching.ts

tricks.ts

unset.ts

vulnerability.ts

card-parsing.ts

card-sort.ts

index.ts

suit-order.ts

factories.ts

index.ts

notation.ts

pbn.ts

types.ts

index.ts

serialize-deal-to-lin.ts

hands-analysis.ts

hands-converts.ts

hands-distribution.ts

hands-pbn.ts

hands-queries.ts

hands-transforms.ts

hands-validation.ts

honors.ts

index.ts

auction.ts

contract-outcome.ts

contract.ts

hands.ts

play.ts

format-rank.ts

index.ts

rank-mappings.ts

suit-mappings.ts

format-ranks.ts

index.ts

parse-ranks.ts

rank-formatters.ts

types.ts

create-auction.ts

create-board-game.ts

create-hands.ts

create-play.ts

index.ts

types.ts

index.ts

parseContract.ts

parseScoring.ts

parseVulnerability.ts

index.ts

play-tricks.ts

compose-pbn-file.ts

convert-deal-to-pbn-deal.ts

convert-pbn-deal.ts

create-empty-deal.ts

detect-deal-comments.ts

dup-to-pbn.ts

encoding.ts

handle-pbn-data.ts

parse-pbn-content.ts

parse-pbn-file.ts

parser-state.ts

pbn-notes.ts

pbn-tokenizer.ts

pbn.ts

preprocess-pbn-comment.ts

preprocess-pbn-content.ts

read-pbn-source.ts

serialize-multi-deal.ts

serialize-pbn-file.ts

source-lines.ts

utils.ts

parse-contract.ts

parse-player-tag.ts

parse-player.ts

parse-result.ts

parse-scoring.ts

parse-teaching.ts

parse-vulnerability.ts

format-contract.ts

format-scoring.ts

format-vulnerability.ts

parse-contract.ts

parse-pbn-auction.ts

parse-pbn-play.ts

serialize-auction.ts

serialize-comment.ts

serialize-header.ts

serialize-play.ts

serialize-tags.ts

check-auction.ts

check-hands.ts

check-play.ts

check-tags.ts

codes.ts

diagnose-pbn.ts

index.ts

player-navigation.ts

player-rotation.ts

player-team.ts

canonical-deal.ts

index.ts

parse-teaching.ts

bid.ts

card.ts

deal.ts

game-params.ts

hands.ts

play.ts

player.ts

scoring.ts

teach-params.ts

vulnerability.ts

index.ts

rotater.ts

rotation-comments.ts

rotation-deal.ts

rotation-vulnerability.ts

contract.ts

scoring.ts

vulnerability.ts

auction.builder.ts

contract.builder.ts

create-random-auction.ts

deal.builder.ts

hands.builder.ts

index.ts

parse-player.ts

pbn-deal.builder.ts

pbn-source.builder.ts

play.builder.ts

random.ts

scenarios.ts

Analysis.ts

Auction.ts

Bid.ts

Config.ts

Contract.ts

Deal.ts

Hands.ts

Locale.ts

PBN.ts

Par.ts

Play.ts

Player.ts

Scoring.ts

TeachingMode.ts

Vulnerability.ts

index.ts

codes.ts

deal-validation.ts

index.ts

par-warning-check.ts

save-decision.ts

Quick start

Sub-path exports

`utils/*`

`schemas/*`

`format/*`

Architecture

Source layout

On this page