@ankhorage/zora 21.0.23 → 21.1.0

package/src/features/chess/meta.ts

@@ -0,0 +1,168 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+export const chessBoardMeta = {
+  name: 'ChessBoard',
+  category: 'component',
+  description:
+    'Renders caller-owned chess pieces, highlights, and move-attempt interactions without chess rules.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Chess board',
+    defaultProps: { pieces: [], orientation: 'white', showCoordinates: true },
+  },
+  events: {
+    squarePress: {
+      label: 'Square press',
+      eventType: 'chess.squarePress',
+      payloadFields: [{ path: 'square', type: 'string', label: 'Square' }],
+    },
+    moveAttempt: {
+      label: 'Move attempt',
+      eventType: 'chess.moveAttempt',
+      payloadFields: [
+        { path: 'from', type: 'string', label: 'From' },
+        { path: 'to', type: 'string', label: 'To' },
+      ],
+    },
+  },
+  bindings: {
+    props: {
+      pieces: {
+        label: 'Pieces',
+        value: { type: 'array', itemType: 'object' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+      legalTargets: {
+        label: 'Legal targets',
+        value: { type: 'array', itemType: 'string' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+  },
+  props: {
+    pieces: {
+      type: 'array',
+      category: 'Board',
+      label: 'Pieces',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    orientation: {
+      type: 'enum',
+      category: 'Board',
+      label: 'Orientation',
+      enum: ['white', 'black'],
+      default: 'white',
+      authoring: { authority: 'instance' },
+    },
+    selectedSquare: {
+      type: 'string',
+      category: 'Board',
+      label: 'Selected square',
+      authoring: { authority: 'instance' },
+    },
+    legalTargets: {
+      type: 'array',
+      category: 'Board',
+      label: 'Legal targets',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    showCoordinates: {
+      type: 'boolean',
+      category: 'Style',
+      label: 'Show coordinates',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;
+export const openingBookMeta = {
+  name: 'OpeningBook',
+  category: 'component',
+  description:
+    'Presents caller-owned opening suggestions and their loading, empty, selected, and press states.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Opening book',
+    defaultProps: {
+      moves: [],
+      title: 'Opening book',
+      emptyText: 'No book moves for this position.',
+    },
+  },
+  events: {
+    movePress: {
+      label: 'Move press',
+      eventType: 'chess.openingMovePress',
+      payloadFields: [
+        { path: 'san', type: 'string', label: 'SAN' },
+        { path: 'uci', type: 'string', label: 'UCI' },
+        { path: 'fen', type: 'string', label: 'Position' },
+      ],
+    },
+  },
+  bindings: {
+    props: {
+      moves: {
+        label: 'Moves',
+        value: { type: 'array', itemType: 'object' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+  },
+  props: {
+    moves: {
+      type: 'array',
+      category: 'Content',
+      label: 'Moves',
+      default: [],
+      authoring: { authority: 'instance' },
+    },
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Opening book',
+      authoring: { authority: 'instance' },
+    },
+    emptyText: {
+      type: 'string',
+      category: 'Content',
+      label: 'Empty text',
+      default: 'No book moves for this position.',
+      authoring: { authority: 'instance' },
+    },
+    loading: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Loading',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    errorText: {
+      type: 'string',
+      category: 'State',
+      label: 'Error text',
+      authoring: { authority: 'instance' },
+    },
+    selectedMove: {
+      type: 'string',
+      category: 'State',
+      label: 'Selected move',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/chess/public.test.tsx

@@ -0,0 +1,165 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import type {
+  ChessBoard as ChessBoardComponent,
+  OpeningBook as OpeningBookComponent,
+} from './public';
+import { createBoardSquares } from './utils/createBoardSquares';
+import { createChessBoardColorScheme } from './utils/createChessBoardColorScheme';
+import { getSquareFile } from './utils/getSquareFile';
+import { getSquareRank } from './utils/getSquareRank';
+import { isLightSquare } from './utils/isLightSquare';
+
+const webDistRoot = join(import.meta.dir, '../../../web-dist');
+const load = (path: string) => import(pathToFileURL(join(webDistRoot, path)).href);
+
+describe('Chess presentation', () => {
+  test('keeps square order and theme-derived presentation independent of chess rules', () => {
+    expect(createBoardSquares('white').at(0)).toBe('a8');
+    expect(createBoardSquares('black').at(0)).toBe('h1');
+    expect(getSquareFile('e4')).toBe('e');
+    expect(getSquareRank('e4')).toBe('4');
+    expect(isLightSquare('a1')).toBe(false);
+    expect(typeof createChessBoardColorScheme).toBe('function');
+  });
+
+  test('renders custom React nodes, square IDs, and opening metadata through independent artifacts', async () => {
+    const { ChessBoard } = (await load('components/chess-board/index.js')) as {
+      ChessBoard: typeof ChessBoardComponent;
+    };
+    const { OpeningBook } = (await load('components/opening-book/index.js')) as {
+      OpeningBook: typeof OpeningBookComponent;
+    };
+    const markup = renderToStaticMarkup(
+      <>
+        <ChessBoard
+          colorScheme={{ selectedSquare: '#123456', legalTarget: '#234567' }}
+          legalTargets={['e4']}
+          pieces={[{ color: 'white', piece: 'p', square: 'e2' }]}
+          renderPiece={() => <div data-testid="custom-piece" />}
+          selectedSquare="e2"
+          showCoordinates
+          testID="board"
+        />
+        <OpeningBook
+          moves={[
+            {
+              san: 'Nf3',
+              eco: 'A04',
+              name: 'Reti Opening',
+              games: 42,
+              whiteWinRate: 0.52,
+              drawRate: 0.2,
+              blackWinRate: 0.28,
+            },
+          ]}
+          testID="book"
+        />
+      </>,
+    );
+    const browser = new Window();
+    browser.document.body.innerHTML = markup;
+    expect(browser.document.querySelectorAll('[data-testid^="board-square-"]')).toHaveLength(64);
+    expect(
+      browser.document.querySelector('[data-testid="board-square-e2"]')?.textContent,
+    ).toContain('e2');
+    expect(
+      browser.document.querySelector('[data-testid="custom-piece"]')?.parentElement?.className,
+    ).toContain('css-view');
+    expect(
+      browser.document.querySelector('[data-testid="board-square-e2"]')?.getAttribute('style'),
+    ).toContain('background-color:rgba(18,52,86,1.00)');
+    expect(
+      browser.document.querySelector('[data-testid="board-square-e4"]')?.getAttribute('style'),
+    ).toContain('background-color:rgba(35,69,103,1.00)');
+    expect(browser.document.querySelector('[data-testid="book-move-Nf3"]')?.textContent).toContain(
+      'A04 · Reti Opening · 42 games',
+    );
+    expect(browser.document.querySelector('[data-testid="book-move-Nf3"]')?.textContent).toContain(
+      'W 52% D 20% B 28%',
+    );
+    browser.close();
+  });
+
+  test('emits only caller-owned intents in active mode and suppresses them in passive mode', async () => {
+    const { ChessBoard } = (await load('components/chess-board/index.js')) as {
+      ChessBoard: typeof ChessBoardComponent;
+    };
+    const { OpeningBook } = (await load('components/opening-book/index.js')) as {
+      OpeningBook: typeof OpeningBookComponent;
+    };
+    const browser = new Window();
+    const keys = ['window', 'document', 'Node', 'navigator', 'IS_REACT_ACT_ENVIRONMENT'] as const;
+    const previous = keys.map(
+      (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+    );
+    Object.assign(globalThis, {
+      window: browser,
+      document: browser.document,
+      Node: browser.Node,
+      navigator: browser.navigator,
+      IS_REACT_ACT_ENVIRONMENT: true,
+    });
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const squares: string[] = [];
+    const moves: string[] = [];
+    const book: string[] = [];
+    const root = createRoot(host);
+    const render = (interactionPolicy: 'active' | 'passive') => (
+      <>
+        <ChessBoard
+          interactionPolicy={interactionPolicy}
+          selectedSquare="e2"
+          testID="board"
+          onSquarePress={(square) => squares.push(square)}
+          onMoveAttempt={(move) => moves.push(`${move.from}-${move.to}`)}
+        />
+        <OpeningBook
+          interactionPolicy={interactionPolicy}
+          moves={[{ san: 'e4' }]}
+          onMovePress={(move) => book.push(move.san)}
+          testID="book"
+        />
+      </>
+    );
+    try {
+      act(() => root.render(render('passive')));
+      act(() => {
+        host
+          .querySelector('[data-testid="board-square-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+        host
+          .querySelector('[data-testid="book-move-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+      });
+      expect([squares, moves, book]).toEqual([[], [], []]);
+      act(() => root.render(render('active')));
+      act(() => {
+        host
+          .querySelector('[data-testid="board-square-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+        host
+          .querySelector('[data-testid="book-move-e4"]')
+          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+      });
+      expect(squares).toEqual(['e4']);
+      expect(moves).toEqual(['e2-e4']);
+      expect(book).toEqual(['e4']);
+    } finally {
+      act(() => root.unmount());
+      browser.close();
+      for (const [key, descriptor] of previous) {
+        if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+        else Reflect.deleteProperty(globalThis, key);
+      }
+    }
+  });
+});

package/src/features/chess/public.ts

@@ -0,0 +1,27 @@
+export type {
+  ChessBoardColorOverrides,
+  ChessBoardColorScheme,
+  ChessBoardOrientation,
+  ChessBoardProps,
+  ChessMoveAttempt,
+  ChessPieceCode,
+  ChessPieceRenderContext,
+  ChessPieceRenderer,
+  ChessPieceState,
+  ChessPromotionPiece,
+  ChessSquareId,
+  OpeningBookColorOverrides,
+  OpeningBookColorScheme,
+  OpeningBookMove,
+  OpeningBookProps,
+} from '../../types/chess';
+export { ChessBoard } from './adapters/inbound/ChessBoard';
+export { OpeningBook } from './adapters/inbound/OpeningBook';
+export { chessSquares } from './utils/chessSquares';
+export { createBoardSquares } from './utils/createBoardSquares';
+export type { ChessColorThemeShape } from './utils/createChessBoardColorScheme';
+export { createChessBoardColorScheme } from './utils/createChessBoardColorScheme';
+export { createOpeningBookColorScheme } from './utils/createOpeningBookColorScheme';
+export { getSquareFile } from './utils/getSquareFile';
+export { getSquareRank } from './utils/getSquareRank';
+export { isLightSquare } from './utils/isLightSquare';

package/src/features/chess/utils/chessSquares.ts

@@ -0,0 +1,6 @@
+import type { ChessSquareId } from '../../../types/chess';
+
+/*** Lists every board square in ascending rank and file order. */
+export const chessSquares: readonly ChessSquareId[] = [1, 2, 3, 4, 5, 6, 7, 8].flatMap((rank) =>
+  [...'abcdefgh'].map((file) => `${file}${rank}` as ChessSquareId),
+);

package/src/features/chess/utils/createBoardSquares.ts

@@ -0,0 +1,13 @@
+import type { ChessBoardOrientation, ChessSquareId } from '../../../types/chess';
+
+const files = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'] as const;
+const ranks = ['1', '2', '3', '4', '5', '6', '7', '8'] as const;
+
+/*** Orders the 64 displayed squares for the selected player orientation. */
+export function createBoardSquares(orientation: ChessBoardOrientation): readonly ChessSquareId[] {
+  const displayedRanks = orientation === 'white' ? [...ranks].reverse() : [...ranks];
+  const displayedFiles = orientation === 'white' ? [...files] : [...files].reverse();
+  return displayedRanks.flatMap((rank) =>
+    displayedFiles.map((file): ChessSquareId => `${file}${rank}`),
+  );
+}

package/src/features/chess/utils/createChessBoardColorScheme.ts

@@ -0,0 +1,55 @@
+import type { ChessBoardColorOverrides, ChessBoardColorScheme } from '../../../types/chess';
+
+export interface ChessColorThemeShape {
+  semantics: {
+    action: {
+      primary: {
+        softBg: string;
+      };
+    };
+    content: {
+      default: string;
+      muted: string;
+    };
+    neutral: {
+      divider: string;
+      surface: string;
+      surfaceHover: string;
+    };
+    success: {
+      softBg: string;
+    };
+    warning: {
+      softBg: string;
+    };
+  };
+}
+
+/***
+ * Creates the theme-derived palette used by `ChessBoard`.
+ *
+ * Use `createChessBoardColorScheme` when custom board overlays, piece renderers,
+ * or adjacent chess UI need to share the same square, highlight, coordinate, and
+ * piece colors as the built-in board.
+ *
+ */
+export function createChessBoardColorScheme(
+  theme: ChessColorThemeShape,
+  overrides?: ChessBoardColorOverrides,
+): ChessBoardColorScheme {
+  return {
+    border: theme.semantics.neutral.divider,
+    coordinateText: theme.semantics.content.muted,
+    darkPiece: theme.semantics.content.default,
+    darkSquare: theme.semantics.neutral.surfaceHover,
+    darkSquareText: theme.semantics.content.muted,
+    lastMoveFrom: theme.semantics.warning.softBg,
+    lastMoveTo: theme.semantics.warning.softBg,
+    legalTarget: theme.semantics.success.softBg,
+    lightPiece: theme.semantics.content.default,
+    lightSquare: theme.semantics.neutral.surface,
+    lightSquareText: theme.semantics.content.muted,
+    selectedSquare: theme.semantics.action.primary.softBg,
+    ...overrides,
+  };
+}

package/src/features/chess/utils/createOpeningBookColorScheme.ts

@@ -0,0 +1,26 @@
+import type { OpeningBookColorOverrides, OpeningBookColorScheme } from '../../../types/chess';
+import type { ChessColorThemeShape } from './createChessBoardColorScheme';
+
+/***
+ * Creates the theme-derived palette used by `OpeningBook`.
+ *
+ * Use `createOpeningBookColorScheme` when custom opening-list rows, badges, or
+ * trainer panels should match the built-in book surface and selected-move states.
+ *
+ */
+export function createOpeningBookColorScheme(
+  theme: ChessColorThemeShape,
+  overrides?: OpeningBookColorOverrides,
+): OpeningBookColorScheme {
+  return {
+    border: theme.semantics.neutral.divider,
+    metricSurface: theme.semantics.neutral.surface,
+    primaryText: theme.semantics.content.default,
+    secondaryText: theme.semantics.content.muted,
+    selectedSurface: theme.semantics.action.primary.softBg,
+    surface: theme.semantics.neutral.surface,
+    surfaceHover: theme.semantics.neutral.surfaceHover,
+    titleText: theme.semantics.content.default,
+    ...overrides,
+  };
+}

package/src/features/chess/utils/getSquareFile.ts

@@ -0,0 +1,6 @@
+import type { ChessSquareId } from '../../../types/chess';
+
+/*** Returns the file letter of a chess square. */
+export function getSquareFile(square: ChessSquareId): string {
+  return square[0] ?? '';
+}

package/src/features/chess/utils/getSquareRank.ts

@@ -0,0 +1,6 @@
+import type { ChessSquareId } from '../../../types/chess';
+
+/*** Returns the rank number of a chess square. */
+export function getSquareRank(square: ChessSquareId): string {
+  return square[1] ?? '';
+}

package/src/features/chess/utils/isLightSquare.ts

@@ -0,0 +1,8 @@
+import type { ChessSquareId } from '../../../types/chess';
+
+const files = 'abcdefgh';
+
+/*** Determines whether a chess square uses the light presentation color. */
+export function isLightSquare(square: ChessSquareId): boolean {
+  return (files.indexOf(square[0] ?? '') + Number(square[1]) - 1) % 2 === 1;
+}

package/src/features/chessTabletopOwnership.test.ts

@@ -0,0 +1,71 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { extname, join, parse } from 'node:path';
+
+import { expect, test } from 'bun:test';
+import * as ts from 'typescript';
+
+const featureRoots = ['src/features/chess', 'src/features/tabletop'] as const;
+
+test('Chess and Tabletop implementation modules own one matching runtime export each', () => {
+  for (const featureRoot of featureRoots) {
+    for (const directory of [join(featureRoot, 'adapters/inbound'), join(featureRoot, 'utils')]) {
+      for (const name of readdirSync(directory)) {
+        if (!['.ts', '.tsx'].includes(extname(name))) continue;
+        const source = ts.createSourceFile(
+          name,
+          readFileSync(join(directory, name), 'utf8'),
+          ts.ScriptTarget.Latest,
+          true,
+        );
+        const runtimeExports = source.statements.flatMap((statement) => {
+          if (
+            !ts.canHaveModifiers(statement) ||
+            !ts
+              .getModifiers(statement)
+              ?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+          )
+            return [];
+          if (ts.isFunctionDeclaration(statement) && statement.name) return [statement.name.text];
+          if (ts.isVariableStatement(statement))
+            return statement.declarationList.declarations.map((declaration) =>
+              declaration.name.getText(source),
+            );
+          return [];
+        });
+        expect(runtimeExports, join(directory, name)).toEqual([parse(name).name]);
+      }
+    }
+  }
+});
+
+test('Chess and Tabletop source graphs contain no standalone package or game-service imports', () => {
+  const sourcePaths = featureRoots.flatMap((featureRoot) => {
+    const visit = (directory: string): string[] =>
+      readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) return visit(path);
+        return /\.(?:ts|tsx)$/.test(entry.name) && !entry.name.includes('.test.') ? [path] : [];
+      });
+    return visit(featureRoot);
+  });
+  for (const path of sourcePaths) {
+    const source = ts.createSourceFile(
+      path,
+      readFileSync(path, 'utf8'),
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    const imports = source.statements
+      .filter(ts.isImportDeclaration)
+      .map((statement) => statement.moduleSpecifier)
+      .filter(ts.isStringLiteral)
+      .map((literal) => literal.text);
+    for (const specifier of imports) {
+      if (specifier.startsWith('.')) continue;
+      expect(
+        ['react', 'react-native', '@ankhorage/color-theory'],
+        `${path}: ${specifier}`,
+      ).toContain(specifier);
+    }
+  }
+});

package/src/features/game/adapters/inbound/Game.tsx

@@ -0,0 +1,43 @@
+import { RuntimeRendererConfigProvider } from '@ankhorage/runtime';
+import React from 'react';
+
+import type { GameProps } from '../../../../types/gamePresentation';
+import { createGameBindingContext } from '../../composition/createGameBindingContext';
+import { createGameMeasurementRegistry } from '../../composition/createGameMeasurementRegistry';
+import { GameRuntimeContext } from '../../composition/GameRuntimeContext';
+import { useGameRuntime } from '../../composition/useGameRuntime';
+import { GameField } from './GameField';
+
+/*** Bind one serializable game definition to a local transient session and presentation field. */
+export function Game(props: GameProps) {
+  const runtime = useGameRuntime(props);
+  const [measurementRegistry] = React.useState(createGameMeasurementRegistry);
+  const runtimeContext = React.useMemo(
+    () => ({ ...runtime, ...measurementRegistry, interactionPolicy: props.interactionPolicy }),
+    [measurementRegistry, props.interactionPolicy, runtime],
+  );
+  const runtimeBindingConfig = React.useMemo(
+    () => ({ bindingContext: createGameBindingContext(runtime.session) }),
+    [runtime.session],
+  );
+
+  return (
+    <GameRuntimeContext.Provider value={runtimeContext}>
+      <RuntimeRendererConfigProvider value={runtimeBindingConfig}>
+        <GameField
+          {...(props.aspectRatio === undefined ? {} : { aspectRatio: props.aspectRatio })}
+          {...(props.minHeight === undefined ? {} : { minHeight: props.minHeight })}
+          {...(props.fill === undefined ? {} : { fill: props.fill })}
+          {...(props.clip === undefined ? {} : { clip: props.clip })}
+          {...(props.accessibilityLabel === undefined
+            ? {}
+            : { accessibilityLabel: props.accessibilityLabel })}
+          {...(props.testID === undefined ? {} : { testID: props.testID })}
+          interactionPolicy={props.interactionPolicy}
+        >
+          {props.children}
+        </GameField>
+      </RuntimeRendererConfigProvider>
+    </GameRuntimeContext.Provider>
+  );
+}

package/src/features/game/adapters/inbound/GameEntity.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { Animated, StyleSheet, type View, type ViewStyle } from 'react-native';
+
+import type { GameEntityProps } from '../../../../types/gamePresentation';
+import { useGameEntityAnimatedStyle } from '../../utils/useGameEntityAnimatedStyle';
+import { useGameEntityMeasurement } from '../../utils/useGameEntityMeasurement';
+
+/*** Render one generic positioned game entity without owning gameplay semantics. */
+export function GameEntity(props: GameEntityProps) {
+  const elementRef = React.useRef<View | null>(null);
+  const animatedStyle = useGameEntityAnimatedStyle(props);
+  useGameEntityMeasurement(elementRef, props.measurementId);
+
+  return (
+    <Animated.View
+      ref={elementRef}
+      accessibilityLabel={props.accessibilityLabel}
+      testID={props.testID}
+      pointerEvents={
+        props.interactionPolicy === 'passive' ? 'none' : (props.pointerEvents ?? 'auto')
+      }
+      style={[styles.root, createEntityStaticStyle(props), animatedStyle]}
+    >
+      {props.children}
+    </Animated.View>
+  );
+}
+
+/*** Convert non-animated GameEntity presentation props into a React Native view style. */
+function createEntityStaticStyle(props: GameEntityProps): ViewStyle {
+  return {
+    display: props.hidden === true ? 'none' : 'flex',
+    position: 'absolute',
+    zIndex: props.zIndex ?? 0,
+    ...(props.height === undefined ? {} : { height: props.height }),
+    ...(props.width === undefined ? {} : { width: props.width }),
+  };
+}
+
+const styles = StyleSheet.create({
+  root: {
+    position: 'absolute',
+  },
+});