@ankhorage/zora 25.11.1 → 26.0.0

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

@@ -1,248 +1,97 @@
-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 { chessBoardMeta } from './meta';
-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);
+import { createChessBoardCellPressHandler } from './utils/createChessBoardCellPressHandler';
+import { createChessBoardCells } from './utils/createChessBoardCells';
 
 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('preserves FEN and validated-move authoring metadata', () => {
-    expect(chessBoardMeta.props.fen.type).toBe('string');
-    expect(chessBoardMeta.props.validateMoves.default).toBe(true);
-    expect(chessBoardMeta.events.legalMove.payloadFields.map((field) => field.path)).toEqual([
-      'from',
-      'to',
-      'fen',
-      'san',
-      'lan',
-      'promotion',
-    ]);
-    expect(chessBoardMeta.events.invalidMove.payloadFields.map((field) => field.path)).toEqual([
-      'from',
-      'to',
-      'promotion',
+  test('declares caller-owned dimensions, cells, and move intents without rule-engine events', () => {
+    expect(chessBoardMeta.blueprint.defaultProps).toMatchObject({ columns: 8, rows: 8 });
+    expect(chessBoardMeta.props.columns.default).toBe(8);
+    expect(chessBoardMeta.props.rows.default).toBe(8);
+    expect(chessBoardMeta.events.cellPress.payloadFields).toEqual([
+      { path: 'column', type: 'number', label: 'Column' },
+      { path: 'row', type: 'number', label: 'Row' },
     ]);
+    expect(chessBoardMeta.events).not.toHaveProperty('legalMove');
+    expect(chessBoardMeta.events).not.toHaveProperty('invalidMove');
   });
 
-  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('uses the shared GridView presentation boundary rather than a chess rules engine', async () => {
+    const source = await Bun.file('src/features/chess/adapters/inbound/ChessBoard.tsx').text();
+
+    expect(source).toContain("import { GridView } from '../../../grid-view/public';");
+    expect(source).not.toContain('chess.js');
+    expect(source).not.toContain('fen');
   });
 
-  test('preserves FEN-backed pieces, legal targets, and legal/invalid move callbacks', async () => {
-    const { ChessBoard } = (await load('components/chess-board/index.js')) as {
-      ChessBoard: typeof ChessBoardComponent;
-    };
-    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,
+  test('maps non-square boards into opposite GridView coordinates for white and black orientation', () => {
+    const white = createChessBoardCells(3, 2, 'white');
+    const black = createChessBoardCells(3, 2, 'black');
+
+    expect(white.find((cell) => cell.column === 1 && cell.row === 2)).toMatchObject({
+      x: 0,
+      y: 0,
+    });
+    expect(white.find((cell) => cell.column === 3 && cell.row === 1)).toMatchObject({
+      x: 2,
+      y: 1,
     });
-    const host = document.createElement('div');
-    document.body.appendChild(host);
-    const legal: string[] = [];
-    const invalid: string[] = [];
-    const root = createRoot(host);
+    expect(black.find((cell) => cell.column === 3 && cell.row === 1)).toMatchObject({
+      x: 0,
+      y: 0,
+    });
+    expect(black.find((cell) => cell.column === 1 && cell.row === 2)).toMatchObject({
+      x: 2,
+      y: 1,
+    });
+  });
 
-    try {
-      act(() =>
-        root.render(
-          <ChessBoard
-            fen="rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
-            onInvalidMove={(move) => invalid.push(`${move.from}-${move.to}`)}
-            onLegalMove={(move) => legal.push(`${move.lan}:${move.san}`)}
-            selectedSquare="e2"
-            showCoordinates
-            testID="fen-board"
-          />,
-        ),
-      );
+  test('accepts only the documented 2 through 24 presentation dimensions', () => {
+    expect(createChessBoardCells(2, 24, 'white')).toHaveLength(48);
+    expect(() => createChessBoardCells(1, 8, 'white')).toThrow(RangeError);
+    expect(() => createChessBoardCells(8, 25, 'black')).toThrow(RangeError);
+    expect(() => createChessBoardCells(2.5, 8, 'white')).toThrow(RangeError);
+  });
 
-      expect(host.querySelector('[data-testid="fen-board-square-e1"]')?.textContent).toContain('♔');
-      expect(
-        host.querySelector('[data-testid="fen-board-square-e4"]')?.getAttribute('style'),
-      ).toContain('background-color');
+  test('emits caller-owned press and move intents without acting in passive mode', () => {
+    const presses: unknown[] = [];
+    const attempts: unknown[] = [];
+    const active = createChessBoardCellPressHandler({
+      onCellPress: (cell) => presses.push(cell),
+      onMoveAttempt: (attempt) => attempts.push(attempt),
+      selectedCell: { column: 2, row: 2 },
+    });
 
-      act(() => {
-        host
-          .querySelector('[data-testid="fen-board-square-e4"]')
-          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
-      });
-      expect(legal).toEqual(['e2e4:e4']);
+    active({ column: 3, row: 4 });
+    createChessBoardCellPressHandler({
+      interactionPolicy: 'passive',
+      onCellPress: (cell) => presses.push(cell),
+      onMoveAttempt: (attempt) => attempts.push(attempt),
+      selectedCell: { column: 2, row: 2 },
+    })({ column: 4, row: 4 });
 
-      act(() => {
-        host
-          .querySelector('[data-testid="fen-board-square-e5"]')
-          ?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
-      });
-      expect(invalid).toEqual(['e2-e5']);
-    } finally {
-      act(() => root.unmount());
-      browser.close();
-      for (const [key, descriptor] of previous) {
-        if (descriptor) Object.defineProperty(globalThis, key, descriptor);
-        else Reflect.deleteProperty(globalThis, key);
-      }
-    }
+    expect(presses).toEqual([{ column: 3, row: 4 }]);
+    expect(attempts).toEqual([{ from: { column: 2, row: 2 }, to: { column: 3, row: 4 } }]);
   });
 
-  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,
+  test('describes selected cells and legal targets as cell objects in manifest metadata', () => {
+    expect(chessBoardMeta.props.selectedCell).toMatchObject({
+      type: 'object',
+      itemSchema: [{ key: 'column' }, { key: 'row' }],
+    });
+    expect(chessBoardMeta.props.legalTargets).toMatchObject({
+      type: 'array',
+      itemSchema: [{ key: 'column' }, { key: 'row' }],
+    });
+    expect(chessBoardMeta.bindings.props.selectedCell.value).toMatchObject({
+      type: 'object',
+      fields: [{ path: 'column' }, { path: 'row' }],
+    });
+    expect(chessBoardMeta.bindings.props.legalTargets.value).toMatchObject({
+      type: 'array',
+      itemType: 'object',
+      fields: [{ path: '[].column' }, { path: '[].row' }],
     });
-    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

@@ -1,16 +1,15 @@
 export type {
+  ChessBoardCell,
   ChessBoardColorOverrides,
   ChessBoardColorScheme,
+  ChessBoardDimensions,
   ChessBoardOrientation,
   ChessBoardProps,
   ChessMoveAttempt,
-  ChessMoveResult,
   ChessPieceCode,
   ChessPieceRenderContext,
   ChessPieceRenderer,
   ChessPieceState,
-  ChessPromotionPiece,
-  ChessSquareId,
   OpeningBookColorOverrides,
   OpeningBookColorScheme,
   OpeningBookMove,
@@ -19,12 +18,6 @@ export type {
 export { ChessBoard } from './adapters/inbound/ChessBoard';
 export { OpeningBook } from './adapters/inbound/OpeningBook';
 export { chessBoardMeta, openingBookMeta } from './meta';
-export { getLegalTargets, readChessPieces, tryMove } from './utils/chessEngine';
-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/createChessBoardCellPressHandler.ts

@@ -0,0 +1,30 @@
+import type { ChessBoardCell, ChessBoardProps } from '../../../types/chess';
+
+type ChessBoardCellPressHandlerOptions = Pick<
+  ChessBoardProps,
+  'disabled' | 'interactionPolicy' | 'onCellPress' | 'onMoveAttempt' | 'selectedCell'
+>;
+
+/*** Creates the caller-owned cell and move intent boundary for an interactive chess presentation. */
+export function createChessBoardCellPressHandler({
+  disabled,
+  interactionPolicy,
+  onCellPress,
+  onMoveAttempt,
+  selectedCell,
+}: ChessBoardCellPressHandlerOptions): (cell: ChessBoardCell) => void {
+  return (cell) => {
+    if (disabled || interactionPolicy === 'passive') return;
+
+    onCellPress?.(cell);
+    if (selectedCell === null || selectedCell === undefined || cellsEqual(selectedCell, cell)) {
+      return;
+    }
+    onMoveAttempt?.({ from: selectedCell, to: cell });
+  };
+}
+
+/*** Compares caller-owned coordinates without adding chess-rule semantics. */
+function cellsEqual(left: ChessBoardCell, right: ChessBoardCell): boolean {
+  return left.column === right.column && left.row === right.row;
+}

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

@@ -0,0 +1,54 @@
+import type { ChessBoardCell, ChessBoardOrientation } from '../../../types/chess';
+
+const minimumDimension = 2;
+const maximumDimension = 24;
+
+type ChessBoardGridCell = ChessBoardCell & {
+  readonly height: 1;
+  readonly id: string;
+  readonly width: 1;
+  readonly x: number;
+  readonly y: number;
+};
+
+/*** Creates bounded GridView cells whose coordinates represent the requested chess orientation. */
+export function createChessBoardCells(
+  columns: number,
+  rows: number,
+  orientation: ChessBoardOrientation,
+): readonly ChessBoardGridCell[] {
+  validateChessBoardDimensions(columns, rows);
+
+  return Array.from({ length: rows }, (_, rowIndex) =>
+    Array.from({ length: columns }, (_, columnIndex) => {
+      const column = columnIndex + 1;
+      const row = rowIndex + 1;
+
+      return {
+        column,
+        height: 1 as const,
+        id: `${column}:${row}`,
+        row,
+        width: 1 as const,
+        x: orientation === 'white' ? columnIndex : columns - column,
+        y: orientation === 'white' ? rows - row : rowIndex,
+      };
+    }),
+  ).flat();
+}
+
+/*** Rejects dimensions outside the presentation contract before GridView receives them. */
+function validateChessBoardDimensions(columns: number, rows: number): void {
+  if (
+    ![columns, rows].every(
+      (dimension) =>
+        Number.isInteger(dimension) &&
+        dimension >= minimumDimension &&
+        dimension <= maximumDimension,
+    )
+  ) {
+    throw new RangeError(
+      `ChessBoard dimensions must be whole numbers from ${minimumDimension} through ${maximumDimension}.`,
+    );
+  }
+}

package/src/features/chessTabletopOwnership.test.ts

@@ -32,17 +32,13 @@ test('Chess and Tabletop implementation modules own one matching runtime export
             );
           return [];
         });
-        const expectedExports =
-          name === 'chessEngine.ts'
-            ? ['getLegalTargets', 'readChessPieces', 'tryMove']
-            : [parse(name).name];
-        expect(runtimeExports.sort(), join(directory, name)).toEqual(expectedExports.sort());
+        expect(runtimeExports.sort(), join(directory, name)).toEqual([parse(name).name]);
       }
     }
   }
 });
 
-test('Chess and Tabletop source graphs depend only on their intentional runtime owners', () => {
+test('Chess and Tabletop source graphs depend only on their intentional presentation owners', () => {
   const sourcePaths = featureRoots.flatMap((featureRoot) => {
     const visit = (directory: string): string[] =>
       readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
@@ -67,7 +63,7 @@ test('Chess and Tabletop source graphs depend only on their intentional runtime
     for (const specifier of imports) {
       if (specifier.startsWith('.')) continue;
       expect(
-        ['react', 'react-native', 'chess.js', '@ankhorage/color-theory'],
+        ['react', 'react-native', '@ankhorage/color-theory'],
         `${path}: ${specifier}`,
       ).toContain(specifier);
     }

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

@@ -382,7 +382,18 @@ describe('ZORA_COMPONENT_META invariants', () => {
     });
     expect(ZORA_COMPONENT_META.ChessBoard.bindings?.props?.legalTargets?.value).toEqual({
       type: 'array',
-      itemType: 'string',
+      itemType: 'object',
+      fields: [
+        { path: '[].column', type: 'number', label: 'Column' },
+        { path: '[].row', type: 'number', label: 'Row' },
+      ],
+    });
+    expect(ZORA_COMPONENT_META.ChessBoard.bindings?.props?.selectedCell?.value).toEqual({
+      type: 'object',
+      fields: [
+        { path: 'column', type: 'number', label: 'Column' },
+        { path: 'row', type: 'number', label: 'Row' },
+      ],
     });
     expect(ZORA_COMPONENT_META.OpeningBook.bindings?.props?.moves?.value).toEqual({
       type: 'array',

package/src/readerFree.ts

@@ -119,18 +119,17 @@ export type {
 } from './features/chat/public';
 export { ChatListItem, MessageBubble } from './features/chat/public';
 export type {
+  ChessBoardCell,
   ChessBoardColorOverrides,
   ChessBoardColorScheme,
+  ChessBoardDimensions,
   ChessBoardOrientation,
   ChessBoardProps,
   ChessMoveAttempt,
-  ChessMoveResult,
   ChessPieceCode,
   ChessPieceRenderContext,
   ChessPieceRenderer,
   ChessPieceState,
-  ChessPromotionPiece,
-  ChessSquareId,
   OpeningBookColorOverrides,
   OpeningBookColorScheme,
   OpeningBookMove,
@@ -138,18 +137,7 @@ export type {
 } from './features/chess/public';
 export type { ChessColorThemeShape } from './features/chess/public';
 export { ChessBoard, chessBoardMeta, OpeningBook, openingBookMeta } from './features/chess/public';
-export {
-  chessSquares,
-  createBoardSquares,
-  createChessBoardColorScheme,
-  createOpeningBookColorScheme,
-  getLegalTargets,
-  getSquareFile,
-  getSquareRank,
-  isLightSquare,
-  readChessPieces,
-  tryMove,
-} from './features/chess/public';
+export { createChessBoardColorScheme, createOpeningBookColorScheme } from './features/chess/public';
 export type { ChipProps } from './features/chip/public';
 export type { ChipGroupItem, ChipGroupProps } from './features/chip/public';
 export { Chip } from './features/chip/public';

package/src/types/authoring.ts

@@ -8,7 +8,8 @@ import type {
 
 export type ZoraComponentCategory = 'foundation' | 'component' | 'pattern' | 'layout';
 
-export type ZoraComponentPropType = UiComponentPropType;
+/** ZORA authoring additionally describes serializable object-shaped values. */
+export type ZoraComponentPropType = UiComponentPropType | 'object';
 
 export type ZoraComponentPropValue =
   | string

package/src/types/chess.ts

@@ -4,33 +4,36 @@ import type { ZoraBaseProps } from './base';
 
 export type ChessBoardOrientation = 'white' | 'black';
 export type ChessPieceCode = string;
-export type ChessSquareId =
-  `${'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h'}${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}`;
-export type ChessPromotionPiece = 'q' | 'r' | 'b' | 'n';
 
-export interface ChessMoveAttempt {
-  readonly from: ChessSquareId;
-  readonly to: ChessSquareId;
-  readonly promotion?: ChessPromotionPiece;
+/** A caller-owned cell location in a rectangular chess presentation board. */
+export interface ChessBoardCell {
+  readonly column: number;
+  readonly row: number;
 }
 
-export interface ChessMoveResult extends Omit<ChessMoveAttempt, 'promotion'> {
-  readonly fen: string;
-  readonly lan: string;
-  readonly promotion?: ChessPromotionPiece;
-  readonly san: string;
+/** The bounded presentation dimensions supported by ChessBoard. */
+export interface ChessBoardDimensions {
+  readonly columns: number;
+  readonly rows: number;
+}
+
+export interface ChessMoveAttempt {
+  readonly from: ChessBoardCell;
+  readonly to: ChessBoardCell;
 }
 
 export interface ChessPieceState {
   readonly color: 'black' | 'white';
   readonly piece: ChessPieceCode;
-  readonly square: ChessSquareId;
+  readonly cell: ChessBoardCell;
 }
 
 export interface ChessPieceRenderContext {
   readonly color: string;
   readonly piece: ChessPieceCode;
-  readonly square: ChessSquareId;
+  readonly cell: ChessBoardCell;
+  /** Available cell edge length in pixels. */
+  readonly size: number;
 }
 
 export type ChessPieceRenderer = (context: ChessPieceRenderContext) => React.ReactNode;
@@ -65,20 +68,24 @@ export interface OpeningBookColorScheme {
 export type OpeningBookColorOverrides = Partial<OpeningBookColorScheme>;
 
 export interface ChessBoardProps extends ZoraBaseProps {
-  readonly fen?: string;
+  /** Number of displayed columns, from 2 through 24. */
+  readonly columns?: number;
+  /** Number of displayed rows, from 2 through 24. */
+  readonly rows?: number;
   readonly pieces?: readonly ChessPieceState[];
   readonly orientation?: ChessBoardOrientation;
-  readonly selectedSquare?: ChessSquareId | null;
-  readonly legalTargets?: readonly ChessSquareId[];
+  readonly selectedCell?: ChessBoardCell | null;
+  readonly legalTargets?: readonly ChessBoardCell[];
   readonly lastMove?: ChessMoveAttempt | null;
   readonly disabled?: boolean;
   readonly showCoordinates?: boolean;
-  readonly validateMoves?: boolean;
+  /** Enables explicit editor resize controls when a dimensions callback is supplied. */
+  readonly resizable?: boolean;
   readonly colorScheme?: ChessBoardColorOverrides;
-  readonly onSquarePress?: (square: ChessSquareId) => void;
+  readonly onCellPress?: (cell: ChessBoardCell) => void;
   readonly onMoveAttempt?: (move: ChessMoveAttempt) => void;
-  readonly onLegalMove?: (move: ChessMoveResult) => void;
-  readonly onInvalidMove?: (move: ChessMoveAttempt) => void;
+  /** Receives a caller-owned resize proposal; ZORA never mutates board dimensions. */
+  readonly onDimensionsChange?: (dimensions: ChessBoardDimensions) => void;
   readonly renderPiece?: ChessPieceRenderer;
 }