@dreamboard-games/ui-sdk 0.0.41

package/src/hooks/useBoardTopology.ts

@@ -0,0 +1,316 @@
+import { useCallback, useMemo } from "react";
+import type {
+  AnyHexBoardInput,
+  AnySquareBoardInput,
+  BoardEdgeIdOf,
+  BoardSpaceIdOf,
+  BoardVertexIdOf,
+  NormalizedHexBoard,
+  NormalizedHexEdgeOf,
+  NormalizedHexTileOf,
+  NormalizedHexVertexOf,
+  NormalizedSquareBoard,
+  NormalizedSquareCellOf,
+  NormalizedSquareEdgeOf,
+  NormalizedSquareVertexOf,
+} from "../types/tiled-board.js";
+import {
+  isGeneratedHexBoardInput,
+  normalizeHexBoardInput,
+  normalizeSquareBoardInput,
+} from "../types/tiled-board.js";
+
+type BoardTopologyData = AnyHexBoardInput | AnySquareBoardInput;
+
+type BoardSpaceOf<TBoard extends BoardTopologyData> =
+  TBoard extends AnyHexBoardInput
+    ? NormalizedHexTileOf<TBoard>
+    : TBoard extends AnySquareBoardInput
+      ? NormalizedSquareCellOf<TBoard>
+      : never;
+
+type BoardEdgeOf<TBoard extends BoardTopologyData> =
+  TBoard extends AnyHexBoardInput
+    ? NormalizedHexEdgeOf<TBoard>
+    : TBoard extends AnySquareBoardInput
+      ? NormalizedSquareEdgeOf<TBoard>
+      : never;
+
+type BoardVertexOf<TBoard extends BoardTopologyData> =
+  TBoard extends AnyHexBoardInput
+    ? NormalizedHexVertexOf<TBoard>
+    : TBoard extends AnySquareBoardInput
+      ? NormalizedSquareVertexOf<TBoard>
+      : never;
+
+type NormalizedBoardOf<TBoard extends BoardTopologyData> =
+  TBoard extends AnyHexBoardInput
+    ? NormalizedHexBoard<TBoard>
+    : TBoard extends AnySquareBoardInput
+      ? NormalizedSquareBoard<TBoard>
+      : never;
+
+type BoardLayoutOf<TBoard extends BoardTopologyData> =
+  TBoard extends AnyHexBoardInput ? "hex" : "square";
+
+function toSpaceIds<TBoard extends BoardTopologyData>(
+  edge: BoardEdgeOf<TBoard>,
+): ReadonlyArray<BoardSpaceIdOf<TBoard>> {
+  if ("spaceIds" in edge) {
+    return edge.spaceIds as ReadonlyArray<BoardSpaceIdOf<TBoard>>;
+  }
+  return [edge.hex1, edge.hex2] as unknown as ReadonlyArray<
+    BoardSpaceIdOf<TBoard>
+  >;
+}
+
+function toVertexSpaceIds<TBoard extends BoardTopologyData>(
+  vertex: BoardVertexOf<TBoard>,
+): ReadonlyArray<BoardSpaceIdOf<TBoard>> {
+  if ("spaceIds" in vertex) {
+    return vertex.spaceIds as ReadonlyArray<BoardSpaceIdOf<TBoard>>;
+  }
+  return vertex.hexes as ReadonlyArray<BoardSpaceIdOf<TBoard>>;
+}
+
+export interface UseBoardTopologyReturn<TBoard extends BoardTopologyData> {
+  layout: BoardLayoutOf<TBoard>;
+  board: NormalizedBoardOf<TBoard>;
+  getSpace: (
+    spaceId: BoardSpaceIdOf<TBoard>,
+  ) => BoardSpaceOf<TBoard> | undefined;
+  getEdge: (edgeId: BoardEdgeIdOf<TBoard>) => BoardEdgeOf<TBoard> | undefined;
+  getVertex: (
+    vertexId: BoardVertexIdOf<TBoard>,
+  ) => BoardVertexOf<TBoard> | undefined;
+  getAdjacentSpaces: (
+    spaceId: BoardSpaceIdOf<TBoard>,
+  ) => Array<BoardSpaceOf<TBoard>>;
+  getDistance: (
+    fromSpaceId: BoardSpaceIdOf<TBoard>,
+    toSpaceId: BoardSpaceIdOf<TBoard>,
+  ) => number;
+  getSpaceEdges: (
+    spaceId: BoardSpaceIdOf<TBoard>,
+  ) => Array<BoardEdgeOf<TBoard>>;
+  getSpaceVertices: (
+    spaceId: BoardSpaceIdOf<TBoard>,
+  ) => Array<BoardVertexOf<TBoard>>;
+  getIncidentEdges: (
+    vertexId: BoardVertexIdOf<TBoard>,
+  ) => Array<BoardEdgeOf<TBoard>>;
+  getIncidentVertices: (
+    edgeId: BoardEdgeIdOf<TBoard>,
+  ) => Array<BoardVertexOf<TBoard>>;
+}
+
+export function useBoardTopology<const TBoard extends BoardTopologyData>(
+  board: TBoard,
+): UseBoardTopologyReturn<TBoard> {
+  const normalizedBoard = useMemo<NormalizedBoardOf<TBoard>>(() => {
+    const candidateBoard = board as BoardTopologyData;
+
+    if (isGeneratedHexBoardInput(candidateBoard) || "tiles" in candidateBoard) {
+      return normalizeHexBoardInput(
+        candidateBoard as AnyHexBoardInput,
+      ) as NormalizedBoardOf<TBoard>;
+    }
+    return normalizeSquareBoardInput(
+      candidateBoard as AnySquareBoardInput,
+    ) as NormalizedBoardOf<TBoard>;
+  }, [board]);
+
+  const layout = (
+    "tiles" in normalizedBoard ? "hex" : "square"
+  ) as BoardLayoutOf<TBoard>;
+  const spaces = useMemo(
+    () =>
+      ("tiles" in normalizedBoard
+        ? normalizedBoard.tiles
+        : normalizedBoard.cells) as Array<BoardSpaceOf<TBoard>>,
+    [normalizedBoard],
+  );
+  const edges = useMemo(
+    () => normalizedBoard.edges as Array<BoardEdgeOf<TBoard>>,
+    [normalizedBoard.edges],
+  );
+  const vertices = useMemo(
+    () => normalizedBoard.vertices as Array<BoardVertexOf<TBoard>>,
+    [normalizedBoard.vertices],
+  );
+
+  const spaceById = useMemo(
+    () =>
+      new Map<BoardSpaceIdOf<TBoard>, BoardSpaceOf<TBoard>>(
+        spaces.map((space) => [space.id as BoardSpaceIdOf<TBoard>, space]),
+      ),
+    [spaces],
+  );
+  const edgeById = useMemo(
+    () =>
+      new Map<BoardEdgeIdOf<TBoard>, BoardEdgeOf<TBoard>>(
+        edges.map((edge) => [edge.id as BoardEdgeIdOf<TBoard>, edge]),
+      ),
+    [edges],
+  );
+  const vertexById = useMemo(
+    () =>
+      new Map<BoardVertexIdOf<TBoard>, BoardVertexOf<TBoard>>(
+        vertices.map((vertex) => [
+          vertex.id as BoardVertexIdOf<TBoard>,
+          vertex,
+        ]),
+      ),
+    [vertices],
+  );
+
+  const adjacentSpaceIdsById = useMemo(() => {
+    const adjacency = new Map<
+      BoardSpaceIdOf<TBoard>,
+      Array<BoardSpaceIdOf<TBoard>>
+    >();
+    for (const space of spaces) {
+      adjacency.set(space.id as BoardSpaceIdOf<TBoard>, []);
+    }
+    for (const edge of edges) {
+      const spaceIds = toSpaceIds(edge);
+      if (spaceIds.length !== 2) {
+        continue;
+      }
+      const [leftId, rightId] = spaceIds;
+      if (!leftId || !rightId) {
+        continue;
+      }
+      adjacency.set(leftId, [...(adjacency.get(leftId) ?? []), rightId]);
+      adjacency.set(rightId, [...(adjacency.get(rightId) ?? []), leftId]);
+    }
+    return adjacency;
+  }, [edges, spaces]);
+
+  const getSpace = useCallback(
+    (spaceId: BoardSpaceIdOf<TBoard>) => {
+      return spaceById.get(spaceId);
+    },
+    [spaceById],
+  );
+
+  const getEdge = useCallback(
+    (edgeId: BoardEdgeIdOf<TBoard>) => {
+      return edgeById.get(edgeId);
+    },
+    [edgeById],
+  );
+
+  const getVertex = useCallback(
+    (vertexId: BoardVertexIdOf<TBoard>) => {
+      return vertexById.get(vertexId);
+    },
+    [vertexById],
+  );
+
+  const getAdjacentSpaces = useCallback(
+    (spaceId: BoardSpaceIdOf<TBoard>) => {
+      return (adjacentSpaceIdsById.get(spaceId) ?? [])
+        .map((adjacentSpaceId) => spaceById.get(adjacentSpaceId))
+        .filter((space): space is BoardSpaceOf<TBoard> => space !== undefined);
+    },
+    [adjacentSpaceIdsById, spaceById],
+  );
+
+  const getDistance = useCallback(
+    (
+      fromSpaceId: BoardSpaceIdOf<TBoard>,
+      toSpaceId: BoardSpaceIdOf<TBoard>,
+    ) => {
+      if (fromSpaceId === toSpaceId) {
+        return 0;
+      }
+
+      const visited = new Set<BoardSpaceIdOf<TBoard>>([fromSpaceId]);
+      let frontier = [fromSpaceId];
+      let distance = 0;
+
+      while (frontier.length > 0) {
+        distance += 1;
+        const nextFrontier: Array<BoardSpaceIdOf<TBoard>> = [];
+        for (const currentSpaceId of frontier) {
+          for (const adjacentSpaceId of adjacentSpaceIdsById.get(
+            currentSpaceId,
+          ) ?? []) {
+            if (adjacentSpaceId === toSpaceId) {
+              return distance;
+            }
+            if (!visited.has(adjacentSpaceId)) {
+              visited.add(adjacentSpaceId);
+              nextFrontier.push(adjacentSpaceId);
+            }
+          }
+        }
+        frontier = nextFrontier;
+      }
+
+      return Number.POSITIVE_INFINITY;
+    },
+    [adjacentSpaceIdsById],
+  );
+
+  const getSpaceEdges = useCallback(
+    (spaceId: BoardSpaceIdOf<TBoard>) => {
+      return edges.filter((edge) => toSpaceIds(edge).includes(spaceId));
+    },
+    [edges],
+  );
+
+  const getSpaceVertices = useCallback(
+    (spaceId: BoardSpaceIdOf<TBoard>) => {
+      return vertices.filter((vertex) =>
+        toVertexSpaceIds(vertex).includes(spaceId),
+      );
+    },
+    [vertices],
+  );
+
+  const getIncidentEdges = useCallback(
+    (vertexId: BoardVertexIdOf<TBoard>) => {
+      const vertex = vertexById.get(vertexId);
+      if (!vertex) {
+        return [];
+      }
+      const vertexSpaceIds = new Set(toVertexSpaceIds(vertex));
+      return edges.filter((edge) =>
+        toSpaceIds(edge).every((spaceId) => vertexSpaceIds.has(spaceId)),
+      );
+    },
+    [edges, vertexById],
+  );
+
+  const getIncidentVertices = useCallback(
+    (edgeId: BoardEdgeIdOf<TBoard>) => {
+      const edge = edgeById.get(edgeId);
+      if (!edge) {
+        return [];
+      }
+      const edgeSpaceIds = new Set(toSpaceIds(edge));
+      return vertices.filter((vertex) =>
+        Array.from(edgeSpaceIds).every((spaceId) =>
+          toVertexSpaceIds(vertex).includes(spaceId),
+        ),
+      );
+    },
+    [edgeById, vertices],
+  );
+
+  return {
+    layout,
+    board: normalizedBoard,
+    getSpace,
+    getEdge,
+    getVertex,
+    getAdjacentSpaces,
+    getDistance,
+    getSpaceEdges,
+    getSpaceVertices,
+    getIncidentEdges,
+    getIncidentVertices,
+  };
+}

package/src/hooks/useCards.test.tsx

@@ -0,0 +1,129 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import type { CardCollection, ViewCard } from "@dreamboard/sdk-types";
+import { RuntimeContext } from "../context/RuntimeContext.js";
+import { PluginSessionContext } from "../context/PluginSessionContext.js";
+import type { PluginStateSnapshot } from "../types/plugin-state.js";
+import type { PluginSessionState, RuntimeAPI } from "../types/runtime-api.js";
+import { materializeCards } from "../helpers/cards.js";
+import { useGameSelector } from "./useGameSelector.js";
+import { useCards } from "./useCards.js";
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createRuntime(snapshot: PluginStateSnapshot): RuntimeAPI & {
+  getSnapshot: () => PluginStateSnapshot;
+  subscribeToState: (
+    listener: (state: PluginStateSnapshot) => void,
+  ) => () => void;
+} {
+  return {
+    validateInteraction: async () => ({ valid: true }),
+    submitInteraction: async () => undefined,
+    getSessionState: () => snapshot.session,
+    disconnect: () => undefined,
+    getSnapshot: () => snapshot,
+    subscribeToState: () => () => undefined,
+  };
+}
+
+test("useCards materializes reducer-native card collections without remapping", () => {
+  const session = createSessionState();
+  const snapshot: PluginStateSnapshot = {
+    view: {
+      hand: {
+        cardIds: ["card-1"],
+        cardsById: {
+          "card-1": {
+            id: "card-1",
+            cardType: "goods",
+            name: "Wheat",
+            properties: { value: 3 },
+          },
+        },
+      },
+    },
+    gameplay: {
+      currentPhase: "takeTurn",
+      currentStage: null,
+      activePlayers: [],
+      availableInteractions: [],
+      zones: {},
+    },
+    lobby: null,
+    notifications: [],
+    session,
+    history: null,
+    syncId: 1,
+  };
+  const runtime = createRuntime(snapshot);
+  let captured: ReturnType<typeof useCards> | null = null;
+
+  function Harness() {
+    const hand = useGameSelector(
+      (view) => (view as { hand: CardCollection<string, ViewCard> }).hand,
+    );
+    captured = useCards(hand);
+    return null;
+  }
+
+  renderToString(
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={session}>
+        <Harness />
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>,
+  );
+
+  expect(captured).toEqual([
+    {
+      id: "card-1",
+      cardType: "goods",
+      name: "Wheat",
+      properties: { value: 3 },
+    },
+  ]);
+});
+
+test("card helpers materialize reducer-native collections and preserve slot nullability", () => {
+  expect(
+    materializeCards({
+      cardIds: ["card-1"],
+      cardsById: {
+        "card-1": {
+          id: "card-1",
+          cardType: "goods",
+          properties: { value: 2 },
+        },
+      },
+    }),
+  ).toEqual([
+    {
+      id: "card-1",
+      cardType: "goods",
+      properties: { value: 2 },
+    },
+  ]);
+
+  expect([
+    {
+      pieceId: "worker-1",
+      playerId: null,
+      slotId: "market",
+    },
+  ]).toEqual([
+    {
+      pieceId: "worker-1",
+      playerId: null,
+      slotId: "market",
+    },
+  ]);
+});

package/src/hooks/useCards.ts

@@ -0,0 +1,10 @@
+import { useMemo } from "react";
+import type { CardCollection, ViewCard } from "@dreamboard/sdk-types";
+import { materializeCards } from "../helpers/cards.js";
+
+export function useCards<
+  CardIdValue extends string,
+  CardValue extends ViewCard<CardIdValue>,
+>(collection: CardCollection<CardIdValue, CardValue>) {
+  return useMemo(() => materializeCards(collection), [collection]);
+}

package/src/hooks/useGameSelector.ts

@@ -0,0 +1,105 @@
+import { useRef, useSyncExternalStore } from "react";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+import type { GameView } from "@dreamboard/ui-contract";
+import type { PluginStateSnapshot } from "../types/reducer-state.js";
+import type { PluginRuntimeAPI } from "../runtime/createPluginRuntimeAPI.js";
+
+type EqualityFn<T> = (left: T, right: T) => boolean;
+
+interface SelectorCache<T> {
+  rawView: GameView;
+  selected: T;
+}
+
+function defaultEquality<T>(left: T, right: T): boolean {
+  return Object.is(left, right);
+}
+
+function requireProjectedView(
+  snapshot: PluginStateSnapshot | null | undefined,
+  message: string,
+): GameView {
+  const view = snapshot?.view;
+  if (view === null || typeof view === "undefined") {
+    throw new Error(message);
+  }
+  return view;
+}
+
+/**
+ * Hook to select a derived value from the projected reducer view.
+ * Only re-renders when the selected slice changes according to the equalityFn.
+ *
+ * @param selector - Function to extract data from the projected view
+ * @param equalityFn - Optional equality function for selected slice comparison
+ * @returns Selected value from the current projected view
+ */
+export function useGameSelector<T>(
+  selector: (state: GameView) => T,
+  equalityFn: EqualityFn<T> = defaultEquality,
+): T {
+  const runtime = useRuntimeContext() as PluginRuntimeAPI;
+  const selectorRef = useRef(selector);
+  const equalityRef = useRef(equalityFn);
+  const cacheRef = useRef<SelectorCache<T> | null>(null);
+
+  if (selectorRef.current !== selector || equalityRef.current !== equalityFn) {
+    selectorRef.current = selector;
+    equalityRef.current = equalityFn;
+    cacheRef.current = null;
+  }
+
+  const message =
+    "useGameSelector: Projected view not available. Ensure the reducer-native host payload is initialized.";
+
+  const getSelectedFromSnapshot = (
+    snapshot: PluginStateSnapshot | null | undefined,
+  ): T => {
+    const view = requireProjectedView(snapshot, message);
+    const cached = cacheRef.current;
+    if (cached && cached.rawView === view) {
+      return cached.selected;
+    }
+
+    const nextSelected = selectorRef.current(view);
+    if (cached && equalityRef.current(cached.selected, nextSelected)) {
+      cacheRef.current = {
+        rawView: view,
+        selected: cached.selected,
+      };
+      return cached.selected;
+    }
+
+    cacheRef.current = {
+      rawView: view,
+      selected: nextSelected,
+    };
+    return nextSelected;
+  };
+
+  const subscribe = (onStoreChange: () => void) => {
+    if (!runtime.subscribeToState) {
+      return () => {};
+    }
+
+    return runtime.subscribeToState((snapshot) => {
+      const previousCache = cacheRef.current;
+      const nextSelected = getSelectedFromSnapshot(
+        snapshot as PluginStateSnapshot,
+      );
+      if (
+        !previousCache ||
+        !equalityRef.current(previousCache.selected, nextSelected)
+      ) {
+        onStoreChange();
+      }
+    });
+  };
+
+  const getSnapshot = () =>
+    getSelectedFromSnapshot(
+      (runtime.getSnapshot?.() ?? null) as PluginStateSnapshot | null,
+    );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/hooks/useGameView.ts

@@ -0,0 +1,9 @@
+import type { GameView } from "@dreamboard/ui-contract";
+import { useGameSelector } from "./useGameSelector.js";
+
+/**
+ * Hook to access the current seat-projected reducer-native view.
+ */
+export function useGameView(): GameView {
+  return useGameSelector((view) => view);
+}