@dreamboard-games/sdk 0.2.0

package/dist/hex-board-view-D_07hO6O.d.ts

@@ -0,0 +1,933 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { BoardId, HexTileState, HexEdgeState, EdgeTypeId, PlayerId, HexVertexState, VertexTypeId, SpaceTypeId, SquareCellState, SquareEdgeState, SquareVertexState, SquarePieceState, HexBoardState, SquareBoardState } from './ui/types/player-state.js';
+
+/**
+ * Token contract for `@dreamboard-games/sdk/ui`.
+ *
+ * The {@link Theme} object is the only thing components consume for
+ * visual styling. Every preset (tabletop, arcade, studio) is just a
+ * different fully-resolved {@link Theme}; every author override is a
+ * deep partial of it. Components never inline hex codes, font stacks,
+ * or shadow strings — they read from `useTheme()` (or, when written in
+ * Tailwind, from CSS variables that the {@link ThemeProvider} writes
+ * onto its wrapper element).
+ *
+ * Architectural rules:
+ *
+ * 1. **Foundation → Semantic → Component.** Foundation palette ramps
+ *    (`color.neutral`, `color.brand`, …) are never read directly by
+ *    components. Components read `semantic.*` (e.g. `surface.card`,
+ *    `intent.primary`) which the preset maps from foundation tokens.
+ * 2. **No optional deep keys.** Presets must supply every leaf so
+ *    components don't need fallbacks. Author-supplied overrides are
+ *    `DeepPartial<Theme>` and merged before the provider mounts.
+ * 3. **Scalar leaves only.** Every leaf is a string (CSS-ready) so the
+ *    serializer can emit a CSS variable for it without per-token
+ *    formatting logic.
+ */
+/** Identity-only metadata. */
+interface ThemeMeta {
+    /** Stable id used by `data-dreamboard-theme` and CSS-var scoping. */
+    readonly id: string;
+    /** Human-readable name for dev tools. */
+    readonly name: string;
+    /**
+     * Render mode hint for components that need to choose between light
+     * and dark sub-tokens. Presets pick one; authors don't toggle this.
+     */
+    readonly mode: "light" | "dark";
+}
+/** Foundation color ramp. Six stops keeps presets compact. */
+interface ColorRamp {
+    readonly 50: string;
+    readonly 100: string;
+    readonly 200: string;
+    readonly 400: string;
+    readonly 600: string;
+    readonly 800: string;
+    readonly 950: string;
+}
+/**
+ * Per-player color tokens. The {@link Theme.player} array is indexed by
+ * 0-based seat slot (`player[0]` = first seat). Each entry carries a
+ * `solid` brand color, a `soft` tint usable as a background, and `on`
+ * — the recommended foreground when text sits on `solid`.
+ */
+interface PlayerColor {
+    readonly solid: string;
+    readonly soft: string;
+    readonly on: string;
+}
+/**
+ * Foundation palette. Components never read this directly; presets map
+ * these into {@link SemanticTokens}. Exposed so authors who write a
+ * full theme can compose without inventing their own palette type.
+ */
+interface FoundationColor {
+    readonly neutral: ColorRamp;
+    readonly brand: ColorRamp;
+    readonly accent: ColorRamp;
+    readonly success: ColorRamp;
+    readonly warning: ColorRamp;
+    readonly danger: ColorRamp;
+    readonly info: ColorRamp;
+}
+/**
+ * Semantic colors consumed by every component. These are the *only*
+ * color tokens components should reference. Names describe role
+ * ("the surface a player card sits on"), not appearance ("light grey").
+ */
+interface SemanticColor {
+    readonly surface: {
+        /** Outermost shell background. */
+        readonly app: string;
+        /** Board canvas background (behind tiles). */
+        readonly board: string;
+        /** HUD chrome panels (top bar, action bar, side rails). */
+        readonly hud: string;
+        /** Standalone cards (player cards, action cards, hand cards). */
+        readonly card: string;
+        /** Modal/sheet body. */
+        readonly sheet: string;
+        /** Scrim behind a blocker overlay. */
+        readonly overlay: string;
+        /** Subtle inset (resource pills, count badges, …). */
+        readonly inset: string;
+    };
+    readonly text: {
+        /** Default body and headline text on light surfaces. */
+        readonly primary: string;
+        /** De-emphasised metadata, hint copy, captions. */
+        readonly muted: string;
+        /** Text used on `intent.primary` solid backgrounds. */
+        readonly onIntent: string;
+        /** Brand-tinted text for emphasis (links, key numbers). */
+        readonly accent: string;
+        /** Disabled text (button labels in disabled state). */
+        readonly disabled: string;
+    };
+    readonly border: {
+        /** Hairline divider between sibling rows. */
+        readonly subtle: string;
+        /** Standard card / panel border. */
+        readonly default: string;
+        /** Outlined emphasis (hovered tiles, selected card). */
+        readonly strong: string;
+        /** Focus ring (keyboard nav). */
+        readonly focus: string;
+    };
+    /**
+     * Intent colours map to action emphasis. Components pick a slot
+     * (`primary` for "do the main thing now", `danger` for destructive
+     * confirms, etc.) and read both the surface and on-color from it.
+     */
+    readonly intent: {
+        readonly primary: IntentColor;
+        readonly secondary: IntentColor;
+        readonly success: IntentColor;
+        readonly danger: IntentColor;
+        readonly warning: IntentColor;
+        readonly info: IntentColor;
+    };
+}
+/** A semantic intent (button background + matching foreground + soft tint). */
+interface IntentColor {
+    /** Solid fill (button bg, badge bg). */
+    readonly solid: string;
+    /** Recommended text/icon color sitting on `solid`. */
+    readonly on: string;
+    /** Subtle tint (e.g. badge bg with `text` for foreground). */
+    readonly soft: string;
+    /** Suitable foreground when sitting on `soft`. */
+    readonly onSoft: string;
+    /** Border tint matched to this intent (e.g. focus ring on intent). */
+    readonly border: string;
+}
+/** Border-radius ramp. */
+interface Radius {
+    readonly none: string;
+    readonly sm: string;
+    readonly md: string;
+    readonly lg: string;
+    /** HUD chrome (top bar pieces, action-bar bar). */
+    readonly hud: string;
+    /** Fully-round badges/pills. */
+    readonly pill: string;
+}
+/** Spacing ramp (rem-based by default). */
+interface Space {
+    readonly 0: string;
+    readonly 0.5: string;
+    readonly 1: string;
+    readonly 1.5: string;
+    readonly 2: string;
+    readonly 3: string;
+    readonly 4: string;
+    readonly 6: string;
+    readonly 8: string;
+    readonly 12: string;
+}
+/** Typography tokens. */
+interface Typography {
+    readonly fontFamily: {
+        /** Hero text — phase name, scoreboard headline, winner banner. */
+        readonly display: string;
+        /** Default UI body text. */
+        readonly body: string;
+        /** Numeric runs (scores, counters, tabular data). Tabular figures preferred. */
+        readonly tabular: string;
+        /** Source/code/raw-id rendering. */
+        readonly mono: string;
+    };
+    readonly fontSize: {
+        readonly xs: string;
+        readonly sm: string;
+        readonly md: string;
+        readonly lg: string;
+        readonly xl: string;
+        readonly "2xl": string;
+        readonly "3xl": string;
+    };
+    readonly fontWeight: {
+        readonly regular: string;
+        readonly medium: string;
+        readonly bold: string;
+    };
+    readonly lineHeight: {
+        readonly tight: string;
+        readonly normal: string;
+        readonly relaxed: string;
+    };
+    readonly letterSpacing: {
+        readonly tight: string;
+        readonly normal: string;
+        readonly wide: string;
+        /** All-caps labels ("YOUR TURN"). */
+        readonly caps: string;
+    };
+}
+/** Drop-shadow elevation ramp. */
+interface Elevation {
+    /** Resting state (cards, panels). */
+    readonly rest: string;
+    /** Hover-lift (interactive cards). */
+    readonly hover: string;
+    /** Selected / dragged element. */
+    readonly lifted: string;
+    /** Modal / overlay stack. */
+    readonly overlay: string;
+    /** Inner shadow (board canvas inset, resource pill well). */
+    readonly inset: string;
+}
+/**
+ * Motion tokens. Components import durations and easings from here so a
+ * single `prefers-reduced-motion` switch zeroes everything out at the
+ * provider, not per-component.
+ */
+interface Motion {
+    readonly duration: {
+        /** Hover, focus, micro-press (~80ms). */
+        readonly fast: string;
+        /** Default — most state changes (~160ms). */
+        readonly normal: string;
+        /** Layout shifts, drawer open/close (~280ms). */
+        readonly slow: string;
+        /**
+         * Looping ambient pulses — active-player breath, dice glow.
+         * Components should respect `motion.reducedMotion` before kicking
+         * off looping animations.
+         */
+        readonly ambient: string;
+    };
+    readonly easing: {
+        /** Default for entering / settling. */
+        readonly out: string;
+        /** Default for exiting. */
+        readonly in: string;
+        /** Symmetric. */
+        readonly inOut: string;
+        /** Springy — selected card lift, active-player wobble. */
+        readonly spring: string;
+    };
+    /**
+     * `"true"` when the active client requests reduced motion. Components
+     * should branch on this rather than forcing animations off via CSS,
+     * because some animations (e.g. dice roll, shuffle) are critical for
+     * conveying state and need a static fallback.
+     */
+    readonly reducedMotion: "true" | "false";
+}
+/**
+ * Component-level token slots derived from semantic + foundation tokens.
+ * Kept intentionally tiny — a slot is added here only when a component
+ * needs to deviate from the semantic mapping in a way that authors
+ * should be able to customise without re-skinning the whole intent
+ * scale.
+ */
+interface ComponentTokens {
+    readonly board: {
+        /** Outer ring around the board canvas. */
+        readonly frameBorder: string;
+        /** Inner board surface tint (overlays the canvas tile renderer). */
+        readonly frameBackground: string;
+        /** Highlight ring drawn on hovered interactive targets. */
+        readonly hoverRing: string;
+        /** Idle hint colour for eligible-but-unhovered targets. */
+        readonly eligibleHint: string;
+    };
+    readonly card: {
+        /** Border drawn around face-up cards. */
+        readonly border: string;
+        /** Border drawn around face-down cards. */
+        readonly backBorder: string;
+        /** Card-back fill colour. */
+        readonly backBackground: string;
+        /** Selected outline. */
+        readonly selectedRing: string;
+    };
+    readonly playerCard: {
+        /** Background of the active-player card. */
+        readonly activeBackground: string;
+        /** Border of the active-player card. */
+        readonly activeBorder: string;
+        /** Glow colour radiated by the active-player card. */
+        readonly activeGlow: string;
+        /** Background of the "you" badge. */
+        readonly youBadgeBackground: string;
+        /** Foreground of the "you" badge. */
+        readonly youBadgeForeground: string;
+    };
+    readonly toast: {
+        readonly successBackground: string;
+        readonly errorBackground: string;
+        readonly infoBackground: string;
+        readonly foreground: string;
+    };
+}
+/**
+ * The complete theme contract. Every leaf is a CSS-ready string so the
+ * provider can emit a CSS variable for each path without per-leaf
+ * formatting. {@link DeepPartial} is exported for author overrides.
+ */
+interface Theme {
+    readonly meta: ThemeMeta;
+    readonly color: FoundationColor;
+    readonly semantic: SemanticColor;
+    readonly radius: Radius;
+    readonly space: Space;
+    readonly typography: Typography;
+    readonly elevation: Elevation;
+    readonly motion: Motion;
+    readonly player: readonly [
+        PlayerColor,
+        PlayerColor,
+        PlayerColor,
+        PlayerColor,
+        PlayerColor,
+        PlayerColor
+    ];
+    readonly component: ComponentTokens;
+}
+/**
+ * Recursive partial for theme overrides. Authors pass this to
+ * `<ThemeProvider override={...}/>` (or to a preset's `extend`
+ * helper) to tweak individual tokens without re-declaring the whole
+ * tree.
+ */
+type ThemeOverride = DeepPartial<Theme>;
+type DeepPartial<T> = T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends object ? {
+    readonly [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Deep merge for {@link Theme} overrides. Arrays (notably
+ * {@link Theme.player}) are *replaced* rather than merged so callers
+ * can't accidentally end up with mixed-preset palettes.
+ */
+declare function mergeTheme(base: Theme, override?: ThemeOverride): Theme;
+
+type RuntimeFields = Record<string, unknown>;
+interface GeneratedTiledEdgeStateLike<SpaceIdValue extends string = string, EdgeIdValue extends string = string, Fields = RuntimeFields> {
+    id: EdgeIdValue;
+    spaceIds: readonly SpaceIdValue[];
+    typeId?: EdgeTypeId | null;
+    label?: string | null;
+    ownerId?: PlayerId | null;
+    fields?: Fields;
+}
+interface GeneratedTiledVertexStateLike<SpaceIdValue extends string = string, VertexIdValue extends string = string, Fields = RuntimeFields> {
+    id: VertexIdValue;
+    spaceIds: readonly SpaceIdValue[];
+    typeId?: VertexTypeId | null;
+    label?: string | null;
+    ownerId?: PlayerId | null;
+    fields?: Fields;
+}
+interface GeneratedHexSpaceStateLike<SpaceIdValue extends string = string, Fields = RuntimeFields> {
+    id: SpaceIdValue;
+    q: number;
+    r: number;
+    typeId?: SpaceTypeId | null;
+    label?: string | null;
+    ownerId?: PlayerId | null;
+    fields?: Fields;
+}
+interface GeneratedSquareSpaceStateLike<SpaceIdValue extends string = string, Fields = RuntimeFields> {
+    id: SpaceIdValue;
+    row: number;
+    col: number;
+    typeId?: SpaceTypeId | null;
+    label?: string | null;
+    ownerId?: PlayerId | null;
+    fields?: Fields;
+}
+interface GeneratedHexBoardInput<BoardIdValue extends string = BoardId, SpaceIdValue extends string = string, EdgeIdValue extends string = string, VertexIdValue extends string = string, SpaceFields = RuntimeFields, EdgeFields = RuntimeFields, VertexFields = RuntimeFields> {
+    id: BoardIdValue;
+    layout?: "hex";
+    orientation?: "pointy-top" | "flat-top";
+    spaces: Readonly<Record<SpaceIdValue, GeneratedHexSpaceStateLike<SpaceIdValue, SpaceFields>>>;
+    edges: ReadonlyArray<HexEdgeState<BoardIdValue, SpaceIdValue, EdgeIdValue, EdgeFields> | GeneratedTiledEdgeStateLike<SpaceIdValue, EdgeIdValue, EdgeFields>>;
+    vertices: ReadonlyArray<HexVertexState<BoardIdValue, SpaceIdValue, VertexIdValue, VertexFields> | GeneratedTiledVertexStateLike<SpaceIdValue, VertexIdValue, VertexFields>>;
+}
+interface AuthoredHexBoardInput<BoardIdValue extends string = BoardId, SpaceIdValue extends string = string, EdgeIdValue extends string = string, VertexIdValue extends string = string, SpaceFields = RuntimeFields, EdgeFields = RuntimeFields, VertexFields = RuntimeFields, SpaceView = unknown> {
+    id: BoardIdValue;
+    layout?: "hex";
+    orientation?: "pointy-top" | "flat-top";
+    tiles: ReadonlyArray<HexTileState<BoardIdValue, SpaceIdValue, SpaceFields, SpaceView>>;
+    edges: ReadonlyArray<HexEdgeState<BoardIdValue, SpaceIdValue, EdgeIdValue, EdgeFields> | GeneratedTiledEdgeStateLike<SpaceIdValue, EdgeIdValue, EdgeFields>>;
+    vertices: ReadonlyArray<HexVertexState<BoardIdValue, SpaceIdValue, VertexIdValue, VertexFields> | GeneratedTiledVertexStateLike<SpaceIdValue, VertexIdValue, VertexFields>>;
+}
+type HexBoardInput<BoardIdValue extends string = BoardId, SpaceIdValue extends string = string, EdgeIdValue extends string = string, VertexIdValue extends string = string, SpaceFields = RuntimeFields, EdgeFields = RuntimeFields, VertexFields = RuntimeFields> = AuthoredHexBoardInput<BoardIdValue, SpaceIdValue, EdgeIdValue, VertexIdValue, SpaceFields, EdgeFields, VertexFields> | GeneratedHexBoardInput<BoardIdValue, SpaceIdValue, EdgeIdValue, VertexIdValue, SpaceFields, EdgeFields, VertexFields>;
+interface GeneratedSquareBoardInput<BoardIdValue extends string = BoardId, SpaceIdValue extends string = string, EdgeIdValue extends string = string, VertexIdValue extends string = string, PieceIdValue extends string = string, SpaceFields = RuntimeFields, EdgeFields = RuntimeFields, VertexFields = RuntimeFields, PieceFields = RuntimeFields> {
+    id: BoardIdValue;
+    layout?: "square";
+    spaces: Readonly<Record<SpaceIdValue, GeneratedSquareSpaceStateLike<SpaceIdValue, SpaceFields>>>;
+    edges: ReadonlyArray<SquareEdgeState<SpaceIdValue, EdgeIdValue, EdgeFields> | GeneratedTiledEdgeStateLike<SpaceIdValue, EdgeIdValue, EdgeFields>>;
+    vertices: ReadonlyArray<SquareVertexState<SpaceIdValue, VertexIdValue, VertexFields> | GeneratedTiledVertexStateLike<SpaceIdValue, VertexIdValue, VertexFields>>;
+    pieces?: ReadonlyArray<SquarePieceState<PieceIdValue, PieceFields>>;
+}
+interface AuthoredSquareBoardInput<BoardIdValue extends string = BoardId, SpaceIdValue extends string = string, EdgeIdValue extends string = string, VertexIdValue extends string = string, PieceIdValue extends string = string, SpaceFields = RuntimeFields, EdgeFields = RuntimeFields, VertexFields = RuntimeFields, PieceFields = RuntimeFields> {
+    id: BoardIdValue;
+    layout?: "square";
+    rows: number;
+    cols: number;
+    cells: ReadonlyArray<SquareCellState<SpaceIdValue, SpaceFields>>;
+    edges: ReadonlyArray<SquareEdgeState<SpaceIdValue, EdgeIdValue, EdgeFields> | GeneratedTiledEdgeStateLike<SpaceIdValue, EdgeIdValue, EdgeFields>>;
+    vertices: ReadonlyArray<SquareVertexState<SpaceIdValue, VertexIdValue, VertexFields> | GeneratedTiledVertexStateLike<SpaceIdValue, VertexIdValue, VertexFields>>;
+    pieces: ReadonlyArray<SquarePieceState<PieceIdValue, PieceFields>>;
+}
+type SquareBoardInput<BoardIdValue extends string = BoardId, SpaceIdValue extends string = string, EdgeIdValue extends string = string, VertexIdValue extends string = string, PieceIdValue extends string = string, SpaceFields = RuntimeFields, EdgeFields = RuntimeFields, VertexFields = RuntimeFields, PieceFields = RuntimeFields> = AuthoredSquareBoardInput<BoardIdValue, SpaceIdValue, EdgeIdValue, VertexIdValue, PieceIdValue, SpaceFields, EdgeFields, VertexFields, PieceFields> | GeneratedSquareBoardInput<BoardIdValue, SpaceIdValue, EdgeIdValue, VertexIdValue, PieceIdValue, SpaceFields, EdgeFields, VertexFields, PieceFields>;
+type AnyHexBoardInput = HexBoardInput<string, string, string, string, RuntimeFields, RuntimeFields, RuntimeFields>;
+type AnySquareBoardInput = SquareBoardInput<string, string, string, string, string, RuntimeFields, RuntimeFields, RuntimeFields, RuntimeFields>;
+type BoardIdOf<TBoard> = TBoard extends {
+    id: infer Id extends string;
+} ? Id : string;
+type SpaceRecordValueOf<TBoard> = TBoard extends {
+    spaces: Readonly<Record<string, infer Space>>;
+} ? Space : never;
+type TileValueOf<TBoard> = TBoard extends {
+    tiles: ReadonlyArray<infer Tile>;
+} ? Tile : never;
+type CellValueOf<TBoard> = TBoard extends {
+    cells: ReadonlyArray<infer Cell>;
+} ? Cell : never;
+type EdgeValueOf<TBoard> = TBoard extends {
+    edges: ReadonlyArray<infer Edge>;
+} ? Edge : never;
+type VertexValueOf<TBoard> = TBoard extends {
+    vertices: ReadonlyArray<infer Vertex>;
+} ? Vertex : never;
+type PieceValueOf<TBoard> = TBoard extends {
+    pieces?: ReadonlyArray<infer Piece>;
+} ? Piece : never;
+type BoardSpaceIdOf<TBoard> = SpaceRecordValueOf<TBoard> extends {
+    id: infer Id extends string;
+} ? Id : TileValueOf<TBoard> extends {
+    id: infer Id extends string;
+} ? Id : CellValueOf<TBoard> extends {
+    id: infer Id extends string;
+} ? Id : never;
+type BoardEdgeIdOf<TBoard> = EdgeValueOf<TBoard> extends {
+    id: infer Id extends string;
+} ? Id : never;
+type BoardVertexIdOf<TBoard> = VertexValueOf<TBoard> extends {
+    id: infer Id extends string;
+} ? Id : never;
+type HexTilePropertiesOf<TBoard> = SpaceRecordValueOf<TBoard> extends {
+    fields?: infer Fields;
+} ? Fields : TileValueOf<TBoard> extends {
+    properties?: infer Properties;
+} ? Properties : RuntimeFields;
+type HexTileViewOf<TBoard> = TileValueOf<TBoard> extends {
+    view: infer View;
+} ? View : TileValueOf<TBoard> extends {
+    view?: infer View;
+} ? View | undefined : unknown;
+type HexEdgePropertiesOf<TBoard> = EdgeValueOf<TBoard> extends {
+    fields?: infer Fields;
+} ? Fields : EdgeValueOf<TBoard> extends {
+    properties?: infer Properties;
+} ? Properties : RuntimeFields;
+type HexVertexPropertiesOf<TBoard> = VertexValueOf<TBoard> extends {
+    fields?: infer Fields;
+} ? Fields : VertexValueOf<TBoard> extends {
+    properties?: infer Properties;
+} ? Properties : RuntimeFields;
+type SquareCellPropertiesOf<TBoard> = SpaceRecordValueOf<TBoard> extends {
+    fields?: infer Fields;
+} ? Fields : CellValueOf<TBoard> extends {
+    properties?: infer Properties;
+} ? Properties : RuntimeFields;
+type SquareEdgePropertiesOf<TBoard> = EdgeValueOf<TBoard> extends {
+    fields?: infer Fields;
+} ? Fields : EdgeValueOf<TBoard> extends {
+    properties?: infer Properties;
+} ? Properties : RuntimeFields;
+type SquareVertexPropertiesOf<TBoard> = VertexValueOf<TBoard> extends {
+    fields?: infer Fields;
+} ? Fields : VertexValueOf<TBoard> extends {
+    properties?: infer Properties;
+} ? Properties : RuntimeFields;
+type SquarePiecePropertiesOf<TBoard> = PieceValueOf<TBoard> extends {
+    properties?: infer Properties;
+} ? Properties : RuntimeFields;
+/**
+ * Normalized hex tile shape for a given board input.
+ *
+ * `view` is always present (required) on the result so consumers can
+ * read overlay fields without a null-check. For boards that do not
+ * statically declare a `view` shape (the generic case), `view` falls
+ * back to `unknown`, which still admits any value.
+ *
+ * The runtime normalizer injects `view: undefined` for inputs that
+ * do not author a `view` field, keeping the runtime contract aligned
+ * with this static shape.
+ */
+type NormalizedHexTileOf<TBoard extends AnyHexBoardInput> = Omit<HexTileState<BoardIdOf<TBoard>, BoardSpaceIdOf<TBoard>, HexTilePropertiesOf<TBoard>, HexTileViewOf<TBoard>>, "view"> & {
+    view: HexTileViewOf<TBoard>;
+};
+type NormalizedHexEdgeOf<TBoard extends AnyHexBoardInput> = HexEdgeState<BoardIdOf<TBoard>, BoardSpaceIdOf<TBoard>, BoardEdgeIdOf<TBoard>, HexEdgePropertiesOf<TBoard>>;
+type NormalizedHexVertexOf<TBoard extends AnyHexBoardInput> = HexVertexState<BoardIdOf<TBoard>, BoardSpaceIdOf<TBoard>, BoardVertexIdOf<TBoard>, HexVertexPropertiesOf<TBoard>>;
+type NormalizedSquareCellOf<TBoard extends AnySquareBoardInput> = SquareCellState<BoardSpaceIdOf<TBoard>, SquareCellPropertiesOf<TBoard>>;
+type NormalizedSquareEdgeOf<TBoard extends AnySquareBoardInput> = SquareEdgeState<BoardSpaceIdOf<TBoard>, BoardEdgeIdOf<TBoard>, SquareEdgePropertiesOf<TBoard>>;
+type NormalizedSquareVertexOf<TBoard extends AnySquareBoardInput> = SquareVertexState<BoardSpaceIdOf<TBoard>, BoardVertexIdOf<TBoard>, SquareVertexPropertiesOf<TBoard>>;
+type NormalizedSquarePieceOf<TBoard extends AnySquareBoardInput> = SquarePieceState<PieceValueOf<TBoard> extends {
+    id: infer PieceIdValue extends string;
+} ? PieceIdValue : string, SquarePiecePropertiesOf<TBoard>>;
+type NormalizedHexBoard<TBoard extends AnyHexBoardInput> = Omit<Pick<HexBoardState<BoardIdOf<TBoard>, BoardSpaceIdOf<TBoard>, BoardEdgeIdOf<TBoard>, BoardVertexIdOf<TBoard>, HexTilePropertiesOf<TBoard>, HexEdgePropertiesOf<TBoard>, HexVertexPropertiesOf<TBoard>>, "id" | "tiles" | "edges" | "vertices">, "tiles"> & {
+    tiles: ReadonlyArray<NormalizedHexTileOf<TBoard>>;
+    orientation?: "pointy-top" | "flat-top";
+};
+type NormalizedSquareBoard<TBoard extends AnySquareBoardInput> = Pick<SquareBoardState<BoardIdOf<TBoard>, BoardSpaceIdOf<TBoard>, BoardEdgeIdOf<TBoard>, BoardVertexIdOf<TBoard>, PieceValueOf<TBoard> extends {
+    id: infer PieceIdValue extends string;
+} ? PieceIdValue : string, SquareCellPropertiesOf<TBoard>, SquareEdgePropertiesOf<TBoard>, SquareVertexPropertiesOf<TBoard>, SquarePiecePropertiesOf<TBoard>>, "id" | "rows" | "cols" | "cells" | "edges" | "vertices" | "pieces">;
+declare function normalizeHexBoardInput<TBoard extends AnyHexBoardInput>(board: TBoard): NormalizedHexBoard<TBoard>;
+declare function normalizeSquareBoardInput<TBoard extends AnySquareBoardInput>(board: TBoard): NormalizedSquareBoard<TBoard>;
+
+type BoardTargetKind = "edge" | "vertex" | "space" | "tile";
+interface InteractiveTargetState {
+    kind?: BoardTargetKind;
+    id: string;
+    eligible: boolean;
+    selectable: boolean;
+    hovered: boolean;
+    pending: boolean;
+    conflict: boolean;
+    unavailableReason?: string;
+    select?: () => unknown | Promise<unknown>;
+}
+interface InteractiveTargetLayer {
+    enabled?: boolean;
+    eligible?: ReadonlySet<string>;
+    selectTargetId?: (targetId: string) => unknown | Promise<unknown>;
+    targetState?: (targetId: string) => Partial<InteractiveTargetState>;
+}
+interface InteractiveTargetRenderState extends InteractiveTargetState {
+    isEnabled: boolean;
+    isEligible: boolean;
+    isHovered: boolean;
+}
+
+type HexOrientation = "pointy-top" | "flat-top";
+/**
+ * Geometry context passed to `renderTile`.
+ *
+ * `corners`, `points`, and `bounds` are expressed in tile-local
+ * coordinates because each tile is rendered inside a `<g>` translated
+ * to its center. Use `position` if you need the resolved center in the
+ * board's absolute SVG coordinates.
+ *
+ * The `inset` option shrinks the polygon toward the center by that many
+ * pixels, which is useful for layered effects such as borders, frames,
+ * or inner highlights without re-deriving the hex math yourself.
+ */
+interface HexTileGeometry {
+    size: number;
+    orientation: HexOrientation;
+    center: {
+        x: 0;
+        y: 0;
+    };
+    position: {
+        x: number;
+        y: number;
+    };
+    corners: (options?: {
+        inset?: number;
+    }) => Array<{
+        x: number;
+        y: number;
+    }>;
+    points: (options?: {
+        inset?: number;
+    }) => string;
+    bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+        width: number;
+        height: number;
+    };
+}
+interface EdgePosition {
+    /** Absolute SVG start point of the visible edge line. */
+    x1: number;
+    y1: number;
+    /** Absolute SVG end point of the visible edge line. */
+    x2: number;
+    y2: number;
+    /** Absolute SVG midpoint of the edge. */
+    midX: number;
+    midY: number;
+    /**
+     * Angle in degrees from hex1 center to hex2 center.
+     * This is perpendicular to the visible edge line.
+     */
+    centerAngle: number;
+    /** Angle in degrees of the visible edge line itself. */
+    edgeAngle: number;
+}
+interface InteractiveHexVertex<TBoard extends AnyHexBoardInput = AnyHexBoardInput> extends NormalizedHexVertexOf<TBoard> {
+    position: {
+        x: number;
+        y: number;
+    };
+    spaceIds: ReadonlyArray<BoardSpaceIdOf<TBoard>>;
+}
+interface InteractiveHexEdge<TBoard extends AnyHexBoardInput = AnyHexBoardInput> extends NormalizedHexEdgeOf<TBoard> {
+    position: EdgePosition;
+    spaceIds: ReadonlyArray<BoardSpaceIdOf<TBoard>>;
+}
+type InteractiveHexSpace<TBoard extends AnyHexBoardInput = AnyHexBoardInput> = NormalizedHexTileOf<TBoard>;
+interface HexGeneratedGridInputProps {
+    id?: string;
+    layout?: "hex";
+    orientation?: HexOrientation;
+    spaces: Extract<AnyHexBoardInput, {
+        spaces: unknown;
+    }>["spaces"];
+    edges?: AnyHexBoardInput["edges"];
+    vertices?: AnyHexBoardInput["vertices"];
+}
+interface HexAuthoredGridInputProps {
+    id?: string;
+    layout?: "hex";
+    orientation?: HexOrientation;
+    tiles: Extract<AnyHexBoardInput, {
+        tiles: unknown;
+    }>["tiles"];
+    edges?: AnyHexBoardInput["edges"];
+    vertices?: AnyHexBoardInput["vertices"];
+}
+type HexGridInputProps = HexGeneratedGridInputProps | HexAuthoredGridInputProps;
+type ResolvedArrayProp<Value> = Exclude<Value, undefined> extends readonly unknown[] ? Exclude<Value, undefined> : readonly [];
+type HexBoardLikeOfProps<TProps extends HexGridInputProps> = TProps extends {
+    id?: infer Id;
+    layout?: infer Layout;
+    orientation?: infer Orientation;
+    spaces: infer Spaces;
+    edges?: infer Edges;
+    vertices?: infer Vertices;
+} ? {
+    id: Extract<Id, string> extends never ? string : Extract<Id, string>;
+    layout?: Extract<Layout, "hex">;
+    orientation?: Extract<Orientation, HexOrientation>;
+    spaces: Spaces;
+    edges: ResolvedArrayProp<Edges>;
+    vertices: ResolvedArrayProp<Vertices>;
+} & GeneratedHexBoardInput : TProps extends {
+    id?: infer Id;
+    layout?: infer Layout;
+    orientation?: infer Orientation;
+    tiles: infer Tiles;
+    edges?: infer Edges;
+    vertices?: infer Vertices;
+} ? {
+    id: Extract<Id, string> extends never ? string : Extract<Id, string>;
+    layout?: Extract<Layout, "hex">;
+    orientation?: Extract<Orientation, HexOrientation>;
+    tiles: Tiles;
+    edges: ResolvedArrayProp<Edges>;
+    vertices: ResolvedArrayProp<Vertices>;
+} & AuthoredHexBoardInput : never;
+type HexGridProps<TProps extends HexGridInputProps = HexGridInputProps> = TProps & {
+    orientation?: HexOrientation;
+    /** Hex radius in pixels */
+    hexSize?: number;
+    /**
+     * Receives tile data centered at (0,0) plus a `HexTileGeometry`
+     * helper. Use `geometry.points({ inset })` to draw custom polygons
+     * without duplicating `hexSize` / orientation in the consumer.
+     */
+    renderTile: (tile: NormalizedHexTileOf<NoInfer<HexBoardLikeOfProps<TProps>>>, geometry: HexTileGeometry) => ReactNode;
+    /**
+     * Receives edge geometry in absolute SVG coordinates.
+     * Use `position.edgeAngle` to align artwork with the visible edge.
+     */
+    renderEdge: (edge: NormalizedHexEdgeOf<NoInfer<HexBoardLikeOfProps<TProps>>>, position: EdgePosition) => ReactNode;
+    renderVertex: (vertex: NormalizedHexVertexOf<NoInfer<HexBoardLikeOfProps<TProps>>>, position: {
+        x: number;
+        y: number;
+    }) => ReactNode;
+    width?: number | string;
+    height?: number | string;
+    enablePanZoom?: boolean;
+    initialZoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    className?: string;
+    /** Reducer-aware space target layer from `board.targetLayers.space(...)`. */
+    interactiveSpaces?: InteractiveTargetLayer;
+    /** Reducer-aware vertex target layer from `board.targetLayers.vertex(...)`. */
+    interactiveVertices?: InteractiveTargetLayer;
+    /** Reducer-aware edge target layer from `board.targetLayers.edge(...)`. */
+    interactiveEdges?: InteractiveTargetLayer;
+    /** Receives space geometry centered at (0,0). */
+    renderInteractiveSpace?: (space: InteractiveHexSpace<NoInfer<HexBoardLikeOfProps<TProps>>>, state: InteractiveTargetRenderState) => ReactNode;
+    /**
+     * Receives vertex geometry in absolute SVG coordinates.
+     */
+    renderInteractiveVertex?: (vertex: InteractiveHexVertex<NoInfer<HexBoardLikeOfProps<TProps>>>, position: {
+        x: number;
+        y: number;
+    }, state: InteractiveTargetRenderState) => ReactNode;
+    /**
+     * Receives edge geometry in the same absolute SVG coordinates as `renderEdge`.
+     */
+    renderInteractiveEdge?: (edge: InteractiveHexEdge<NoInfer<HexBoardLikeOfProps<TProps>>>, position: EdgePosition, state: InteractiveTargetRenderState) => ReactNode;
+    interactiveVertexSize?: number;
+    interactiveEdgeSize?: number;
+};
+interface HexGridBoardProps<TBoard extends AnyHexBoardInput = AnyHexBoardInput> {
+    board: TBoard;
+    orientation?: HexOrientation;
+    hexSize?: number;
+    /**
+     * Receives tile data centered at (0,0) plus a `HexTileGeometry`
+     * helper. Use `geometry.points({ inset })` to draw custom polygons
+     * without duplicating `hexSize` / orientation in the consumer.
+     */
+    renderTile: (tile: NormalizedHexTileOf<NoInfer<TBoard>>, geometry: HexTileGeometry) => ReactNode;
+    /**
+     * Receives edge geometry in absolute SVG coordinates.
+     * Use `position.edgeAngle` to align artwork with the visible edge.
+     */
+    renderEdge: (edge: NormalizedHexEdgeOf<NoInfer<TBoard>>, position: EdgePosition) => ReactNode;
+    renderVertex: (vertex: NormalizedHexVertexOf<NoInfer<TBoard>>, position: {
+        x: number;
+        y: number;
+    }) => ReactNode;
+    width?: number | string;
+    height?: number | string;
+    enablePanZoom?: boolean;
+    initialZoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    className?: string;
+    interactiveSpaces?: InteractiveTargetLayer;
+    interactiveVertices?: InteractiveTargetLayer;
+    interactiveEdges?: InteractiveTargetLayer;
+    /** Receives space geometry centered at (0,0). */
+    renderInteractiveSpace?: (space: InteractiveHexSpace<NoInfer<TBoard>>, state: InteractiveTargetRenderState) => ReactNode;
+    /**
+     * Receives vertex geometry in absolute SVG coordinates.
+     */
+    renderInteractiveVertex?: (vertex: InteractiveHexVertex<NoInfer<TBoard>>, position: {
+        x: number;
+        y: number;
+    }, state: InteractiveTargetRenderState) => ReactNode;
+    /**
+     * Receives edge geometry in the same absolute SVG coordinates as `renderEdge`.
+     */
+    renderInteractiveEdge?: (edge: InteractiveHexEdge<NoInfer<TBoard>>, position: EdgePosition, state: InteractiveTargetRenderState) => ReactNode;
+    interactiveVertexSize?: number;
+    interactiveEdgeSize?: number;
+}
+interface DefaultHexTileProps {
+    /** Should match hexSize from HexGrid */
+    size: number;
+    fill: string;
+    stroke?: string;
+    strokeWidth?: number;
+    isSelected?: boolean;
+    isHighlighted?: boolean;
+    label?: string;
+    showCoordinates?: boolean;
+    coordinates?: {
+        q: number;
+        r: number;
+    };
+    orientation?: HexOrientation;
+    onClick?: () => void;
+    onPointerEnter?: () => void;
+    onPointerLeave?: () => void;
+    className?: string;
+}
+/** Pre-built hexagon tile for use in `renderTile`. */
+declare function DefaultHexTile({ size, fill, stroke, strokeWidth, isSelected, isHighlighted, label, showCoordinates, coordinates, orientation, onClick, onPointerEnter, onPointerLeave, className, }: DefaultHexTileProps): react_jsx_runtime.JSX.Element;
+interface DefaultHexEdgeProps {
+    position: EdgePosition;
+    color: string;
+    hasOwner?: boolean;
+    strokeWidth?: number;
+    touchTargetSize?: number;
+    onClick?: () => void;
+    className?: string;
+}
+/** Pre-built edge/road component for use in `renderEdge`. */
+declare function DefaultHexEdge({ position, color, hasOwner, strokeWidth, touchTargetSize, onClick, className, }: DefaultHexEdgeProps): react_jsx_runtime.JSX.Element;
+interface DefaultHexVertexProps {
+    position: {
+        x: number;
+        y: number;
+    };
+    color: string;
+    stroke?: string;
+    strokeWidth?: number;
+    hasOwner?: boolean;
+    isSelected?: boolean;
+    isHighlighted?: boolean;
+    size?: number;
+    touchTargetSize?: number;
+    shape?: "circle" | "square";
+    onClick?: () => void;
+    onPointerEnter?: () => void;
+    onPointerLeave?: () => void;
+    className?: string;
+}
+/** Pre-built vertex/settlement component for use in `renderVertex`. */
+declare function DefaultHexVertex({ position, color, stroke, strokeWidth, hasOwner, isSelected, isHighlighted, size, touchTargetSize, shape, onClick, onPointerEnter, onPointerLeave, className, }: DefaultHexVertexProps): react_jsx_runtime.JSX.Element;
+declare const hexUtils: {
+    /** Convert axial coordinates to pixel position. */
+    axialToPixel(q: number, r: number, size: number, orientation: HexOrientation): {
+        x: number;
+        y: number;
+    };
+    getNeighbors(q: number, r: number): Array<{
+        q: number;
+        r: number;
+    }>;
+    getDistance(q1: number, r1: number, q2: number, r2: number): number;
+    getHexCorners(centerX: number, centerY: number, size: number, orientation: HexOrientation): Array<{
+        x: number;
+        y: number;
+    }>;
+    getHexPoints(centerX: number, centerY: number, size: number, orientation: HexOrientation): string;
+    getEdgePosition(hex1Pos: {
+        x: number;
+        y: number;
+    }, hex2Pos: {
+        x: number;
+        y: number;
+    }, size: number): EdgePosition;
+    getVertexPosition(hex1Pos: {
+        x: number;
+        y: number;
+    }, hex2Pos: {
+        x: number;
+        y: number;
+    }, hex3Pos: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+};
+interface HexGridComponent {
+    <const TBoard extends AnyHexBoardInput>(props: HexGridBoardProps<TBoard>): ReactNode;
+    <const TProps extends HexGeneratedGridInputProps>(props: HexGridProps<TProps>): ReactNode;
+    <const TProps extends HexAuthoredGridInputProps>(props: HexGridProps<TProps>): ReactNode;
+}
+declare const HexGrid: HexGridComponent;
+
+/**
+ * Typed adapter for joining static hex-board topology with a dynamic
+ * per-space view overlay. Use this to feed `HexGrid` a single board
+ * value whose tiles carry both static geometry (`q`, `r`, `id`) and
+ * the projected view fields the UI cares about (e.g. `terrain`,
+ * `numberToken`).
+ *
+ * The runtime is intentionally strict: every static space must have
+ * exactly one overlay, duplicates throw, and overlays for ids that
+ * are not on the board throw. There is no relaxed fallback in v1 —
+ * silent merge bugs are far more expensive than a loud throw at
+ * dev/CI time.
+ */
+
+/**
+ * Per-tile result produced by {@link createHexBoardView}. Each tile
+ * carries the static topology (`id`, `q`, `r`) plus the matched
+ * overlay row in `view`.
+ *
+ * Static board fields/properties are preserved from `TBoard`.
+ * Consumers should use `tile.properties` for authored static space
+ * fields and `tile.view` for dynamic per-space projection data.
+ */
+type HexBoardViewTile<TBoard extends AnyHexBoardInput, TSpaceView extends {
+    id: BoardSpaceIdOf<TBoard>;
+}> = Omit<NormalizedHexTileOf<TBoard>, "view"> & {
+    view: TSpaceView;
+};
+/**
+ * Result of {@link createHexBoardView}. Shaped like an authored hex
+ * board so it can be passed straight to `<HexGrid board={...} />`
+ * without any further adapter work.
+ *
+ * The type-level board id and space id are preserved from `TBoard`,
+ * so `tile.id` stays narrow inside `renderTile`. `tile.view` is the
+ * authored overlay row, fully typed.
+ */
+interface HexBoardView<TBoard extends AnyHexBoardInput, TSpaceView extends {
+    id: BoardSpaceIdOf<TBoard>;
+}> {
+    id: BoardIdOf<TBoard>;
+    layout?: "hex";
+    orientation?: "pointy-top" | "flat-top";
+    tiles: ReadonlyArray<HexBoardViewTile<TBoard, TSpaceView>>;
+    edges: TBoard["edges"];
+    vertices: TBoard["vertices"];
+}
+interface CreateHexBoardViewOptions<TSpaceView> {
+    spaces: readonly TSpaceView[];
+}
+/**
+ * Join a static hex board topology with a dynamic per-space overlay.
+ *
+ * The result is suitable for direct use as the `board` prop on
+ * `<HexGrid>`. Every overlay is enforced 1-to-1 against the board's
+ * spaces:
+ *
+ *  - missing overlay for a board space → throws
+ *  - duplicate overlay (same `id` twice) → throws
+ *  - overlay `id` not present on the board → throws
+ *
+ * Each tile in the result carries a `view` field with the matched
+ * overlay row.
+ */
+declare function createHexBoardView<const TBoard extends AnyHexBoardInput, const TSpaceView extends {
+    id: BoardSpaceIdOf<TBoard>;
+}>(board: TBoard, options: CreateHexBoardViewOptions<TSpaceView>): HexBoardView<TBoard, TSpaceView>;
+
+export { type ThemeMeta as $, type AnyHexBoardInput as A, type BoardEdgeIdOf as B, type ColorRamp as C, DefaultHexEdge as D, type EdgePosition as E, type FoundationColor as F, type GeneratedHexBoardInput as G, type HexBoardInput as H, type IntentColor as I, type InteractiveTargetLayer as J, type InteractiveTargetRenderState as K, type NormalizedHexEdgeOf as L, type Motion as M, type NormalizedHexBoard as N, type NormalizedHexTileOf as O, type NormalizedHexVertexOf as P, type NormalizedSquareBoard as Q, type NormalizedSquareCellOf as R, type NormalizedSquareEdgeOf as S, type NormalizedSquarePieceOf as T, type NormalizedSquareVertexOf as U, type PlayerColor as V, type Radius as W, type SemanticColor as X, type Space as Y, type SquareBoardInput as Z, type Theme as _, type AnySquareBoardInput as a, type ThemeOverride as a0, type Typography as a1, createHexBoardView as a2, hexUtils as a3, mergeTheme as a4, normalizeHexBoardInput as a5, normalizeSquareBoardInput as a6, type AuthoredHexBoardInput as b, type AuthoredSquareBoardInput as c, type BoardSpaceIdOf as d, type BoardVertexIdOf as e, type ComponentTokens as f, type DefaultHexEdgeProps as g, DefaultHexTile as h, type DefaultHexTileProps as i, DefaultHexVertex as j, type DefaultHexVertexProps as k, type Elevation as l, type GeneratedHexSpaceStateLike as m, type GeneratedSquareBoardInput as n, type GeneratedSquareSpaceStateLike as o, type GeneratedTiledEdgeStateLike as p, type GeneratedTiledVertexStateLike as q, type HexBoardView as r, type HexBoardViewTile as s, HexGrid as t, type HexGridBoardProps as u, type HexGridProps as v, type HexOrientation as w, type HexTileGeometry as x, type InteractiveHexEdge as y, type InteractiveHexVertex as z };