@dreamboard-games/ui-sdk 0.0.41

package/dist/hooks/useBoardInteractions.js

@@ -0,0 +1,248 @@
+import { useCallback, useMemo } from "react";
+import { useStore } from "zustand";
+import { useInteractionUiStore } from "../context/InteractionDraftContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { usePluginState } from "../context/PluginStateContext.js";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+import { validationErrorFromUnknown } from "../errors/ValidationError.js";
+import { eligibleTargetsByBoardKind, eligibleTargetsForInput, hasBoardTargetInput, hasCardTargetInput, hasInteractionFieldErrors, inputByTarget, inputKeyForTarget, isInputValueReady, interactionArmScope, interactionInputKeys, toggleManyValue, validateInteractionInputDomains, } from "../utils/interaction-inputs.js";
+export class BoardInteractionConflictError extends Error {
+    constructor({ targetKind, targetId, interactionKeys, }) {
+        super(`Ambiguous ${targetKind} target '${targetId}' matched interactions: ${interactionKeys.join(", ")}. Arm one interaction explicitly or route with a narrower board primitive.`);
+        this.name = "BoardInteractionConflictError";
+        this.targetKind = targetKind;
+        this.targetId = targetId;
+        this.interactionKeys = interactionKeys;
+    }
+}
+/**
+ * Board-surface orchestration helper that removes the boilerplate of
+ * wiring many `useInteractionById(...)` calls, merging their
+ * eligibility sets, and dispatching clicks to the right handle.
+ *
+ * Use this alongside (or instead of) `<BoardSurface>` when a game
+ * keeps multiple board interactions live simultaneously and dispatch
+ * is target-driven rather than armed-then-clicked. The typical
+ * Catan-class shape:
+ *
+ * ```tsx
+ * const board = useBoardInteractions();
+ *
+ * return (
+ *   <HexGrid
+ *     interactiveVertices={board.targetLayers.vertex()}
+ *     interactiveEdges={board.targetLayers.edge()}
+ *     onTileClick={(id) =>
+ *       board.select.space(id, { stealFromPlayerId: null })
+ *     }
+ *   />
+ * );
+ * ```
+ *
+ * Eligibility and availability remain authoritative on reducer-projected
+ * descriptors. Armed follow-up descriptors beat ambient board descriptors.
+ * Multiple unarmed matches are ambiguous and throw
+ * {@link BoardInteractionConflictError}.
+ */
+export function useBoardInteractions(options = {}) {
+    const { targetKinds } = options;
+    const runtime = useRuntimeContext();
+    const { controllingPlayerId } = usePluginSession();
+    const store = useInteractionUiStore();
+    const subscribedArmedBySurface = useStore(store, (state) => state.arms);
+    const armedBySurface = store.getState().arms ?? subscribedArmedBySurface;
+    const descriptors = usePluginState((state) => state.gameplay.availableInteractions ?? []);
+    const targetKindSet = useMemo(() => new Set(targetKinds), [targetKinds]);
+    const armedIds = useMemo(() => new Set(Object.values(armedBySurface)), [armedBySurface]);
+    const interactions = useMemo(() => {
+        return descriptors.filter((descriptor) => {
+            if (armedIds.has(descriptor.interactionKey))
+                return true;
+            if (hasCardTargetInput(descriptor))
+                return false;
+            if (!hasBoardTargetInput(descriptor))
+                return false;
+            if (!targetKinds || targetKinds.length === 0)
+                return true;
+            const byKind = eligibleTargetsByBoardKind(descriptor);
+            return Object.keys(byKind).some((kind) => targetKindSet.has(kind));
+        });
+    }, [armedIds, descriptors, targetKindSet, targetKinds]);
+    const eligible = useMemo(() => {
+        const acc = {
+            edge: new Set(),
+            vertex: new Set(),
+            space: new Set(),
+            tile: new Set(),
+        };
+        for (const descriptor of interactions) {
+            if (!descriptor.available)
+                continue;
+            const targetsByKind = eligibleTargetsByBoardKind(descriptor);
+            for (const [targetKind, ids] of Object.entries(targetsByKind)) {
+                if (!ids)
+                    continue;
+                const bucket = acc[targetKind];
+                for (const id of ids)
+                    bucket.add(id);
+            }
+        }
+        return acc;
+    }, [interactions]);
+    const isEligible = useCallback((targetId, targetKind) => {
+        if (targetKind !== undefined) {
+            return eligible[targetKind].has(targetId);
+        }
+        for (const bucket of Object.values(eligible)) {
+            if (bucket.has(targetId))
+                return true;
+        }
+        return false;
+    }, [eligible]);
+    const selectByKind = useCallback(async (targetKind, targetId, extraInputs) => {
+        if (!controllingPlayerId)
+            return null;
+        const matches = interactions.flatMap((descriptor) => {
+            if (!descriptor.available)
+                return [];
+            const inputKey = inputKeyForTarget(descriptor, targetKind, targetId);
+            if (!inputKey)
+                return [];
+            const input = inputByTarget(descriptor, targetKind, targetId);
+            if (input?.domain.type === "target" &&
+                !isTargetSelectable(input, store.getDraft(descriptor.interactionKey), targetId)) {
+                return [];
+            }
+            const targets = eligibleTargetsForInput(descriptor, inputKey);
+            if (!targets || !targets.includes(targetId))
+                return [];
+            return [
+                {
+                    descriptor,
+                    inputKey,
+                    armed: armedIds.has(descriptor.interactionKey),
+                },
+            ];
+        });
+        const selected = selectDispatchCandidate(matches, targetKind, targetId);
+        if (selected) {
+            const { descriptor, inputKey } = selected;
+            const input = inputByTarget(descriptor, targetKind, targetId);
+            const currentDraft = store.getDraft(descriptor.interactionKey);
+            const selection = input?.domain.type === "target" ? input.domain.selection : undefined;
+            const nextTargetValue = selection?.mode === "many"
+                ? toggleManyValue(currentDraft[inputKey], targetId, selection)
+                : targetId;
+            const params = {
+                ...currentDraft,
+                ...(extraInputs ?? {}),
+                [inputKey]: nextTargetValue,
+            };
+            for (const [key, value] of Object.entries(extraInputs ?? {})) {
+                store.setInput(descriptor.interactionKey, key, value);
+            }
+            store.setInput(descriptor.interactionKey, inputKey, nextTargetValue);
+            if (descriptor.commit.mode !== "autoWhenReady" ||
+                (selection?.mode === "many" && !isDraftReady(descriptor, params))) {
+                store.arm(interactionArmScope(descriptor), descriptor.interactionKey);
+                return descriptor.interactionKey;
+            }
+            // Fill any remaining required inputs with `null` so the reducer
+            // bundle can decide whether to reject (missing) or accept
+            // (optional). This matches the Catan "spaceId + null stealee"
+            // pattern without forcing callers to memorise each interaction's
+            // full input shape.
+            for (const required of interactionInputKeys(descriptor)) {
+                if (!(required in params))
+                    params[required] = null;
+            }
+            try {
+                await runtime.submitInteraction(controllingPlayerId, descriptor.interactionId, params);
+                store.clearInput(descriptor.interactionKey);
+                if (store.getArmed(interactionArmScope(descriptor)) ===
+                    descriptor.interactionKey) {
+                    store.arm(interactionArmScope(descriptor), null);
+                }
+                return descriptor.interactionKey;
+            }
+            catch (error) {
+                throw validationErrorFromUnknown(error);
+            }
+        }
+        return null;
+    }, [armedIds, controllingPlayerId, interactions, runtime, store]);
+    const select = useMemo(() => ({
+        edge: (targetId, extraInputs) => selectByKind("edge", targetId, extraInputs),
+        vertex: (targetId, extraInputs) => selectByKind("vertex", targetId, extraInputs),
+        space: (targetId, extraInputs) => selectByKind("space", targetId, extraInputs),
+        tile: (targetId, extraInputs) => selectByKind("tile", targetId, extraInputs),
+    }), [selectByKind]);
+    const targetLayers = useMemo(() => {
+        const createLayer = (targetKind) => (layerOptions = {}) => {
+            const { enabled, extraInputs, onBeforeSelect, onError } = layerOptions;
+            const resolveExtraInputs = (targetId) => typeof extraInputs === "function"
+                ? extraInputs(targetId)
+                : extraInputs;
+            return {
+                enabled,
+                eligible: eligible[targetKind],
+                selectTargetId: async (targetId) => {
+                    if (enabled === false)
+                        return;
+                    onBeforeSelect?.();
+                    try {
+                        await select[targetKind](targetId, resolveExtraInputs(targetId));
+                    }
+                    catch (error) {
+                        onError?.(error);
+                        if (!onError)
+                            throw error;
+                    }
+                },
+            };
+        };
+        return {
+            edge: createLayer("edge"),
+            vertex: createLayer("vertex"),
+            space: createLayer("space"),
+            tile: createLayer("tile"),
+        };
+    }, [eligible, select]);
+    return useMemo(() => ({ interactions, eligible, isEligible, select, targetLayers }), [interactions, eligible, isEligible, select, targetLayers]);
+}
+function isTargetSelectable(input, draft, targetId) {
+    const selection = input.domain.type === "target" ? input.domain.selection : undefined;
+    if (selection?.mode !== "many" || !selection.distinct)
+        return true;
+    const current = draft[input.key];
+    if (!Array.isArray(current))
+        return true;
+    if (current.map((item) => String(item)).includes(targetId))
+        return true;
+    return selection.max === undefined || current.length < selection.max;
+}
+function isDraftReady(descriptor, draft) {
+    const fieldErrors = validateInteractionInputDomains(descriptor, draft);
+    if (hasInteractionFieldErrors(fieldErrors))
+        return false;
+    return interactionInputKeys(descriptor).every((key) => {
+        const input = descriptor.inputs.find((candidate) => candidate.key === key);
+        const value = draft[key] ??
+            (input && "defaultValue" in input ? input.defaultValue : undefined);
+        return input ? isInputValueReady(input, value) : value !== undefined;
+    });
+}
+function selectDispatchCandidate(matches, targetKind, targetId) {
+    if (matches.length === 0)
+        return null;
+    const armed = matches.filter((match) => match.armed);
+    const candidates = armed.length > 0 ? armed : matches;
+    if (candidates.length > 1) {
+        throw new BoardInteractionConflictError({
+            targetKind,
+            targetId,
+            interactionKeys: candidates.map((winner) => winner.descriptor.interactionKey),
+        });
+    }
+    return candidates[0] ?? null;
+}

package/dist/hooks/useBoardTopology.d.ts

@@ -0,0 +1,23 @@
+import type { AnyHexBoardInput, AnySquareBoardInput, BoardEdgeIdOf, BoardSpaceIdOf, BoardVertexIdOf, NormalizedHexBoard, NormalizedHexEdgeOf, NormalizedHexTileOf, NormalizedHexVertexOf, NormalizedSquareBoard, NormalizedSquareCellOf, NormalizedSquareEdgeOf, NormalizedSquareVertexOf } 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";
+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 declare function useBoardTopology<const TBoard extends BoardTopologyData>(board: TBoard): UseBoardTopologyReturn<TBoard>;
+export {};
+//# sourceMappingURL=useBoardTopology.d.ts.map

package/dist/hooks/useBoardTopology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBoardTopology.d.ts","sourceRoot":"","sources":["../../src/hooks/useBoardTopology.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useBoardTopology.js

@@ -0,0 +1,128 @@
+import { useCallback, useMemo } from "react";
+import { isGeneratedHexBoardInput, normalizeHexBoardInput, normalizeSquareBoardInput, } from "../types/tiled-board.js";
+function toSpaceIds(edge) {
+    if ("spaceIds" in edge) {
+        return edge.spaceIds;
+    }
+    return [edge.hex1, edge.hex2];
+}
+function toVertexSpaceIds(vertex) {
+    if ("spaceIds" in vertex) {
+        return vertex.spaceIds;
+    }
+    return vertex.hexes;
+}
+export function useBoardTopology(board) {
+    const normalizedBoard = useMemo(() => {
+        const candidateBoard = board;
+        if (isGeneratedHexBoardInput(candidateBoard) || "tiles" in candidateBoard) {
+            return normalizeHexBoardInput(candidateBoard);
+        }
+        return normalizeSquareBoardInput(candidateBoard);
+    }, [board]);
+    const layout = ("tiles" in normalizedBoard ? "hex" : "square");
+    const spaces = useMemo(() => ("tiles" in normalizedBoard
+        ? normalizedBoard.tiles
+        : normalizedBoard.cells), [normalizedBoard]);
+    const edges = useMemo(() => normalizedBoard.edges, [normalizedBoard.edges]);
+    const vertices = useMemo(() => normalizedBoard.vertices, [normalizedBoard.vertices]);
+    const spaceById = useMemo(() => new Map(spaces.map((space) => [space.id, space])), [spaces]);
+    const edgeById = useMemo(() => new Map(edges.map((edge) => [edge.id, edge])), [edges]);
+    const vertexById = useMemo(() => new Map(vertices.map((vertex) => [
+        vertex.id,
+        vertex,
+    ])), [vertices]);
+    const adjacentSpaceIdsById = useMemo(() => {
+        const adjacency = new Map();
+        for (const space of spaces) {
+            adjacency.set(space.id, []);
+        }
+        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) => {
+        return spaceById.get(spaceId);
+    }, [spaceById]);
+    const getEdge = useCallback((edgeId) => {
+        return edgeById.get(edgeId);
+    }, [edgeById]);
+    const getVertex = useCallback((vertexId) => {
+        return vertexById.get(vertexId);
+    }, [vertexById]);
+    const getAdjacentSpaces = useCallback((spaceId) => {
+        return (adjacentSpaceIdsById.get(spaceId) ?? [])
+            .map((adjacentSpaceId) => spaceById.get(adjacentSpaceId))
+            .filter((space) => space !== undefined);
+    }, [adjacentSpaceIdsById, spaceById]);
+    const getDistance = useCallback((fromSpaceId, toSpaceId) => {
+        if (fromSpaceId === toSpaceId) {
+            return 0;
+        }
+        const visited = new Set([fromSpaceId]);
+        let frontier = [fromSpaceId];
+        let distance = 0;
+        while (frontier.length > 0) {
+            distance += 1;
+            const nextFrontier = [];
+            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) => {
+        return edges.filter((edge) => toSpaceIds(edge).includes(spaceId));
+    }, [edges]);
+    const getSpaceVertices = useCallback((spaceId) => {
+        return vertices.filter((vertex) => toVertexSpaceIds(vertex).includes(spaceId));
+    }, [vertices]);
+    const getIncidentEdges = useCallback((vertexId) => {
+        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) => {
+        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/dist/hooks/useCards.d.ts

@@ -0,0 +1,3 @@
+import type { CardCollection, ViewCard } from "@dreamboard/sdk-types";
+export declare function useCards<CardIdValue extends string, CardValue extends ViewCard<CardIdValue>>(collection: CardCollection<CardIdValue, CardValue>): CardValue[];
+//# sourceMappingURL=useCards.d.ts.map

package/dist/hooks/useCards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCards.d.ts","sourceRoot":"","sources":["../../src/hooks/useCards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtE,wBAAgB,QAAQ,CACtB,WAAW,SAAS,MAAM,EAC1B,SAAS,SAAS,QAAQ,CAAC,WAAW,CAAC,EACvC,UAAU,EAAE,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC,eAEnD"}

package/dist/hooks/useCards.js

@@ -0,0 +1,5 @@
+import { useMemo } from "react";
+import { materializeCards } from "../helpers/cards.js";
+export function useCards(collection) {
+    return useMemo(() => materializeCards(collection), [collection]);
+}

package/dist/hooks/useGameSelector.d.ts

@@ -0,0 +1,13 @@
+import type { GameView } from "@dreamboard/ui-contract";
+type EqualityFn<T> = (left: T, right: T) => boolean;
+/**
+ * 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 declare function useGameSelector<T>(selector: (state: GameView) => T, equalityFn?: EqualityFn<T>): T;
+export {};
+//# sourceMappingURL=useGameSelector.d.ts.map

package/dist/hooks/useGameSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGameSelector.d.ts","sourceRoot":"","sources":["../../src/hooks/useGameSelector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAIxD,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;AAsBpD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,CAAC,EAChC,UAAU,GAAE,UAAU,CAAC,CAAC,CAAmB,GAC1C,CAAC,CAiEH"}

package/dist/hooks/useGameSelector.js

@@ -0,0 +1,67 @@
+import { useRef, useSyncExternalStore } from "react";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+function defaultEquality(left, right) {
+    return Object.is(left, right);
+}
+function requireProjectedView(snapshot, message) {
+    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(selector, equalityFn = defaultEquality) {
+    const runtime = useRuntimeContext();
+    const selectorRef = useRef(selector);
+    const equalityRef = useRef(equalityFn);
+    const cacheRef = useRef(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) => {
+        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) => {
+        if (!runtime.subscribeToState) {
+            return () => { };
+        }
+        return runtime.subscribeToState((snapshot) => {
+            const previousCache = cacheRef.current;
+            const nextSelected = getSelectedFromSnapshot(snapshot);
+            if (!previousCache ||
+                !equalityRef.current(previousCache.selected, nextSelected)) {
+                onStoreChange();
+            }
+        });
+    };
+    const getSnapshot = () => getSelectedFromSnapshot((runtime.getSnapshot?.() ?? null));
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/dist/hooks/useGameView.d.ts

@@ -0,0 +1,6 @@
+import type { GameView } from "@dreamboard/ui-contract";
+/**
+ * Hook to access the current seat-projected reducer-native view.
+ */
+export declare function useGameView(): GameView;
+//# sourceMappingURL=useGameView.d.ts.map

package/dist/hooks/useGameView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGameView.d.ts","sourceRoot":"","sources":["../../src/hooks/useGameView.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGxD;;GAEG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAEtC"}

package/dist/hooks/useGameView.js

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

package/dist/hooks/useHandLayout.d.ts

@@ -0,0 +1,120 @@
+import type { RefObject } from "react";
+export type CardSize = "sm" | "md" | "lg";
+export type HandLayout = "spread" | "stack" | "overlap";
+export interface CardPositionProps {
+    /** X position (left offset) */
+    x: number;
+    /** Y position (vertical offset for hover/selected) */
+    y: number;
+    /** Z-index for layering */
+    zIndex: number;
+    /** CSS transform origin */
+    transformOrigin: string;
+}
+export interface UseHandLayoutOptions {
+    /** Number of cards in the hand */
+    cardCount: number;
+    /** Card size variant */
+    cardSize?: CardSize;
+    /** Layout style */
+    layout?: HandLayout;
+    /** Padding to subtract from container width */
+    containerPadding?: number;
+}
+export interface UseHandLayoutReturn {
+    /** Ref to attach to the container element */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** Ref to attach to the cards container element (for mouse tracking) */
+    cardsContainerRef: RefObject<HTMLDivElement | null>;
+    /** Measured container width */
+    containerWidth: number;
+    /** Calculated offset between cards */
+    cardOffset: number;
+    /** Total width of all cards */
+    totalWidth: number;
+    /** Whether drawer mode should be used */
+    useDrawerMode: boolean;
+    /** Card dimensions for the current size */
+    cardDimensions: {
+        width: number;
+        height: number;
+    };
+    /** Constants for positioning */
+    constants: {
+        hoverLift: number;
+        selectedLift: number;
+    };
+    /** Currently hovered card index */
+    hoveredIndex: number | null;
+    /** Mouse move handler for the cards container */
+    handleMouseMove: (e: React.MouseEvent<HTMLDivElement>) => void;
+    /** Mouse leave handler for the cards container */
+    handleMouseLeave: () => void;
+    /** Get position props for a card at the given index */
+    getCardPosition: (index: number, isHovered: boolean, isSelected: boolean) => CardPositionProps;
+}
+/**
+ * Hook for managing hand layout calculations and interactions.
+ *
+ * Provides container measurement, overlap calculations, drawer mode detection,
+ * and hover state management for card hand displays.
+ *
+ * @example
+ * ```tsx
+ * function MyHand({ cards, selectedIds }) {
+ *   const {
+ *     containerRef,
+ *     cardsContainerRef,
+ *     totalWidth,
+ *     useDrawerMode,
+ *     cardDimensions,
+ *     hoveredIndex,
+ *     handleMouseMove,
+ *     handleMouseLeave,
+ *     getCardPosition,
+ *     constants,
+ *   } = useHandLayout({
+ *     cardCount: cards.length,
+ *     cardSize: "md",
+ *     layout: "overlap",
+ *   });
+ *
+ *   if (useDrawerMode) {
+ *     return <MyDrawerUI cards={cards} />;
+ *   }
+ *
+ *   return (
+ *     <div ref={containerRef}>
+ *       <div
+ *         ref={cardsContainerRef}
+ *         style={{ width: totalWidth, height: cardDimensions.height + constants.hoverLift }}
+ *         onMouseMove={handleMouseMove}
+ *         onMouseLeave={handleMouseLeave}
+ *       >
+ *         {cards.map((card, index) => {
+ *           const isHovered = hoveredIndex === index;
+ *           const isSelected = selectedIds.includes(card.id);
+ *           const position = getCardPosition(index, isHovered, isSelected);
+ *
+ *           return (
+ *             <div
+ *               key={card.id}
+ *               style={{
+ *                 position: "absolute",
+ *                 left: position.x,
+ *                 transform: `translateY(${position.y}px)`,
+ *                 zIndex: position.zIndex,
+ *               }}
+ *             >
+ *               <MyCard card={card} />
+ *             </div>
+ *           );
+ *         })}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHandLayout({ cardCount, cardSize, layout, containerPadding, }: UseHandLayoutOptions): UseHandLayoutReturn;
+//# sourceMappingURL=useHandLayout.d.ts.map

package/dist/hooks/useHandLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHandLayout.d.ts","sourceRoot":"","sources":["../../src/hooks/useHandLayout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAoBvC,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAC1C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,sDAAsD;IACtD,CAAC,EAAE,MAAM,CAAC;IACV,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mBAAmB;IACnB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,YAAY,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC/C,wEAAwE;IACxE,iBAAiB,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACpD,+BAA+B;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,aAAa,EAAE,OAAO,CAAC;IACvB,2CAA2C;IAC3C,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,gCAAgC;IAChC,SAAS,EAAE;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,mCAAmC;IACnC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,eAAe,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;IAC/D,kDAAkD;IAClD,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,uDAAuD;IACvD,eAAe,EAAE,CACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,OAAO,KAChB,iBAAiB,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,QAAe,EACf,MAAkB,EAClB,gBAAqB,GACtB,EAAE,oBAAoB,GAAG,mBAAmB,CAwM5C"}