doubletwelve 0.1.0 → 0.3.1

package/dist/ai/candidate-generator.d.ts

@@ -0,0 +1,29 @@
+import { TrainData } from '../game/TrainData';
+import { AiAction, AiObservation, AiPlayAction, CandidateGenerator } from './types';
+/**
+ * Indices (into `obs.trains`) the player may legally build on under standard
+ * Mexican Train access: your own train, plus any train flagged public. Games
+ * with richer access rules (Warp12's Distress Beacon, locked fractures, …)
+ * supply their own {@link CandidateGenerator}.
+ */
+export declare function getAccessibleTrainIndices(obs: AiObservation): number[];
+/** Union of every played tile's key across all trains (uniqueness is global). */
+export declare function collectAllPlayedKeys(trains: readonly TrainData[]): Set<string>;
+/** Every legal placement of a hand tile onto an accessible train. */
+export declare function generatePlayActions(obs: AiObservation): AiPlayAction[];
+export interface CandidateGeneratorOptions {
+    /**
+     * Offer `draw` even when legal plays exist. Off by default (canonical "must
+     * play if you can"). Turn on for variants where drawing is always optional —
+     * combined with a high blunder rate this is what makes a beginner draw when
+     * they didn't have to.
+     */
+    allowOptionalDraw?: boolean;
+}
+/**
+ * Builds the standard candidate set: all legal plays, plus `draw` when the pile
+ * isn't empty (and either there are no plays, or optional drawing is enabled),
+ * falling back to `pass` only when nothing else is possible.
+ */
+export declare function createCandidateGenerator(options?: CandidateGeneratorOptions): CandidateGenerator<AiAction>;
+export declare const defaultCandidateGenerator: CandidateGenerator<AiAction>;

package/dist/ai/create-ai-player.d.ts

@@ -0,0 +1,14 @@
+import { AiAction, AiActionBase, AiPlayer, CreateAiPlayerOptions } from './types';
+/**
+ * Builds an offline, heuristic-driven domino player over the standard double-N
+ * model. The decision flow per turn:
+ *
+ *   observation → candidate generator → weighted heuristics → policy → action
+ *
+ * Every stage is injectable: swap the generator to change rules access, append
+ * heuristics (including ones that read custom `kind`s or `obs.meta`) to teach it
+ * variant-specific tactics, and pick/clone a {@link SkillProfile} to set strength.
+ * Pass a seeded {@link Rng} for fully reproducible games. Under the hood this is
+ * a thin adapter over the model-agnostic {@link createPolicyPlayer}.
+ */
+export declare function createAiPlayer<TAction extends AiActionBase = AiAction>(options: CreateAiPlayerOptions<TAction>): AiPlayer<TAction>;

package/dist/ai/heuristics.d.ts

@@ -0,0 +1,13 @@
+import { Heuristic } from './types';
+/** Stable ids so skill profiles and overrides can reference heuristics by name. */
+export declare const HEURISTIC_IDS: {
+    readonly preferPlay: "prefer-play";
+    readonly dumpPips: "dump-pips";
+    readonly doublesEarly: "play-doubles-early";
+    readonly ownTrain: "own-train";
+    readonly obligationRelief: "obligation-relief";
+    readonly handFlexibility: "hand-flexibility";
+    readonly defensivePublic: "defensive-public";
+};
+/** The stock, game-agnostic heuristic set. Append/replace by `id` to customize. */
+export declare const DEFAULT_HEURISTICS: Heuristic[];

package/dist/ai/index.d.ts

@@ -0,0 +1,12 @@
+export type { Rng, AiActionBase, AiPlayAction, AiDrawAction, AiPassAction, AiAction, AiObservation, EvalContext, Heuristic, SkillProfile, CandidateGenerator, AiPlayer, CreateAiPlayerOptions, } from './types';
+export { isPlayAction } from './types';
+export type { CandidateGeneratorOptions } from './candidate-generator';
+export { getAccessibleTrainIndices, collectAllPlayedKeys, generatePlayActions, createCandidateGenerator, defaultCandidateGenerator, } from './candidate-generator';
+export { HEURISTIC_IDS, DEFAULT_HEURISTICS } from './heuristics';
+export type { SkillLevel } from './skill-profiles';
+export { SKILL_PRESETS, getSkillProfile } from './skill-profiles';
+export { createAiPlayer } from './create-ai-player';
+export type { GenericHeuristic, PolicyPlayer, PolicyPlayerConfig, } from './policy';
+export { scoreWithHeuristics, argmaxIndex, softmaxIndex, chooseActionIndex, createPolicyPlayer, } from './policy';
+export type { PlayerRef, SearchModel, SearchOptions, ScoredAction, } from './search';
+export { searchActionValues } from './search';

package/dist/ai/policy.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Model-agnostic decision core shared by every game built on this library.
+ *
+ * Nothing here knows about dominoes, trains, or any specific rule set: it only
+ * knows how to turn a set of candidate actions into one chosen action, given a
+ * skill profile and a way to score actions. The domino-specific player
+ * (`createAiPlayer`) and downstream variants (e.g. Warp12) are thin adapters
+ * over {@link createPolicyPlayer}.
+ */
+/** Pseudo-random source in [0, 1). Inject a seeded one for deterministic play. */
+export type Rng = () => number;
+/**
+ * The dials that define "skill". The same engine spans beginner→advanced purely
+ * by changing which heuristics are active, their weights, and how sharply (or
+ * randomly) the policy commits to the highest-scoring action.
+ */
+export interface SkillProfile {
+    readonly id: string;
+    /** Softmax temperature over candidate scores. 0 = argmax; higher = noisier. */
+    readonly temperature: number;
+    /** Probability of ignoring the policy and picking a uniformly random action. */
+    readonly blunderRate: number;
+    /** Plies of simulation (0 = greedy). Reserved; greedy-only in this release. */
+    readonly lookaheadDepth: number;
+    readonly weights: Readonly<Record<string, number>>;
+    readonly enabled: ReadonlySet<string>;
+}
+/**
+ * A single, pure rule-of-thumb over actions of type `TAction`, given a turn
+ * context of type `TCtx`. Higher score = more attractive; return 0 when the
+ * heuristic doesn't apply so it stays weight-neutral.
+ */
+export interface GenericHeuristic<TAction, TCtx> {
+    readonly id: string;
+    score(action: TAction, ctx: TCtx): number;
+}
+/** Weighted sum of the enabled heuristics for one action. */
+export declare function scoreWithHeuristics<TAction, TCtx>(action: TAction, ctx: TCtx, byId: ReadonlyMap<string, GenericHeuristic<TAction, TCtx>>, skill: SkillProfile): number;
+/** Index of the max score, breaking ties uniformly at random. */
+export declare function argmaxIndex(scores: readonly number[], rng: Rng): number;
+/** Sample an index proportional to exp(score / temperature). */
+export declare function softmaxIndex(scores: readonly number[], temperature: number, rng: Rng): number;
+/** Temperature-controlled choice: argmax at 0, softmax sampling above it. */
+export declare function chooseActionIndex(scores: readonly number[], skill: SkillProfile, rng: Rng): number;
+export interface PolicyPlayerConfig<TObs, TAction, TCtx> {
+    skill: SkillProfile;
+    heuristics: ReadonlyArray<GenericHeuristic<TAction, TCtx>>;
+    generateCandidates: (obs: TObs) => TAction[];
+    buildContext: (obs: TObs, candidates: readonly TAction[]) => TCtx;
+    /** Returned when the generator yields no candidates at all. */
+    fallback: (obs: TObs) => TAction;
+    rng?: Rng;
+}
+export interface PolicyPlayer<TObs, TAction> {
+    decide(obs: TObs): TAction;
+}
+/**
+ * The reusable decision engine. Per turn:
+ *
+ *   observation → candidates → (blunder?) → weighted heuristics → policy → action
+ *
+ * Context is built once per decision and shared across heuristics. A single
+ * candidate short-circuits scoring; an empty set returns `fallback`.
+ */
+export declare function createPolicyPlayer<TObs, TAction, TCtx>(config: PolicyPlayerConfig<TObs, TAction, TCtx>): PolicyPlayer<TObs, TAction>;

package/dist/ai/search.d.ts

@@ -0,0 +1,43 @@
+import { Rng } from './policy';
+export type PlayerRef = number | string;
+/**
+ * The forward model the search drives. Implement these over your engine:
+ * `applyAction` is the transition function, `evaluate` is the leaf heuristic
+ * (higher = better for `perspective`), and `determinize` samples the hidden
+ * state so the search isn't allowed to peek at information a player shouldn't
+ * have. `orderActions` is an optional breadth control (good move ordering lets
+ * `maxBranch` prune to the promising moves).
+ */
+export interface SearchModel<TState, TAction> {
+    legalActions(state: TState): TAction[];
+    applyAction(state: TState, action: TAction): TState;
+    isTerminal(state: TState): boolean;
+    currentPlayer(state: TState): PlayerRef;
+    /** Position value from `perspective`'s point of view (higher is better). */
+    evaluate(state: TState, perspective: PlayerRef): number;
+    /** Sample a concrete world consistent with `perspective`'s knowledge. */
+    determinize?(state: TState, perspective: PlayerRef, rng: Rng): TState;
+    /** Reorder actions best-first; the search expands only the first `maxBranch`. */
+    orderActions?(state: TState, actions: TAction[]): TAction[];
+}
+export interface SearchOptions {
+    /** Plies to look ahead, including the root action itself (>= 1). */
+    depth: number;
+    perspective: PlayerRef;
+    rng?: Rng;
+    /** Worlds to sample for imperfect-information averaging (default 1). */
+    determinizations?: number;
+    /** Cap candidates expanded per node (default unlimited). */
+    maxBranch?: number;
+}
+export interface ScoredAction<TAction> {
+    readonly action: TAction;
+    readonly value: number;
+}
+/**
+ * Value every root action by simulating it forward. For each action we average
+ * its minimax value across `determinizations` sampled worlds. Returns one entry
+ * per (ordered, breadth-capped) root action; the caller turns these values into
+ * a choice (e.g. skill-scaled softmax via {@link chooseActionIndex}).
+ */
+export declare function searchActionValues<TState, TAction>(rootState: TState, model: SearchModel<TState, TAction>, options: SearchOptions): ScoredAction<TAction>[];

package/dist/ai/skill-profiles.d.ts

@@ -0,0 +1,16 @@
+import { SkillProfile } from './types';
+/**
+ * Stock skill tiers. Each is just a configuration of the same engine:
+ *
+ * - **beginner** — only cares about playing and lightly about dumping pips, with
+ *   high temperature and a real blunder rate: erratic, often suboptimal plays.
+ * - **intermediate** — adds doubles-early and own-train sense, low noise.
+ * - **advanced** — full heuristic suite (obligations, flexibility, defense),
+ *   near-deterministic, no blunders.
+ *
+ * Clone and tweak (`{ ...SKILL_PRESETS.advanced, temperature: 0.3 }`) for any
+ * point on the spectrum.
+ */
+export declare const SKILL_PRESETS: Record<'beginner' | 'intermediate' | 'advanced', SkillProfile>;
+export type SkillLevel = keyof typeof SKILL_PRESETS;
+export declare function getSkillProfile(level: SkillLevel): SkillProfile;

package/dist/ai/test-fixtures.d.ts

@@ -0,0 +1,9 @@
+import { DominoValue } from '../game/DominoValue';
+import { TrainData } from '../game/TrainData';
+import { RulesConfig } from '../rules/rulesConfig';
+import { AiObservation } from './types';
+/** Deterministic mulberry32 RNG for reproducible AI tests. */
+export declare function mulberry32(seed: number): () => number;
+export declare const DEFAULT_TEST_RULES: RulesConfig;
+export declare function train(playerId: number, dominoes: DominoValue[], isPublic?: boolean): TrainData;
+export declare function makeObs(overrides?: Partial<AiObservation>): AiObservation;

package/dist/ai/types.d.ts

@@ -0,0 +1,84 @@
+import { DominoValue } from '../game/DominoValue';
+import { TrainData } from '../game/TrainData';
+import { RulesConfig } from '../rules/rulesConfig';
+import { Move } from '../rules/placement';
+import { GenericHeuristic, Rng, SkillProfile } from './policy';
+export type { Rng, SkillProfile } from './policy';
+/**
+ * Base shape every action shares. Games extend the action space by declaring
+ * their own `kind` literals (e.g. Warp12's `'deploy-beacon'`) and unioning them
+ * with {@link AiAction}; the scoring pipeline treats unknown kinds opaquely.
+ */
+export interface AiActionBase {
+    readonly kind: string;
+}
+/** Attach `tile` at `move.end` of the train at `trainIndex` in the observation. */
+export interface AiPlayAction extends AiActionBase {
+    readonly kind: 'play';
+    readonly trainIndex: number;
+    readonly move: Move;
+}
+export interface AiDrawAction extends AiActionBase {
+    readonly kind: 'draw';
+}
+export interface AiPassAction extends AiActionBase {
+    readonly kind: 'pass';
+}
+/** The base action space shared by all double-N variants. */
+export type AiAction = AiPlayAction | AiDrawAction | AiPassAction;
+/** Narrows any action to a play action (kind discriminant on the base is widened). */
+export declare function isPlayAction(action: AiActionBase): action is AiPlayAction;
+/**
+ * Everything the bot is allowed to see this turn. Game-specific extras (beacon
+ * flags, fracture state, scores, turn order…) ride along in {@link meta} so
+ * custom heuristics can read them without changing this interface.
+ */
+export interface AiObservation {
+    readonly selfPlayerId: number;
+    readonly hand: readonly DominoValue[];
+    readonly rules: RulesConfig;
+    readonly trains: readonly TrainData[];
+    readonly engineValue: number;
+    /** Tiles left to draw; omit for "unlimited/unknown". 0 forbids drawing. */
+    readonly drawPileSize?: number;
+    /**
+     * Set by the host once this player has already taken their single draw this
+     * turn. Standard Mexican Train allows exactly one draw when you can't play;
+     * if the drawn tile still can't be played you must pass (which marks your
+     * train public). When true the generator stops offering `draw`, so the bot
+     * falls through to `pass` instead of draining the pile.
+     */
+    readonly turnDrawUsed?: boolean;
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/** Shared, pre-computed turn data handed to every heuristic (built once per decision). */
+export interface EvalContext {
+    readonly obs: AiObservation;
+    /** Canonical keys of every tile already on the table (global uniqueness). */
+    readonly playedKeys: ReadonlySet<string>;
+    readonly candidates: readonly AiActionBase[];
+    readonly playCandidates: readonly AiPlayAction[];
+    /** Tiles neither played nor in hand — the basis for tile-counting heuristics. */
+    readonly unseen: readonly DominoValue[];
+    readonly rng: Rng;
+}
+/**
+ * A single, pure rule-of-thumb over the domino action space. Higher score =
+ * more attractive; return 0 when it doesn't apply so it stays weight-neutral.
+ * This is the domino specialization of the generic {@link GenericHeuristic}.
+ */
+export type Heuristic = GenericHeuristic<AiActionBase, EvalContext>;
+/** Produces the legal/considered actions for a turn. Override to change rules access. */
+export type CandidateGenerator<TAction extends AiActionBase = AiAction> = (obs: AiObservation) => TAction[];
+export interface AiPlayer<TAction extends AiActionBase = AiAction> {
+    decide(obs: AiObservation): TAction;
+}
+export interface CreateAiPlayerOptions<TAction extends AiActionBase = AiAction> {
+    skill: SkillProfile;
+    /** Defaults to {@link DEFAULT_HEURISTICS}. Append your own to extend behavior. */
+    heuristics?: Heuristic[];
+    /** Defaults to {@link defaultCandidateGenerator}. */
+    generateCandidates?: CandidateGenerator<TAction>;
+    /** Defaults to `Math.random`. Inject a seeded RNG for reproducible games/tests. */
+    rng?: Rng;
+}

package/dist/app/DefaultPip.d.ts

@@ -0,0 +1,9 @@
+import { FC } from 'react';
+import { PipRenderContext, DominoTheme } from './dominoTheme';
+export interface DefaultPipProps {
+    ctx: PipRenderContext;
+    theme?: DominoTheme;
+}
+/** Stock domino pip — solid or hollow circle using the resolved pip color. */
+export declare const DefaultPip: FC<DefaultPipProps>;
+export default DefaultPip;

package/dist/app/DominoHub.d.ts

@@ -13,5 +13,13 @@ interface DominoHubProps {
     tableHeight: number;
     pipColors?: PipColorMap;
 }
+/**
+ * Distance from the hub center at which a train should start so its first tile
+ * clears its neighbours. Trains fan out 360/slots° apart, so the neighbour gap
+ * at distance d is ~2πd/slots; it must exceed a tile's footprint. Offset trains
+ * zigzag wider (a perpendicular half-tile seed) and need a bigger ring; linear
+ * trains are skinny and stay near the hub. Never smaller than `radius + 20`.
+ */
+export declare function hubTrainStartDistance(slots: number, radius: number, dominoWidth: number, layoutStyle: 'offset' | 'linear'): number;
 export declare const DominoHub: FC<DominoHubProps>;
 export default DominoHub;

package/dist/app/DominoThemeContext.d.ts

@@ -0,0 +1,8 @@
+import { FC, ReactNode } from 'react';
+import { DominoTheme } from './dominoTheme';
+export interface DominoThemeProviderProps {
+    theme?: DominoTheme;
+    children: ReactNode;
+}
+export declare const DominoThemeProvider: FC<DominoThemeProviderProps>;
+export declare function useDominoTheme(override?: DominoTheme): DominoTheme;

package/dist/app/DoubleTwelve.d.ts

@@ -1,4 +1,5 @@
 import { FC } from 'react';
+import { DominoTheme } from './dominoTheme';
 import { PipColorMap } from './pipColors';
 export interface DoubleTwelveProps {
     /** Pip count on the top half (0–12). Defaults to 0 (blank). */
@@ -14,6 +15,8 @@ export interface DoubleTwelveProps {
     pipColors?: PipColorMap;
     borderColor?: string;
     rotation?: number;
+    /** Presentation overrides — also available via DominoThemeProvider. */
+    theme?: DominoTheme;
 }
 export declare const DoubleTwelve: FC<DoubleTwelveProps>;
 export default DoubleTwelve;

package/dist/app/Pip.d.ts

@@ -1,13 +1,6 @@
 import { FC } from 'react';
-import { PipGridSize } from './pipGrid';
-export interface PipProps {
-    row: number;
-    col: number;
-    gridSize: PipGridSize;
-    color: string;
-    hollow?: boolean;
-    top?: string;
-    left?: string;
-}
-export declare const Pip: FC<PipProps>;
+import { PipRenderContext } from './dominoTheme';
+export type PipProps = PipRenderContext;
+/** @deprecated Prefer theme.renderPip or DefaultPip via DominoTheme. */
+export declare const Pip: FC<PipRenderContext>;
 export default Pip;

package/dist/app/Viewport.d.ts

@@ -0,0 +1,27 @@
+import { FC, ReactNode } from 'react';
+export interface ViewportProps {
+    /** Visible viewport size in pixels. */
+    width: number;
+    height: number;
+    /** Content (world) size, used by the fit/reset control. */
+    contentWidth: number;
+    contentHeight: number;
+    children: ReactNode;
+    minScale?: number;
+    maxScale?: number;
+    /** Multiplier applied per wheel notch / zoom-button press. */
+    zoomStep?: number;
+    padding?: number;
+    background?: string;
+    /** Show the built-in zoom/reset control overlay. Default true. */
+    showControls?: boolean;
+    testId?: string;
+}
+/**
+ * A pan/zoom canvas for content larger than the screen. Drag to slide, wheel or
+ * the on-screen buttons to zoom (zoom centers on the cursor for the wheel).
+ * Clicks pass through to children unless the pointer actually dragged, so
+ * interactive content (e.g. click-to-bend tiles) keeps working.
+ */
+export declare const Viewport: FC<ViewportProps>;
+export default Viewport;

package/dist/app/dominoTheme.d.ts

@@ -0,0 +1,39 @@
+import { CSSProperties, ReactNode } from 'react';
+import { PipGridSize } from './pipGrid';
+export interface PipRenderContext {
+    value: number;
+    row: number;
+    col: number;
+    gridSize: PipGridSize;
+    color: string;
+    hollow?: boolean;
+    top?: string;
+    left?: string;
+    positionStyle: CSSProperties;
+}
+export interface TileRenderContext {
+    value1: number;
+    value2: number;
+    width: number;
+    height: number;
+    backgroundColor: string;
+    borderColor: string;
+    rotation: number;
+}
+/** Optional presentation hooks for domino tiles and pips. */
+export interface DominoTheme {
+    /** Root class on each tile — use for app-specific CSS modules. */
+    tileClassName?: string;
+    /** Extra data attributes for CSS selectors, e.g. holographic toggles. */
+    tileDataAttributes?: Record<string, string | boolean | number | undefined>;
+    tileStyle?: (ctx: TileRenderContext) => CSSProperties;
+    halfDividerStyle?: (ctx: TileRenderContext) => CSSProperties;
+    /** Merged onto each pip after layout positioning. */
+    pipStyle?: (ctx: PipRenderContext) => CSSProperties;
+    /** Replace the default pip element entirely. */
+    renderPip?: (ctx: PipRenderContext) => ReactNode;
+}
+export declare const DEFAULT_DOMINO_THEME: DominoTheme;
+export declare function mergeDominoTheme(base: DominoTheme, patch?: DominoTheme): DominoTheme;
+/** Convert theme tileDataAttributes to React data-* props. */
+export declare function themeDataAttributes(attrs?: DominoTheme['tileDataAttributes']): Record<string, string>;

package/dist/app/trainBends.d.ts

@@ -0,0 +1,77 @@
+import { TrainBend, TrainBranch } from '../game/TrainData';
+import { TrainLayoutEntry, TrainLayoutStyle } from './trainLayout';
+export type TurnSide = 'left' | 'right';
+/** Default pivot magnitude. The interactive UI only produces square corners. */
+export declare const TURN_DEGREES = 90;
+/**
+ * Signed turn (degrees) for a side. Headings use the screen convention
+ * (0° = +x, +90° = +y / downward), so a `+90` turn rotates +x toward +y, which
+ * reads as a clockwise/"right" turn on screen.
+ */
+export declare function sideToTurn(side: TurnSide, degrees?: number): number;
+export declare function oppositeSide(side: TurnSide): TurnSide;
+/**
+ * Default turn side in offset mode: fold toward the empty side — the one
+ * opposite the lane the zigzag biases into (`outwardSign`). A `+90` turn heads
+ * toward the heading's `+perp`; outwardSign is measured on that same perp axis,
+ * so the empty side is `-outwardSign`, i.e. side = outwardSign >= 0 ? 'left' : 'right'.
+ */
+export declare function offsetDefaultSide(angle: number, outwardSign?: number): TurnSide;
+export interface TableBounds {
+    width: number;
+    height: number;
+}
+/**
+ * Default turn side in linear mode: fold toward whichever perpendicular side has
+ * more open table from the bend point. Distance is measured from `point` along
+ * each perpendicular until it exits the table rectangle; the roomier side wins.
+ * Ties (e.g. dead-center) fall back to 'right'.
+ */
+export declare function linearDefaultSide(point: {
+    x: number;
+    y: number;
+}, angle: number, bounds: TableBounds): TurnSide;
+export interface BuildTrainTilesInput {
+    startX: number;
+    startY: number;
+    angle: number;
+    layoutStyle: TrainLayoutStyle;
+}
+/** Flattens a branch (with feet and bends) to its world-space tiles. */
+export declare function buildBranchTiles(branch: TrainBranch, input: BuildTrainTilesInput): TrainLayoutEntry[];
+/** Replaces (or removes) the bend at `index`, returning a new bends array. */
+export declare function withBendAt(bends: readonly TrainBend[] | undefined, index: number, turn: number | null): TrainBend[];
+export interface ResolveBendResult {
+    /** The legal turn to apply, or null when no side is collision-free. */
+    turn: number | null;
+    /** Why null: 'blocked' = both sides collide; never set on success. */
+    reason?: 'blocked';
+}
+export interface ResolveBendInput {
+    branch: TrainBranch;
+    index: number;
+    build: BuildTrainTilesInput;
+    /** Tiles belonging to every OTHER path; a bend may not intersect these. */
+    obstacles: readonly TrainLayoutEntry[];
+    /** Preferred side to try first (from the mode's heuristic). */
+    preferredSide: TurnSide;
+    /** Turn magnitude in degrees (default 90). */
+    degrees?: number;
+}
+/**
+ * Picks a collision-free turn for a new bend at `index`. Tries the preferred
+ * side first, then the opposite; a candidate is rejected if the resulting path
+ * crosses itself or any obstacle path. Returns `{ turn: null, reason: 'blocked' }`
+ * when neither side is legal, so the caller can refuse the bend.
+ */
+export declare function resolveBend({ branch, index, build, obstacles, preferredSide, degrees, }: ResolveBendInput): ResolveBendResult;
+/**
+ * Cycles a tile's bend on repeated clicks: none → preferred legal side →
+ * opposite legal side → none. Skips sides that collide. Returns the next bends
+ * array, or the unchanged input when no legal bend exists.
+ */
+export declare function cycleBendAt(branch: TrainBranch, index: number, build: BuildTrainTilesInput, obstacles: readonly TrainLayoutEntry[], preferredSide: TurnSide, degrees?: number): {
+    bends: TrainBend[];
+    changed: boolean;
+    blocked: boolean;
+};

package/dist/app/trainLayout.d.ts

@@ -1,5 +1,5 @@
 import { DominoValue } from '../game/DominoValue';
-import { TrainBranch } from '../game/TrainData';
+import { TrainBend, TrainBranch } from '../game/TrainData';
 export declare const DOMINO_WIDTH = 60;
 export declare const DOMINO_HEIGHT = 120;
 /**
@@ -45,6 +45,12 @@ export interface ComputeTrainLayoutInput {
      * toes sit at equal, close distances on either side.
      */
     hubIndex?: number;
+    /**
+     * Pivots that fold this run's path into Ls, Us, or snakes. When present, the
+     * run is split into straight sub-runs at each bend index and chained corner to
+     * corner. Hub-centering is skipped (corners relax centering by design).
+     */
+    bends?: readonly TrainBend[];
 }
 export declare function halfExtentAlongTrain(isDouble: boolean, dominoWidth?: number, dominoHeight?: number): number;
 export declare function stepAlongTrain(fromIsDouble: boolean, toIsDouble: boolean, dominoWidth?: number, dominoHeight?: number): number;
@@ -56,10 +62,31 @@ export declare function trainPerpendicular(angle: number): {
     perpX: number;
     perpY: number;
 };
-export declare function orientDominoValues(dominoes: DominoValue[], layoutStyle: TrainLayoutStyle): DominoValue[];
+/**
+ * Orients a value chain for rendering so each tile's connecting value (`value1`,
+ * the near end) faces the previous tile. A tile is flipped only when it is
+ * stored reversed (its `value2`, not `value1`, is the one that matches the
+ * previous tile's open end). A correctly-stored chain is left untouched, and
+ * doubles are never flipped. This is identical for linear and offset layouts —
+ * the connection rule doesn't depend on spacing.
+ */
+export declare function orientDominoValues(dominoes: DominoValue[]): DominoValue[];
 export declare function outwardPerpSign(angle: number): number;
 export declare function nextPerpOffset(current: number, outwardSign: number): number;
-export declare function computeTrainLayout({ startX, startY, angle, dominoes, layoutStyle, dominoWidth, dominoHeight, leadGap, outwardSign: outwardSignInput, hubIndex, }: ComputeTrainLayoutInput): TrainLayoutEntry[];
+/**
+ * Normalizes a run's bends: integer indices strictly inside the run, one per
+ * index (last wins), sorted. Index 0 is dropped — a run can't bend before its
+ * first tile. Returns the cleaned, sorted list.
+ */
+export declare function normalizeBends(bends: readonly TrainBend[] | undefined, tileCount: number): TrainBend[];
+/**
+ * Local heading (degrees) of the tile at `index` in a (possibly bent) run: the
+ * base `angle` plus every bend turn at or before that index. With no bends this
+ * is just `angle`. Used to anchor chicken-foot toes off a double's *actual*
+ * heading when the double sits in a turned section of the path.
+ */
+export declare function headingAtIndex(angle: number, bends: readonly TrainBend[] | undefined, index: number, tileCount?: number): number;
+export declare function computeTrainLayout({ startX, startY, angle, dominoes, layoutStyle, dominoWidth, dominoHeight, leadGap, outwardSign: outwardSignInput, hubIndex, bends, }: ComputeTrainLayoutInput): TrainLayoutEntry[];
 /** The four world-space corners of a tile (its rotated rectangle). */
 export declare function tileCorners(entry: TrainLayoutEntry, dominoWidth?: number, dominoHeight?: number): Array<{
     x: number;
@@ -72,6 +99,18 @@ export declare function tileCorners(entry: TrainLayoutEntry, dominoWidth?: numbe
  * double — pass cleanly while real collisions are caught.
  */
 export declare function tilesOverlap(a: TrainLayoutEntry, b: TrainLayoutEntry, epsilon?: number, dominoWidth?: number, dominoHeight?: number): boolean;
+/**
+ * True when any tile of `layout` overlaps any tile in `obstacles` — i.e. this
+ * path would physically intersect another path. Used to forbid a bend that
+ * would cross another train.
+ */
+export declare function layoutsCollide(layout: readonly TrainLayoutEntry[], obstacles: readonly TrainLayoutEntry[], epsilon?: number, dominoWidth?: number, dominoHeight?: number): boolean;
+/**
+ * True when a path crosses itself — any two of its own tiles overlap. Adjacent
+ * tiles that merely touch are fine (tilesOverlap ignores contact), so this only
+ * fires when a fold (e.g. a too-tight U-turn) makes the path collide with itself.
+ */
+export declare function layoutSelfIntersects(layout: readonly TrainLayoutEntry[], epsilon?: number, dominoWidth?: number, dominoHeight?: number): boolean;
 /**
  * A single straight run of dominoes within a chicken-foot tree: the main line
  * or one toe. `depth` is 0 for the main line, 1 for its toes, and so on.

package/dist/app/viewportMath.d.ts

@@ -0,0 +1,28 @@
+/** Pan/zoom transform: content is scaled by `scale` then translated by (x, y). */
+export interface ViewportTransform {
+    scale: number;
+    x: number;
+    y: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export declare function clampScale(scale: number, min: number, max: number): number;
+/**
+ * Zooms by `factor` about a fixed screen `pivot` so the content point under the
+ * pivot stays put. Scale is clamped to [min, max]; the translation is adjusted
+ * by the *effective* factor after clamping so panning can't drift at the limits.
+ */
+export declare function zoomAt(view: ViewportTransform, factor: number, pivot: Point, min: number, max: number): ViewportTransform;
+/**
+ * Centers `content` within `viewport` at the largest scale that fits inside the
+ * given padding (clamped to [min, max]). Use this for a "fit / reset" control.
+ */
+export declare function fitToBounds(content: Size, viewport: Size, padding: number, min: number, max: number): ViewportTransform;
+/** Converts a screen point inside the viewport to content coordinates. */
+export declare function screenToContent(view: ViewportTransform, screen: Point): Point;

package/dist/game/TrainData.d.ts

@@ -1,4 +1,22 @@
 import { DominoValue } from './DominoValue';
+/**
+ * A pivot in a run's path. At `index` (a tile position within `dominoes`) the run
+ * stops going straight and turns by `turn` degrees, so a player can fold a train
+ * into Ls, Us, and meandering snakes to avoid other trains. Bends are layout
+ * hints only — they never change which tiles connect (the value chain is
+ * untouched), so like-values keep touching across every corner.
+ *
+ * `turn` is signed degrees relative to the current heading, in the same
+ * convention as a branch's `angle` (0° = +x, 90° = +y / downward on screen).
+ * The interactive default is ±90°; the sign is chosen by a heuristic when the
+ * player first bends, then persisted here so the path is stable across renders.
+ */
+export interface TrainBend {
+    /** Index in `dominoes` of the first tile that continues in the new heading. */
+    index: number;
+    /** Signed turn in degrees applied to the heading at this point. */
+    turn: number;
+}
 /**
  * A run of dominoes that can sprout chicken-foot side toes at its doubles.
  *
@@ -15,6 +33,11 @@ export interface TrainBranch {
      * entries: index 0 → -45°, index 1 → +45°).
      */
     feet?: Record<number, TrainBranch[]>;
+    /**
+     * Optional pivots that fold this run's path. Order-independent (the engine
+     * sorts by index); at most one bend per index. Absent/empty = a straight run.
+     */
+    bends?: TrainBend[];
 }
 export interface TrainData extends TrainBranch {
     playerId: number;