@ankhorage/zora 21.0.23 → 21.1.0

package/dist/types/tabletop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabletop.js","sourceRoot":"","sources":["../../src/types/tabletop.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nimport type { ZoraBaseProps } from './base';\n\nexport type PlayingCardSuit = 'clubs' | 'diamonds' | 'hearts' | 'spades';\nexport type TabletopCardSize = 'large' | 'medium' | 'small';\nexport type TabletopShape = 'circle' | 'oval' | 'rounded';\nexport type TabletopSeatCount = 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;\n\nexport interface PlayingCardValue {\n  readonly rank: string;\n  readonly suit: PlayingCardSuit;\n}\nexport interface TabletopSeatState {\n  readonly id: string;\n  readonly label: React.ReactNode;\n  readonly sublabel?: React.ReactNode;\n  readonly cards?: readonly PlayingCardValue[];\n  readonly faceDownCards?: number;\n  readonly selected?: boolean;\n  readonly muted?: boolean;\n  readonly disabled?: boolean;\n  readonly tokenLabel?: React.ReactNode;\n  readonly accessibilityLabel?: string;\n}\nexport type TabletopGameSeatPresentation = Omit<TabletopSeatState, 'id'>;\nexport interface TabletopGameSeatDefinition {\n  readonly id: string;\n  readonly defaultState: TabletopGameSeatPresentation;\n}\nexport interface TabletopGameParticipantState {\n  readonly seatId: string;\n  readonly state: Partial<TabletopGameSeatPresentation>;\n}\nexport interface CreateTabletopGameSeatsInput {\n  readonly seats: readonly TabletopGameSeatDefinition[];\n  readonly participants: readonly TabletopGameParticipantState[];\n  readonly missingParticipantState?: Partial<TabletopGameSeatPresentation>;\n}\nexport interface TabletopColorScheme {\n  readonly cardBack: string;\n  readonly cardBackBorder: string;\n  readonly cardBorder: string;\n  readonly cardSurface: string;\n  readonly cardText: string;\n  readonly mutedText: string;\n  readonly redSuitText: string;\n  readonly seatBorder: string;\n  readonly seatMutedText: string;\n  readonly seatSelectedBorder: string;\n  readonly seatSurface: string;\n  readonly seatText: string;\n  readonly tableBorder: string;\n  readonly tableFelt: string;\n  readonly tableInnerBorder: string;\n  readonly tableMutedText: string;\n  readonly tableText: string;\n  readonly tokenSurface: string;\n  readonly tokenText: string;\n}\nexport type TabletopColorOverrides = Partial<TabletopColorScheme>;\nexport interface CardBackProps extends ZoraBaseProps {\n  readonly size?: TabletopCardSize;\n  readonly muted?: boolean;\n  readonly accessibilityLabel?: string;\n  readonly colorScheme?: TabletopColorOverrides;\n}\nexport interface CardHandProps extends ZoraBaseProps {\n  readonly cards?: readonly PlayingCardValue[];\n  readonly faceDownCards?: number;\n  readonly size?: TabletopCardSize;\n  readonly muted?: boolean;\n  readonly colorScheme?: TabletopColorOverrides;\n  readonly accessibilityLabel?: string;\n}\nexport interface PlayingCardProps extends ZoraBaseProps {\n  readonly card: PlayingCardValue;\n  readonly size?: TabletopCardSize;\n  readonly selected?: boolean;\n  readonly muted?: boolean;\n  readonly accessibilityLabel?: string;\n  readonly colorScheme?: TabletopColorOverrides;\n}\nexport interface TabletopTableProps extends ZoraBaseProps {\n  readonly seats: readonly TabletopSeatState[];\n  readonly centerCards?: readonly PlayingCardValue[];\n  readonly centerLabel?: React.ReactNode;\n  readonly centerSublabel?: React.ReactNode;\n  readonly shape?: TabletopShape;\n  readonly seatCount?: TabletopSeatCount;\n  readonly cardSize?: TabletopCardSize;\n  readonly disabled?: boolean;\n  readonly colorScheme?: TabletopColorOverrides;\n  readonly accessibilityLabel?: string;\n}\nexport interface PokerTrainingPlayer {\n  readonly position: string;\n  readonly stack?: number;\n  readonly bet?: number;\n  readonly cards?: readonly PlayingCardValue[];\n  readonly folded?: boolean;\n  readonly isHero?: boolean;\n}\nexport type PokerTrainingTableSize = '6max' | '9max';\nexport interface PokerTrainingTaskTableData {\n  readonly tableSize?: PokerTrainingTableSize;\n  readonly blinds?: { readonly small: number; readonly big: number };\n  readonly heroPosition?: string;\n  readonly heroCards?: readonly PlayingCardValue[];\n  readonly communityCards?: readonly PlayingCardValue[];\n  readonly pot?: number;\n  readonly players?: readonly PokerTrainingPlayer[];\n}\nexport interface PokerTrainingTableProps extends Omit<\n  TabletopTableProps,\n  'seatCount' | 'seats' | 'centerCards' | 'centerLabel' | 'centerSublabel'\n> {\n  readonly task?: PokerTrainingTaskTableData;\n  readonly defaultStackBigBlinds?: number;\n}\nexport interface CreatePokerTrainingTableStateOptions {\n  readonly defaultStackBigBlinds?: number;\n}\nexport interface PokerTrainingTableState {\n  readonly seatCount: TabletopSeatCount;\n  readonly seats: readonly TabletopSeatState[];\n  readonly centerCards: readonly PlayingCardValue[];\n  readonly centerLabel?: string;\n  readonly centerSublabel?: string;\n  readonly accessibilityLabel: string;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "21.0.23",
+  "version": "21.1.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -42,6 +42,8 @@
   "dependencies": {
     "@ankhorage/color-theory": "^0.3.1",
     "@ankhorage/contracts": "^22.8.2",
+    "@ankhorage/game": "^0.1.2",
+    "@ankhorage/runtime": "^3.0.25",
     "@ankhorage/surface": "^9.1.7",
     "@ankhorage/utility": "^1.8.1",
     "expo-document-picker": "~57.0.1",

package/src/features/authoring/allowedChildren.ts

@@ -63,6 +63,11 @@ export const CONTAINER_ALLOWED_CHILDREN = [
   'MissingElement',
 ] as const;
 
+export const GAME_ALLOWED_CHILDREN = ['Game', 'GameField'] as const;
+
+export const CHESS_ALLOWED_CHILDREN = ['ChessBoard', 'OpeningBook'] as const;
+export const TABLETOP_ALLOWED_CHILDREN = ['TabletopTable', 'PokerTrainingTable'] as const;
+
 export const CONTENT_RAIL_ALLOWED_CHILDREN = [
   'Chip',
   'ChipGroup',
@@ -84,6 +89,14 @@ export const CONTENT_RAIL_ALLOWED_CHILDREN = [
   'MissingElement',
 ] as const;
 
-export const SCREEN_SECTION_ALLOWED_CHILDREN = [...CONTAINER_ALLOWED_CHILDREN] as const;
+export const SCREEN_SECTION_ALLOWED_CHILDREN = [
+  ...CONTAINER_ALLOWED_CHILDREN,
+  ...CHESS_ALLOWED_CHILDREN,
+  ...GAME_ALLOWED_CHILDREN,
+  ...TABLETOP_ALLOWED_CHILDREN,
+] as const;
 
-export const SCREEN_ALLOWED_CHILDREN = ['ScreenSection', ...CONTAINER_ALLOWED_CHILDREN] as const;
+export const SCREEN_ALLOWED_CHILDREN = [
+  'ScreenSection',
+  ...SCREEN_SECTION_ALLOWED_CHILDREN,
+] as const;

package/src/features/authoring/componentMeta.test.ts

@@ -17,6 +17,32 @@ describe('ZORA_COMPONENT_META public API', () => {
 });
 
 describe('ZORA_COMPONENT_META registry coverage', () => {
+  test('registers the six Game components and their canonical placements', () => {
+    const names = [
+      'Game',
+      'GameField',
+      'GameEntity',
+      'GameInputZone',
+      'GameMeasurementProbe',
+      'GameOverlay',
+    ] as const;
+    const gameMetadata = Object.values(ZORA_COMPONENT_META).filter((meta) =>
+      names.some((name) => name === meta.name),
+    );
+    expect(gameMetadata).toHaveLength(names.length);
+    for (const meta of gameMetadata) expect(meta.directManifestNode).toBe(true);
+    expect(ZORA_COMPONENT_META.Screen.allowedChildren).toContain('Game');
+    expect(ZORA_COMPONENT_META.ScreenSection.allowedChildren).toContain('GameField');
+    expect(ZORA_COMPONENT_META.Game.allowedChildren).toContain('GameInputZone');
+    expect(ZORA_COMPONENT_META.Game.allowedChildren).toContain('GameMeasurementProbe');
+    expect(ZORA_COMPONENT_META.GameField.allowedChildren).toContain('GameEntity');
+    expect(ZORA_COMPONENT_META.GameField.allowedChildren).toContain('GameOverlay');
+    expect(ZORA_COMPONENT_META.Game.bindings?.props?.definition?.value.type).toBe('object');
+    expect(ZORA_COMPONENT_META.Game.bindings?.events?.output?.payload.eventType).toBe(
+      'game.output',
+    );
+  });
+
   test('covers every public UI React component export (foundation/components/patterns/layout)', async () => {
     const source = await Bun.file('src/index.ts').text();
     const componentExports = Array.from(
@@ -185,6 +211,10 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'Divider',
       'ChatListItem',
       'CameraPermissionView',
+      'ChessBoard',
+      'GameInputZone',
+      'GameMeasurementProbe',
+      'OpeningBook',
       'ScanOverlay',
       'ProductCard',
       'Progress',
@@ -192,6 +222,8 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'ReaderSurface',
       'MissingElement',
       'TimePicker',
+      'TabletopTable',
+      'PokerTrainingTable',
     ]);
 
     const expectedContainerNodes = new Set([
@@ -200,6 +232,10 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'Dialog',
       'Form',
       'Gradient',
+      'Game',
+      'GameEntity',
+      'GameField',
+      'GameOverlay',
       'Surface',
       'MediaCard',
       'FlatList',
@@ -254,6 +290,63 @@ describe('ZORA_COMPONENT_META invariants', () => {
     expect(ZORA_COMPONENT_META.Tabs.events?.valueChange?.eventType).toBe('tabs.valueChange');
   });
 
+  test('Chess and Tabletop retain their direct placement hierarchy without exposing card subprimitives', () => {
+    for (const name of ['CardBack', 'CardHand', 'PlayingCard']) {
+      expect(
+        Object.values(ZORA_COMPONENT_META).find((meta) => meta.name === name)?.directManifestNode,
+      ).toBe(false);
+      for (const meta of Object.values(ZORA_COMPONENT_META)) {
+        expect(meta.allowedChildren).not.toContain(name);
+      }
+    }
+    for (const parent of [
+      ZORA_COMPONENT_META.Card,
+      ZORA_COMPONENT_META.Grid,
+      ZORA_COMPONENT_META.Screen,
+      ZORA_COMPONENT_META.ScreenSection,
+    ]) {
+      for (const name of ['ChessBoard', 'OpeningBook', 'TabletopTable', 'PokerTrainingTable']) {
+        expect(parent.allowedChildren).toContain(name);
+      }
+    }
+    expect(ZORA_COMPONENT_META.View.allowedChildren).toContain('ChessBoard');
+    expect(ZORA_COMPONENT_META.View.allowedChildren).not.toContain('TabletopTable');
+    expect(ZORA_COMPONENT_META.ScrollView.allowedChildren).not.toContain('PokerTrainingTable');
+  });
+
+  test('Chess and Tabletop presentation bindings retain typed inputs and interaction intents', () => {
+    expect(ZORA_COMPONENT_META.ChessBoard.bindings?.props?.pieces?.value).toEqual({
+      type: 'array',
+      itemType: 'object',
+    });
+    expect(ZORA_COMPONENT_META.ChessBoard.bindings?.props?.legalTargets?.value).toEqual({
+      type: 'array',
+      itemType: 'string',
+    });
+    expect(ZORA_COMPONENT_META.OpeningBook.bindings?.props?.moves?.value).toEqual({
+      type: 'array',
+      itemType: 'object',
+    });
+    expect(ZORA_COMPONENT_META.OpeningBook.bindings?.events?.movePress?.payload.eventType).toBe(
+      'chess.openingMovePress',
+    );
+    expect(ZORA_COMPONENT_META.TabletopTable.bindings?.props?.seats?.value).toEqual({
+      type: 'array',
+      itemType: 'object',
+    });
+    expect(ZORA_COMPONENT_META.PokerTrainingTable.bindings?.props?.task?.value).toMatchObject({
+      type: 'object',
+      fields: [
+        { path: 'blinds' },
+        { path: 'heroPosition' },
+        { path: 'heroCards' },
+        { path: 'communityCards' },
+        { path: 'pot' },
+        { path: 'players' },
+      ],
+    });
+  });
+
   test('Accordion constrains authored items to its canonical hierarchy', () => {
     expect(ZORA_COMPONENT_META.Accordion.directManifestNode).toBe(true);
     expect(ZORA_COMPONENT_META.Accordion.allowedChildren).toEqual(['AccordionItem']);

package/src/features/authoring/componentMeta.ts

@@ -24,6 +24,7 @@ import { postCardMeta } from '../card/postCardMeta';
 import { productCardMeta } from '../card/productCardMeta';
 import { chatListItemMeta } from '../chat/chatListItemMeta';
 import { messageBubbleMeta } from '../chat/messageBubbleMeta';
+import { chessBoardMeta, openingBookMeta } from '../chess/meta';
 import { chipGroupMeta } from '../chip/chipGroupMeta';
 import { chipMeta } from '../chip/chipMeta';
 import { collectionEditorMeta } from '../collection-editor/meta';
@@ -42,6 +43,12 @@ import { searchInputMeta } from '../form/search-input/searchInputMeta';
 import { selectMeta } from '../form/select/selectMeta';
 import { switchMeta } from '../form/switch/switchMeta';
 import { textInputMeta } from '../form/text-input/textInputMeta';
+import { gameEntityMeta } from '../game/meta/gameEntityMeta';
+import { gameFieldMeta } from '../game/meta/gameFieldMeta';
+import { gameInputZoneMeta } from '../game/meta/gameInputZoneMeta';
+import { gameMeasurementProbeMeta } from '../game/meta/gameMeasurementProbeMeta';
+import { gameMeta } from '../game/meta/gameMeta';
+import { gameOverlayMeta } from '../game/meta/gameOverlayMeta';
 import { gradientMeta } from '../gradient/gradientMeta';
 import { heroMeta } from '../hero/heroMeta';
 import { iconMeta } from '../icon/iconMeta';
@@ -74,6 +81,13 @@ import {
   skeletonTextMeta,
 } from '../skeleton/skeletonMeta';
 import { surfaceMeta } from '../surface/surfaceMeta';
+import {
+  cardBackMeta,
+  cardHandMeta,
+  playingCardMeta,
+  pokerTrainingTableMeta,
+  tabletopTableMeta,
+} from '../tabletop/meta';
 import { tabListMeta } from '../tabs/tabListMeta';
 import { tabMeta } from '../tabs/tabMeta';
 import { tabPanelMeta } from '../tabs/tabPanelMeta';
@@ -119,6 +133,12 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   FormError: formErrorMeta,
   Field: fieldMeta,
   Gradient: gradientMeta,
+  Game: gameMeta,
+  GameField: gameFieldMeta,
+  GameEntity: gameEntityMeta,
+  GameInputZone: gameInputZoneMeta,
+  GameMeasurementProbe: gameMeasurementProbeMeta,
+  GameOverlay: gameOverlayMeta,
   Heading: headingMeta,
   Icon: iconMeta,
   IconButton: iconButtonMeta,
@@ -165,6 +185,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   SignInForm: signInFormMeta,
   SignUpForm: signUpFormMeta,
   ChatListItem: chatListItemMeta,
+  ChessBoard: chessBoardMeta,
   CollectionEditor: collectionEditorMeta,
   ContentRail: contentRailMeta,
   EmptyState: emptyStateMeta,
@@ -173,6 +194,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   ListItem: listItemMeta,
   ListSection: listSectionMeta,
   MessageBubble: messageBubbleMeta,
+  OpeningBook: openingBookMeta,
   MissingElement: missingElementMeta,
   PostCard: postCardMeta,
   ProductCard: productCardMeta,
@@ -185,6 +207,11 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   SelectionProvider: selectionProviderMeta,
   PaletteItem: paletteItemMeta,
   Timeline: timelineMeta,
+  CardBack: cardBackMeta,
+  CardHand: cardHandMeta,
+  PlayingCard: playingCardMeta,
+  TabletopTable: tabletopTableMeta,
+  PokerTrainingTable: pokerTrainingTableMeta,
   TreeItem: treeItemMeta,
   TreeView: treeViewMeta,
 });

package/src/features/authoring/constants.ts

@@ -42,6 +42,9 @@ export const FEATURE_MANIFEST_ELEMENTS = {
   'time-picker': ['TimePicker'],
   uploader: ['Uploader'],
   'bottom-sheet': ['BottomSheet'],
+  chess: ['ChessBoard', 'OpeningBook'],
+  game: ['Game', 'GameField', 'GameEntity', 'GameInputZone', 'GameMeasurementProbe', 'GameOverlay'],
+  tabletop: ['TabletopTable', 'PokerTrainingTable'],
 } as const;
 
 export const ZORA_THEME_TOKEN_FAMILIES = [

package/src/features/card/cardMeta.ts

@@ -1,12 +1,22 @@
 import type { ZoraComponentMeta } from '../authoring';
-import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
+import {
+  CHESS_ALLOWED_CHILDREN,
+  CONTAINER_ALLOWED_CHILDREN,
+  GAME_ALLOWED_CHILDREN,
+  TABLETOP_ALLOWED_CHILDREN,
+} from '../authoring/allowedChildren';
 import { COMPONENT_THEME_AUTHORING } from '../authoring/constants';
 
 export const cardMeta = {
   name: 'Card',
   category: 'component',
   directManifestNode: true,
-  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  allowedChildren: [
+    ...CONTAINER_ALLOWED_CHILDREN,
+    ...CHESS_ALLOWED_CHILDREN,
+    ...GAME_ALLOWED_CHILDREN,
+    ...TABLETOP_ALLOWED_CHILDREN,
+  ],
   blueprint: { label: 'Card', defaultProps: { title: 'Card' } },
   events: { press: { label: 'Press', eventType: 'card.press', payloadFields: [] } },
   props: {

package/src/features/chess/adapters/inbound/ChessBoard.tsx

@@ -0,0 +1,169 @@
+import React from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+import type { ChessBoardProps, ChessPieceState, ChessSquareId } from '../../../../types/chess';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { createBoardSquares } from '../../utils/createBoardSquares';
+import { createChessBoardColorScheme } from '../../utils/createChessBoardColorScheme';
+import { isLightSquare } from '../../utils/isLightSquare';
+
+const symbols = new Map<string, string>([
+  ['white:p', '♙'],
+  ['white:n', '♘'],
+  ['white:b', '♗'],
+  ['white:r', '♖'],
+  ['white:q', '♕'],
+  ['white:k', '♔'],
+  ['black:p', '♟'],
+  ['black:n', '♞'],
+  ['black:b', '♝'],
+  ['black:r', '♜'],
+  ['black:q', '♛'],
+  ['black:k', '♚'],
+]);
+
+/*** Renders caller-owned chess presentation state without chess rule execution. */
+export const ChessBoard = withZoraThemeScope(ChessBoardInner);
+
+/*** Renders the current presentation state without executing chess rules. */
+function ChessBoardInner({
+  pieces = [],
+  orientation = 'white',
+  selectedSquare = null,
+  legalTargets = [],
+  lastMove = null,
+  disabled = false,
+  showCoordinates = false,
+  colorScheme,
+  onSquarePress,
+  onMoveAttempt,
+  renderPiece,
+  interactionPolicy,
+  testID,
+}: ChessBoardProps) {
+  const { theme } = useZoraTheme();
+  const colors = createChessBoardColorScheme(theme, colorScheme);
+  const squares = createBoardSquares(orientation);
+  const piecesBySquare = new Map<ChessSquareId, ChessPieceState>(
+    pieces.map((piece) => [piece.square, piece]),
+  );
+  const legalTargetSet = new Set(legalTargets);
+  const pressSquare = (square: ChessSquareId) => {
+    if (disabled || interactionPolicy === 'passive') return;
+    onSquarePress?.(square);
+    if (selectedSquare !== null && selectedSquare !== square)
+      onMoveAttempt?.({ from: selectedSquare, to: square });
+  };
+  return (
+    <View
+      accessibilityLabel="Chess board"
+      style={[styles.board, { borderColor: colors.border, opacity: disabled ? 0.56 : 1 }]}
+      testID={testID}
+    >
+      {squares.map((square) => {
+        const piece = piecesBySquare.get(square);
+        const light = isLightSquare(square);
+        const isTarget = legalTargetSet.has(square);
+        const backgroundColor =
+          selectedSquare === square
+            ? colors.selectedSquare
+            : isTarget
+              ? colors.legalTarget
+              : lastMove?.from === square
+                ? colors.lastMoveFrom
+                : lastMove?.to === square
+                  ? colors.lastMoveTo
+                  : light
+                    ? colors.lightSquare
+                    : colors.darkSquare;
+        const pieceContent =
+          piece === undefined
+            ? null
+            : renderPiece
+              ? renderPiece({
+                  color: piece.color === 'white' ? colors.lightPiece : colors.darkPiece,
+                  piece: piece.piece,
+                  square,
+                })
+              : (symbols.get(`${piece.color}:${piece.piece.toLowerCase()}`) ?? piece.piece);
+        return (
+          <Pressable
+            accessibilityLabel={square}
+            accessibilityRole="button"
+            disabled={disabled || interactionPolicy === 'passive'}
+            key={square}
+            onPress={() => pressSquare(square)}
+            style={[styles.square, { backgroundColor }]}
+            testID={testID ? `${testID}-square-${square}` : undefined}
+          >
+            {showCoordinates ? (
+              <Text
+                style={[
+                  styles.coordinate,
+                  { color: light ? colors.lightSquareText : colors.darkSquareText },
+                ]}
+              >
+                {square}
+              </Text>
+            ) : null}
+            {piece === undefined ? null : (
+              <View pointerEvents="none" style={styles.pieceContainer}>
+                {renderPiece ? (
+                  pieceContent
+                ) : (
+                  <Text
+                    style={[
+                      styles.piece,
+                      { color: piece.color === 'white' ? colors.lightPiece : colors.darkPiece },
+                    ]}
+                  >
+                    {pieceContent}
+                  </Text>
+                )}
+              </View>
+            )}
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  board: {
+    aspectRatio: 1,
+    borderRadius: 12,
+    borderWidth: StyleSheet.hairlineWidth,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    overflow: 'hidden',
+    width: '100%',
+  },
+  coordinate: {
+    fontSize: 9,
+    fontWeight: '600',
+    left: 3,
+    opacity: 0.72,
+    position: 'absolute',
+    top: 2,
+    zIndex: 2,
+  },
+  piece: { fontSize: 32, fontWeight: '600', lineHeight: 38 },
+  pieceContainer: {
+    alignItems: 'center',
+    bottom: 0,
+    justifyContent: 'center',
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+  square: {
+    alignItems: 'center',
+    aspectRatio: 1,
+    width: '12.5%',
+    justifyContent: 'center',
+    position: 'relative',
+  },
+});

package/src/features/chess/adapters/inbound/OpeningBook.tsx

@@ -0,0 +1,131 @@
+import React from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+import type { OpeningBookMove, OpeningBookProps } from '../../../../types/chess';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { createOpeningBookColorScheme } from '../../utils/createOpeningBookColorScheme';
+
+/*** Renders caller-owned opening suggestions and their visual states. */
+export const OpeningBook = withZoraThemeScope(OpeningBookInner);
+
+/*** Formats an opening result percentage, accepting fractions or percentages. */
+function rate(label: string, value: number | undefined): string | undefined {
+  if (value === undefined || !Number.isFinite(value)) return undefined;
+  return `${label} ${Math.round(value <= 1 ? value * 100 : value)}%`;
+}
+
+/*** Resolves an opening move's stable row key. */
+function moveKey(move: OpeningBookMove): string {
+  return move.uci ?? move.fen ?? move.san;
+}
+
+/*** Renders the themed opening list without owning chess rules or data loading. */
+function OpeningBookInner({
+  moves = [],
+  title = 'Opening book',
+  loading = false,
+  errorText,
+  emptyText = 'No book moves for this position.',
+  selectedMove = null,
+  colorScheme,
+  onMovePress,
+  interactionPolicy,
+  testID,
+}: OpeningBookProps) {
+  const { theme } = useZoraTheme();
+  const colors = createOpeningBookColorScheme(theme, colorScheme);
+  const stateText = loading ? 'Loading opening moves…' : (errorText ?? emptyText);
+  const showState = loading || errorText !== undefined || moves.length === 0;
+  return (
+    <View
+      accessibilityLabel={title}
+      style={[
+        styles.root,
+        {
+          borderColor: colors.border,
+          backgroundColor: colors.surface,
+        },
+      ]}
+      testID={testID}
+    >
+      <Text style={[styles.title, { color: colors.titleText }]}>{title}</Text>
+      {!showState ? (
+        <View style={styles.moves}>
+          {moves.map((move) => {
+            const selected =
+              selectedMove !== null &&
+              (selectedMove === move.san || selectedMove === move.uci || selectedMove === move.fen);
+            const details = [
+              move.eco,
+              move.name,
+              move.games === undefined ? undefined : `${move.games} games`,
+            ].filter((part): part is string => typeof part === 'string' && part.length > 0);
+            const stats = [
+              rate('W', move.whiteWinRate),
+              rate('D', move.drawRate),
+              rate('B', move.blackWinRate),
+            ].filter((part): part is string => part !== undefined);
+            return (
+              <Pressable
+                accessibilityRole="button"
+                disabled={onMovePress === undefined || interactionPolicy === 'passive'}
+                key={moveKey(move)}
+                onPress={() => {
+                  if (interactionPolicy === 'passive') return;
+                  onMovePress?.(move);
+                }}
+                style={[
+                  styles.move,
+                  {
+                    backgroundColor: selected ? colors.selectedSurface : colors.surfaceHover,
+                    borderColor: colors.border,
+                  },
+                ]}
+                testID={testID ? `${testID}-move-${move.san}` : undefined}
+              >
+                <View style={styles.moveMain}>
+                  <Text style={[styles.san, { color: colors.primaryText }]}>{move.san}</Text>
+                  <Text style={[styles.meta, { color: colors.secondaryText }]}>
+                    {details.length > 0 ? details.join(' · ') : 'Book move'}
+                  </Text>
+                </View>
+                {stats.length > 0 ? (
+                  <View style={[styles.metric, { backgroundColor: colors.metricSurface }]}>
+                    <Text style={[styles.metricText, { color: colors.secondaryText }]}>
+                      {stats.join(' ')}
+                    </Text>
+                  </View>
+                ) : null}
+              </Pressable>
+            );
+          })}
+        </View>
+      ) : (
+        <Text style={[styles.stateText, { color: colors.secondaryText }]}>{stateText}</Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { borderRadius: 12, borderWidth: StyleSheet.hairlineWidth, gap: 10, padding: 12 },
+  title: { fontSize: 15, fontWeight: '700', lineHeight: 20 },
+  stateText: { fontSize: 13, lineHeight: 18 },
+  moves: { gap: 8 },
+  move: {
+    alignItems: 'center',
+    borderRadius: 10,
+    borderWidth: StyleSheet.hairlineWidth,
+    flexDirection: 'row',
+    gap: 10,
+    justifyContent: 'space-between',
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+  },
+  moveMain: { flex: 1, gap: 2 },
+  san: { fontSize: 16, fontWeight: '700', lineHeight: 20 },
+  meta: { fontSize: 12, lineHeight: 16 },
+  metric: { borderRadius: 999, paddingHorizontal: 8, paddingVertical: 4 },
+  metricText: { fontSize: 11, fontWeight: '600' },
+});