@stargazeryan/poker-ui 0.4.3 → 0.6.0

package/dist/index.d.cts

@@ -4,10 +4,140 @@ import { ReactNode, CSSProperties } from 'react';
 /** Join class names and resolve conflicting Tailwind utilities (last wins). */
 declare function cn(...parts: Array<string | false | null | undefined>): string;
 
-/** Big Blind value used for stack display. */
+/**
+ * Default big blind that `formatBB` uses when you do not pass one.
+ *
+ * Kept for back-compat. Nothing in the package applies it on your behalf: the
+ * components render plain numbers unless you hand them a formatter, because a
+ * big blind is a poker rule and this is not a poker library.
+ */
 declare const BB = 20;
-/** Format a chip amount as a Big-Blind string, e.g. 1234 -> "61.7 BB". */
-declare function formatBB(amount: number): string;
+/**
+ * Format an amount as big blinds, e.g. 1234 -> "61.7 BB".
+ *
+ * This is a poker *helper*, not a default. Pass your own big blind — a
+ * fixed 20 is wrong for most tables:
+ *
+ * ```ts
+ * <Pot amount={1234} format={(n) => formatBB(n, 100)} />
+ * ```
+ */
+declare function formatBB(amount: number, bb?: number): string;
+
+/**
+ * Colour maths. Nothing here knows about cards, chips or games — this is the
+ * generic layer that contrast decisions are built on.
+ *
+ * It exists because the package needs to answer "would this be visible on top of
+ * that?" in more than one place (edge spots on a chip, and anything else that
+ * grows a light/dark ink choice later), and that question should not live inside
+ * a component or a game-specific module.
+ */
+interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    /** 0–1. */
+    a: number;
+}
+/**
+ * Parse `#rgb`, `#rrggbb`, `rgb()` or `rgba()` into channels.
+ *
+ * Returns `null` for anything else — a `var(...)`, a named colour, a value with
+ * a color-mix() in it. Callers are expected to have a sensible fallback rather
+ * than guess, which is why this does not throw.
+ */
+declare function parseColor(color: string): Rgba | null;
+/** WCAG relative luminance (0 = black, 1 = white). `null` if unparseable. */
+declare function relativeLuminance(color: string): number | null;
+/** Composite a possibly translucent colour over an opaque one. */
+declare function flatten(foreground: string, background: string): Rgba | null;
+/**
+ * WCAG contrast ratio between two colours, 1–21. `foreground` may be
+ * translucent, in which case it is composited over `background` first — which is
+ * the question you actually have when you are choosing an ink colour.
+ *
+ * `null` if either colour is unparseable.
+ */
+declare function contrastRatio(foreground: string, background: string): number | null;
+/**
+ * Pick whichever candidate is more visible on `background`.
+ *
+ * Derived from measured contrast rather than a hand-tuned luminance threshold,
+ * so a mid-tone background gets the genuinely better of the two instead of
+ * whichever side of an arbitrary cut-off it fell on. Falls back to the first
+ * candidate when the background cannot be measured.
+ */
+declare function mostVisible(candidates: readonly string[], background: string): string;
+
+/**
+ * The size vocabulary, in one place.
+ *
+ * Cards and chips keep their own pixel tables — a `sm` card and a `sm` chip are
+ * different objects and pretending otherwise would be worse — but they share one
+ * list of names. That way adding an `xl` to the vocabulary is a single edit and
+ * a component cannot silently support a size the type does not mention.
+ */
+declare const SIZES: readonly ["xs", "sm", "md", "lg"];
+/** Any size in the vocabulary. */
+type Size = (typeof SIZES)[number];
+/** `PlayingCard` / `HoleCards` / `CommunityCards`: the full range. */
+type CardSize = Size;
+/** `Chip` / `ChipStack`: a chip has no `xs`. */
+type ChipSize = Exclude<Size, "xs">;
+
+/**
+ * Animation timing, in one place.
+ *
+ * These were magic numbers inside three components. They are kept short on
+ * purpose: the on-by-default animations are game feel, and a consumer who wants
+ * a different tempo turns them off rather than tuning them.
+ */
+/** How long the pot takes to count from one value to the next, in ms. */
+declare const COUNT_UP_MS = 500;
+/** Stagger between hole cards dealing in, in ms. */
+declare const DEAL_STAGGER_MS = 100;
+/** Stagger between community cards flipping in, in ms. */
+declare const FLIP_STAGGER_MS = 70;
+
+/**
+ * Card codes and how to say them out loud. Pure functions, no React.
+ *
+ * This lives outside the component because two things need it: the artwork
+ * (`PlayingCard` / `CardBack`, for the accessible name) and any consumer
+ * building a hand list, a log line or a replay. A single vocabulary is what
+ * stops every call site inventing its own way of saying "As".
+ */
+interface ParsedCard {
+    rank: string;
+    suit: string;
+}
+/**
+ * Split a compact card code like `"As"` or `"10h"` into rank and suit.
+ *
+ * Deliberately permissive: it takes the last character as the suit and trusts
+ * the rest, so `"xyz"` parses as rank `"xy"` / suit `"z"`. Validation is a known
+ * gap — use `describeCard`, which falls back to the raw code rather than
+ * pretending to know what it read.
+ */
+declare function parseCard(card: string): ParsedCard;
+/** The glyph for a suit letter. Unknown suits are passed through unchanged. */
+declare function getSuitSymbol(suit: string): string;
+/** `"A"` → `"Ace"`, `"10"` → `"Ten"`. Unknown ranks pass through. */
+declare function getRankName(rank: string): string;
+/** `"s"` → `"spades"`. Unknown suits pass through. */
+declare function getSuitName(suit: string): string;
+/** Hearts and diamonds are the red ones. */
+declare function isRedSuit(suit: string): boolean;
+/** Whether a suit letter is one this package knows how to draw. */
+declare function isKnownSuit(suit: string): boolean;
+/**
+ * A spoken description: `"As"` → `"Ace of spades"`, `null` → `"face-down card"`.
+ *
+ * Returns the raw code when the rank or suit is not recognised, rather than
+ * announcing something the card is not.
+ */
+declare function describeCard(card: string | null): string;
 
 /**
  * Seat-ring helpers. Pure functions — they contain no game-specific rules.
@@ -25,18 +155,194 @@ interface NextSeatOptions {
  */
 declare function nextSeatIndex(current: number, seatCount: number, opts?: NextSeatOptions): number;
 
-type CardSize = "xs" | "sm" | "md" | "lg";
-/** Parse a compact card code like "As", "10h", "kd" into rank + suit. */
-declare function parseCard(card: string): {
-    rank: string;
-    suit: string;
+/**
+ * Pure ellipse geometry for the card table. No game rules, no React.
+ *
+ * Everything is derived from one parametric ellipse:
+ *
+ *   x(θ) = cx + rx·cos θ
+ *   y(θ) = cy + ry·sin θ
+ *
+ * with θ in degrees. Screen coordinates (y grows downward), so θ = 90° is the
+ * point directly BELOW the centre.
+ *
+ * Seat 0 sits at `startAngle` (default 90° = directly below the centre) and
+ * every following seat advances by `360 / seatCount`, so any count from 2 to 10
+ * spreads evenly. The betting line uses the same formula with a smaller radius.
+ */
+interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Ring angle (degrees) of seat `index`, evenly divided around 360°.
+ * Seat 0 is at `startAngle` (default 90° = directly below the table centre).
+ */
+declare function seatAngle(index: number, seatCount: number, startAngle?: number): number;
+/** Point on the ellipse at `angleDeg` (degrees; 90° = below the centre). */
+declare function ellipsePoint(cx: number, cy: number, rx: number, ry: number, angleDeg: number): Point;
+/**
+ * `count` evenly spaced points on an ellipse, starting at `startAngle`
+ * (default 90° = directly below the centre). Handy for seat rings and betting
+ * lines alike: pass the ring radii, get the coordinates.
+ */
+declare function ringPoints(count: number, cx: number, cy: number, rx: number, ry: number, startAngle?: number): Point[];
+
+/**
+ * Pure layout math for the card table. No React, no game rules.
+ *
+ * Everything is derived from one parametric ellipse (see `geometry.ts`). The
+ * table, the felt, the rim, the seat ring and the betting line are ellipses
+ * sharing a centre and an aspect ratio, and they are all computed **here**.
+ *
+ * That matters: the betting line used to be computed inside `CardTable` from a
+ * module constant while the chips were positioned from the `betRadiusScale`
+ * prop, and the two drifted apart. One ellipse, one place that computes it.
+ */
+/** Default design space. */
+declare const DESIGN_W = 1200;
+declare const DESIGN_H = 900;
+/** Rail inset as a fraction of the design box (164/1200, 196/900). */
+declare const DEFAULT_MARGIN_X: number;
+declare const DEFAULT_MARGIN_Y: number;
+/** Gap between the rail and the felt, in design-space px. */
+declare const DEFAULT_FELT_GAP = 11;
+/** Default radius of the bet ring, as a fraction of the table radius. */
+declare const DEFAULT_BET_SCALE = 0.72;
+/** Default minimum clearance between neighbouring seat frames. */
+declare const DEFAULT_SEAT_GAP = 24;
+/** Default preferred seat frame size. */
+declare const DEFAULT_SEAT_W = 160;
+declare const DEFAULT_SEAT_H = 176;
+/** How far inside the rail the rim highlight sits, in design-space px. */
+declare const RIM_GAP = 6;
+/** How far inside the rail the your-turn glow sits, in design-space px. */
+declare const GLOW_GAP = 2;
+interface LayoutOptions {
+    /** Number of seats. */
+    count: number;
+    /** Design-space width / height. */
+    designWidth: number;
+    designHeight: number;
+    /** Rail inset as a fraction of designWidth / designHeight (0..0.5). */
+    marginX: number;
+    marginY: number;
+    /** Felt inset from the rail, in design-space px. */
+    feltGap: number;
+    /** Preferred (maximum) seat frame size. */
+    seatWidth: number;
+    seatHeight: number;
+    /**
+     * Minimum clearance in design-space px to keep between neighbouring seat
+     * frames. Frames are shrunk uniformly (never below `SEAT_SHRINK_FLOOR`) to
+     * honour it. `0` disables the shrink entirely.
+     */
+    seatGap: number;
+    /** Angle of seat 0, in degrees. */
+    startAngle: number;
+    /** Where the betting line sits, as a fraction of the table radii. Default 0.72. */
+    betRadiusScale?: number;
+}
+interface SeatLayout {
+    index: number;
+    /** Centre of the seat frame, in design space. */
+    x: number;
+    y: number;
+    /** Frame size the layout was computed for (≤ the preferred size when shrunk). */
+    width: number;
+    height: number;
+}
+/**
+ * How far an ellipse sits inside the design box, in design-space px. Spread it
+ * onto an absolutely-positioned element and the ellipse lands where the rest of
+ * the layout expects.
+ */
+interface EllipseBox {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface Layout {
+    /** Seat centre used for every ring, in design space. */
+    cx: number;
+    cy: number;
+    /** Radii of the outer table ellipse. */
+    tableRx: number;
+    tableRy: number;
+    /** Radii of the seat ring. */
+    ringRx: number;
+    ringRy: number;
+    /** Radii of the betting line. */
+    betRx: number;
+    betRy: number;
+    /** Seat frame size actually used. */
+    seatW: number;
+    seatH: number;
+    seats: SeatLayout[];
+    /** Every ellipse the table draws, ready to position. */
+    boxes: {
+        table: EllipseBox;
+        felt: EllipseBox;
+        rim: EllipseBox;
+        glow: EllipseBox;
+        bettingLine: EllipseBox;
+    };
+}
+/** Smallest fraction of the preferred seat size the auto-shrink will go to. */
+declare const SEAT_SHRINK_FLOOR = 0.5;
+/** Radii of the table ellipse for a given design box and rail inset. */
+declare function tableRadii(designWidth: number, designHeight: number, marginX: number, marginY: number): {
+    rx: number;
+    ry: number;
 };
-declare function getSuitSymbol(suit: string): string;
+/**
+ * Radii of the seat ring. Seats ride the ring at `+ seatSize / 2 + 6`, so the
+ * frames straddle the rail, but never past the design box (seats at the extreme
+ * left / right / top / bottom used to be clipped in narrow layouts).
+ */
+declare function seatRingRadii(designWidth: number, designHeight: number, tableRx: number, tableRy: number, seatW: number, seatH: number, feltGap: number): {
+    rx: number;
+    ry: number;
+};
+/** Centre point of seat `index` on the seat ring, in design space. */
+declare function seatPoint(index: number, count: number, cx: number, cy: number, ringRx: number, ringRy: number, startAngle?: number): {
+    x: number;
+    y: number;
+};
+/** Turn radii into the inset box of an absolutely-positioned ellipse. */
+declare function ellipseBox(designWidth: number, designHeight: number, rx: number, ry: number): EllipseBox;
+/**
+ * Smallest gap between any two seat frames, over every pair. Positive means no
+ * frames overlap. Returns `Infinity` for fewer than two seats.
+ */
+declare function minSeatSeparation(seats: SeatLayout[]): number;
+/**
+ * Pick the largest uniform scale (1 → `SEAT_SHRINK_FLOOR`, in 1% steps) at which
+ * every pair of seat frames clears `seatGap`. Returns the scale to apply.
+ *
+ * A 10-seat table at the default 160x176 frames only leaves ~26px between
+ * neighbours, which reads as crowded; shrinking them a little spreads the ring
+ * out. It is also what makes 11–16 seats possible at all. Wide tables (2–8
+ * seats) are unaffected — they pass on the first step.
+ */
+declare function fitSeatScale(opts: LayoutOptions): number;
+/**
+ * Everything the table draws for one configuration: the table ellipse, the felt,
+ * the rim, the glow ring, the betting line, the seat ring and every seat centre.
+ */
+declare function layoutSeats(opts: LayoutOptions): Layout;
+
 interface PlayingCardProps {
     /** Compact card code ("As", "10h") or null to render a face-down card back. */
     card: string | null;
     /** xs / sm show a single, larger, centered index; md / lg show corner + center. */
     size?: CardSize;
+    /**
+     * Accessible name. Defaults to `describeCard(card)` — "Ace of spades" rather
+     * than the fragments "A" and "♠" a screen reader would otherwise read out.
+     */
+    label?: string;
     className?: string;
 }
 /**
@@ -44,22 +350,30 @@ interface PlayingCardProps {
  * breakpoints) so cards scale predictably inside any container. Small sizes
  * (xs / sm) show only a larger upright index, centered in the card.
  */
-declare function PlayingCard({ card, size, className }: PlayingCardProps): react.JSX.Element;
+declare function PlayingCard({ card, size, label, className }: PlayingCardProps): react.JSX.Element;
 interface CardBackProps {
     size?: CardSize;
+    /** Accessible name. Defaults to "face-down card". */
+    label?: string;
     className?: string;
 }
 /** The face-down card back (dark red + gold rosette). */
-declare function CardBack({ size, className }: CardBackProps): react.JSX.Element;
+declare function CardBack({ size, label, className }: CardBackProps): react.JSX.Element;
 interface HoleCardsProps {
     cards: (string | null)[];
     size?: CardSize;
     className?: string;
     /** Animate the cards dealing in, one after another. Default true. */
     deal?: boolean;
+    /**
+     * Change this to replay the deal animation for an unchanged hand (e.g. a hand
+     * id or a round number). Without it, a card whose value changed re-deals on
+     * its own, but a new hand holding the same two cards looks identical.
+     */
+    dealKey?: string | number;
 }
 /** A row of a player's hole cards. */
-declare function HoleCards({ cards, size, className, deal }: HoleCardsProps): react.JSX.Element;
+declare function HoleCards({ cards, size, className, deal, dealKey }: HoleCardsProps): react.JSX.Element;
 interface CommunityCardsProps {
     cards: (string | null)[];
     size?: CardSize;
@@ -72,6 +386,126 @@ interface CommunityCardsProps {
 /** A row of community cards, each flipping in with a staggered delay. */
 declare function CommunityCards({ cards, size, className, animated, slots }: CommunityCardsProps): react.JSX.Element;
 
+/**
+ * Chip denominations and the breakdown of an amount into chips. Pure functions,
+ * no React — the same split as `geometry.ts` and `layout.ts`.
+ *
+ * Amounts are in **chip units** (the smallest chip is 1), not in big blinds.
+ */
+interface Denomination {
+    /** Face value of the chip. */
+    value: number;
+    /**
+     * Printed on the chip face. Defaults to the value, which is what you want for
+     * a 5 or a 100; use it for a "$5" or a "5K" if your table reads differently.
+     */
+    label?: string;
+    /**
+     * CSS colour for the body. Used directly as the SVG `fill`, so it can be any
+     * CSS colour — including `var(--color-chip-red)`.
+     */
+    color: string;
+    /**
+     * Colour of the eight edge spots. Defaults to white, or to a dark spot on a
+     * light body — see `chipSpotColor`.
+     */
+    spotColor?: string;
+    /**
+     * Optional `fill-*` utility applied on top of `color`. The default set uses
+     * these so the `--color-chip-*` theme tokens are actually emitted by Tailwind
+     * (it only outputs a theme variable something references) and can therefore be
+     * overridden from a consumer's `@theme` block like every other token.
+     *
+     * A class wins over the `fill` attribute, so `color` acts as the fallback.
+     */
+    className?: string;
+}
+/**
+ * The classic low-stakes set: white 1, red 5, blue 10, green 25, black 100.
+ *
+ * Blue is the one that varies between houses — plenty of rooms use blue for
+ * $10 and plenty for $20. Ten is the default here; override
+ * `denominations` to use twenty.
+ */
+declare const DEFAULT_DENOMINATIONS: Denomination[];
+/**
+ * Spot colour for a chip body: whichever of the two inks is measurably more
+ * visible on it.
+ *
+ * Derived from contrast rather than a luminance threshold, because the obvious
+ * implementation — always white spots — puts the white chip
+ * (`--color-chip-white`, #ecf0f1) at a 1.13:1 contrast ratio against its own
+ * body, so it renders as a blank oval with no edge at all. Colours we cannot
+ * measure keep white spots.
+ */
+declare function chipSpotColor(bodyColor: string): string;
+interface ChipStackEntry extends Denomination {
+    /** How many chips of this denomination the amount needs. */
+    count: number;
+}
+/**
+ * Break an amount into chips, largest denomination first (the greedy breakdown
+ * a dealer actually uses).
+ *
+ * Anything below the smallest denomination is left out rather than rounded up —
+ * `chipsTotal()` tells you what the chips add up to, so you can spot the
+ * remainder. Non-integer and negative amounts are floored/clamped to 0.
+ */
+declare function chipBreakdown(amount: number, denominations?: Denomination[]): ChipStackEntry[];
+/** What a set of chip entries adds up to. Compare with the amount to see the remainder. */
+declare function chipsTotal(entries: ChipStackEntry[]): number;
+/** Total number of physical chips in a breakdown. */
+declare function chipCount(entries: ChipStackEntry[]): number;
+
+interface ChipProps {
+    /** Printed on the centre of the face. */
+    value?: number | string;
+    /** CSS colour for the body. */
+    color?: string;
+    /** `fill-*` utility applied over `color` — see `Denomination.className`. */
+    colorClassName?: string;
+    /** Colour of the eight edge spots. Defaults to `chipSpotColor(color)`. */
+    spotColor?: string;
+    /** Default `"md"`. */
+    size?: ChipSize;
+    /** Accessible name. Defaults to `"<value> chip"`. */
+    label?: string;
+    className?: string;
+}
+/**
+ * A single chip, drawn as SVG: a coloured disc with a darker edge for
+ * thickness, eight white edge spots, a rim highlight and a white centre carrying
+ * the value.
+ *
+ * The colours come from `--color-chip-*` via `fill-*` utilities, so the chip
+ * palette is themeable like every other token.
+ */
+declare function Chip({ value, color, colorClassName, spotColor, size, label, className, }: ChipProps): react.JSX.Element;
+interface ChipStackProps {
+    /** Amount in chip units — see `chipBreakdown`. */
+    amount: number;
+    /** Default `"md"`. */
+    size?: ChipSize;
+    /** Default `DEFAULT_DENOMINATIONS` (white 1, red 5, blue 10, green 25, black 100). */
+    denominations?: Denomination[];
+    /**
+     * Most chips to draw, biggest denominations first. A 10,000 bet would
+     * otherwise be 100 black chips. The count of the chips left off is shown
+     * underneath. Default 12.
+     */
+    maxChips?: number;
+    /** Content under the stack — usually the formatted amount. */
+    label?: ReactNode;
+    className?: string;
+}
+/**
+ * The chips for an amount: a real stack, largest denomination on top.
+ *
+ * The accessible name is the full breakdown ("240 in 4 chips: 2x100, 1x25,
+ * 1x10"), so a screen reader gets the value rather than four anonymous images.
+ */
+declare function ChipStack({ amount, size, denominations, maxChips, label, className, }: ChipStackProps): react.JSX.Element;
+
 interface SeatProps {
     /** Turn/active highlight (generic). Animated by default. */
     isActive?: boolean;
@@ -105,7 +539,13 @@ interface SeatProps {
     topRight?: ReactNode;
     /** Slot: floating content centered above the top edge (e.g. D/SB/BB badges). */
     topCenter?: ReactNode;
+    /**
+     * Frame width. Defaults to the size the surrounding `CardTable` laid out for
+     * this seat, or 160 outside a table — the table is the one that knows how much
+     * room the ring has.
+     */
     width?: number;
+    /** Frame height. Defaults to the laid-out size, or 176 outside a table. */
     height?: number;
     className?: string;
     /** Extra classes for the inner frame, to override visuals. */
@@ -125,7 +565,10 @@ interface PotProps {
     amount: number;
     /** Optional label, e.g. "Main" / "Side". */
     label?: string;
-    /** Formatter for the amount; defaults to Big-Blind formatting. */
+    /**
+     * Formatter for the amount. Defaults to a plain, locale-grouped number —
+     * pass one if your amounts have a unit.
+     */
     format?: (amount: number) => string;
     /** Animate the amount counting up when it changes. Default true. */
     animate?: boolean;
@@ -134,14 +577,54 @@ interface PotProps {
 /** A small, standalone pot pill. Optional — the table does not require it. */
 declare function Pot({ amount, label, format, animate, className }: PotProps): react.JSX.Element;
 
+/** Geometry CardTable laid a seat frame out for, handed to `renderSeat`. */
+interface SeatBox {
+    index: number;
+    isYou: boolean;
+    /** Centre of the frame, in design space. */
+    x: number;
+    y: number;
+    /** Frame size the ring was laid out for (≤ `seatWidth`/`seatHeight`). */
+    width: number;
+    height: number;
+}
 interface CardTableProps {
-    /** Number of seats (2–10). Default 6. */
+    /**
+   * Number of seats. Default 6.
+   *
+   * There is no upper limit. The seat ring shrinks the frames until `seatGap` is
+   * honoured, so 11–16 seats lay out fine (measured: 11 -> 126x139 frames,
+   * 16 -> 80x88). Past roughly 16 the frames hit the 50% shrink floor and start
+   * to overlap — that is the caller's call, not something to clamp silently.
+   */
     seatCount?: number;
     /** Optional per-seat content. Length should equal `seatCount`. */
     seats?: (ReactNode | null)[];
-    /** Alternative to `seats`: render a seat by index. */
-    renderSeat?: (index: number, isYou: boolean) => ReactNode;
-    /** Which seat belongs to the viewer; rotates that seat to the bottom. */
+    /**
+     * Alternative to `seats`: render a seat by index. Receives the laid-out
+     * frame box as a third argument, so an auto-shrunk seat can be sized to
+     * match the ring: `<Seat width={box.width} height={box.height} />`.
+     */
+    renderSeat?: (index: number, isYou: boolean, box: SeatBox) => ReactNode;
+    /**
+     * Optional per-seat "bet" content, auto-positioned on the betting line
+     * (`betRadiusScale`) along the seat-to-center radius, so it faces the middle
+     * of the table. Length should equal `seatCount`; `null` entries are skipped.
+     */
+    bets?: (ReactNode | null)[];
+    /** Alternative to `bets`: render a bet by index (return `null` to skip). */
+    renderBet?: (index: number) => ReactNode;
+    /**
+     * Radius of the bet ring, as a fraction of the table radius. Default 0.72.
+     * The drawn betting line follows this value. Clamped to 0.2–1.
+     */
+    betRadiusScale?: number;
+    /**
+     * Angle (degrees) of seat 0. Default 90° = directly below the table centre.
+     * Seats advance by `360 / seatCount` from there, so 2–10 players spread evenly.
+     */
+    startAngle?: number;
+    /** Which seat is the viewer (adds no offset; only flags `isYou`). Default null. */
     yourSeatIndex?: number | null;
     /** Optional content in the middle of the table (cards, pot, anything). */
     center?: ReactNode;
@@ -153,16 +636,57 @@ interface CardTableProps {
     winnerSeats?: number[];
     /** Show confetti for winners. Default true. */
     confetti?: boolean;
-    /** Seat frame size used for layout. */
+    /**
+     * Confetti colours. Defaults to a party palette. This is a prop rather than a
+     * theme token because the colours land in inline styles, which Tailwind's
+     * tree-shaking cannot see — a custom property nothing references never gets
+     * emitted.
+     */
+    confettiColors?: string[];
+    /** Preferred seat frame width. Default 160. */
     seatWidth?: number;
+    /** Preferred seat frame height. Default 176. */
     seatHeight?: number;
+    /**
+     * Minimum clearance to keep between neighbouring seat frames, in design-space
+     * px. Frames shrink uniformly (down to 50%) until it is honoured, which is what
+     * keeps 9–10 seat tables from looking cramped and what lets 11–16 seat tables
+     * lay out at all. `0` disables it.
+     * Only applies when `renderSeat` is used (it is the only form that can size
+     * the frames); the `seats` array keeps the size you were given.
+     * Default 24.
+     */
+    seatGap?: number;
+    /** Design-space width. Default 1200. */
+    designWidth?: number;
+    /** Design-space height. Default 900. */
+    designHeight?: number;
+    /**
+     * Rail inset as a fraction of the design box (default 164/1200).
+     * Proportional so a custom design box stays in proportion.
+     */
+    marginX?: number;
+    /** Rail inset as a fraction of the design box (default 196/900). */
+    marginY?: number;
+    /** Felt inset from the rail, in design-space px. Default 11. */
+    feltGap?: number;
+    /**
+     * How the design box relates to the container.
+     * - `"design"` (default): scale the fixed design box to fit — preserves the
+     *   table's proportions but letterboxes non-matching containers.
+     * - `"container"`: derive the design width from the container's aspect ratio
+     *   (clamped to 0.5–2.5) so the table fills the box instead of letterboxing.
+     *   Use this for phone-portrait layouts. Pair with `designHeight` to set the
+     *   scale.
+     */
+    fit?: "design" | "container";
     className?: string;
 }
 /**
- * A responsive, game-agnostic card table. It scales a fixed 1200x900 design
- * onto its container and arranges `seatCount` seats around the felt. Purely
- * presentational: supply seat content and an optional `center` slot.
+ * A responsive, game-agnostic card table. It scales a design box (1200x900 by
+ * default) onto its container and arranges `seatCount` seats around the felt.
+ * Purely presentational: supply seat content and an optional `center` slot.
  */
-declare function CardTable({ seatCount, seats, renderSeat, yourSeatIndex, center, ambient, yourTurn, winnerSeats, confetti, seatWidth, seatHeight, className, }: CardTableProps): react.JSX.Element;
+declare function CardTable({ seatCount, seats, renderSeat, bets, renderBet, betRadiusScale, startAngle, yourSeatIndex, center, ambient, yourTurn, winnerSeats, confetti, confettiColors, seatWidth, seatHeight, seatGap, designWidth, designHeight, marginX, marginY, feltGap, fit, className, }: CardTableProps): react.JSX.Element;
 
-export { BB, CardBack, type CardBackProps, type CardSize, CardTable, type CardTableProps, CommunityCards, type CommunityCardsProps, HoleCards, type HoleCardsProps, type NextSeatOptions, PlayingCard, type PlayingCardProps, CardTable as PokerTable, type CardTableProps as PokerTableProps, Pot, type PotProps, Seat, type SeatProps, cn, formatBB, getSuitSymbol, nextSeatIndex, parseCard };
+export { BB, COUNT_UP_MS, CardBack, type CardBackProps, type CardSize, CardTable, type CardTableProps, Chip, type ChipProps, type ChipSize, ChipStack, type ChipStackEntry, type ChipStackProps, CommunityCards, type CommunityCardsProps, DEAL_STAGGER_MS, DEFAULT_BET_SCALE, DEFAULT_DENOMINATIONS, DEFAULT_FELT_GAP, DEFAULT_MARGIN_X, DEFAULT_MARGIN_Y, DEFAULT_SEAT_GAP, DEFAULT_SEAT_H, DEFAULT_SEAT_W, DESIGN_H, DESIGN_W, type Denomination, type EllipseBox, FLIP_STAGGER_MS, GLOW_GAP, HoleCards, type HoleCardsProps, type Layout, type LayoutOptions, type NextSeatOptions, type ParsedCard, PlayingCard, type PlayingCardProps, type Point, CardTable as PokerTable, type CardTableProps as PokerTableProps, Pot, type PotProps, RIM_GAP, type Rgba, SEAT_SHRINK_FLOOR, SIZES, Seat, type SeatBox, type SeatLayout, type SeatProps, type Size, chipBreakdown, chipCount, chipSpotColor, chipsTotal, cn, contrastRatio, describeCard, ellipseBox, ellipsePoint, fitSeatScale, flatten, formatBB, getRankName, getSuitName, getSuitSymbol, isKnownSuit, isRedSuit, layoutSeats, minSeatSeparation, mostVisible, nextSeatIndex, parseCard, parseColor, relativeLuminance, ringPoints, seatAngle, seatPoint, seatRingRadii, tableRadii };