@dreamboard-games/ui-sdk 0.0.41

package/dist/hooks/useIsMyTurn.js

@@ -0,0 +1,11 @@
+import { usePluginState } from "../context/PluginStateContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+/**
+ * Returns whether the currently controlled player is one of the engine-tracked
+ * active players for the current gameplay snapshot.
+ */
+export function useIsMyTurn() {
+    const { controllingPlayerId } = usePluginSession();
+    const activePlayers = usePluginState((state) => state.gameplay.activePlayers);
+    return (controllingPlayerId !== null && activePlayers.includes(controllingPlayerId));
+}

package/dist/hooks/useLobby.d.ts

@@ -0,0 +1,28 @@
+import type { LobbyState } from "../types/plugin-state.js";
+export type { LobbyState };
+/**
+ * Subscribes to lobby updates from the plugin runtime snapshot when present.
+ * Returns `null` until the host provides lobby state (SSR/tests/minimal runtimes).
+ */
+export declare function useLobbyState(): LobbyState | null;
+/**
+ * Hook to subscribe to lobby state updates.
+ * Returns the latest lobby information from state-sync messages.
+ *
+ * State is provided by PluginStateProvider from host's state-sync messages.
+ * The host transforms raw SSE LOBBY_UPDATE messages into clean LobbyState objects.
+ *
+ * @returns Current lobby state (never null - throws if not available)
+ * @throws Error if lobby state is not available
+ *
+ * @example
+ * ```typescript
+ * function LobbyScreen() {
+ *   const lobby = useLobby();
+ *   // lobby is guaranteed to be non-null
+ *   return <div>{lobby.seats.length} seats</div>;
+ * }
+ * ```
+ */
+export declare function useLobby(): LobbyState;
+//# sourceMappingURL=useLobby.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useLobby.d.ts","sourceRoot":"","sources":["../../src/hooks/useLobby.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAI3D,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAgCjD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,IAAI,UAAU,CAUrC"}

package/dist/hooks/useLobby.js

@@ -0,0 +1,60 @@
+import { useState, useEffect } from "react";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+/**
+ * Subscribes to lobby updates from the plugin runtime snapshot when present.
+ * Returns `null` until the host provides lobby state (SSR/tests/minimal runtimes).
+ */
+export function useLobbyState() {
+    const runtime = useRuntimeContext();
+    const getStateFromSnapshot = () => {
+        if (!runtime.getSnapshot)
+            return null;
+        const snapshot = runtime.getSnapshot();
+        if (!snapshot?.lobby)
+            return null;
+        return snapshot.lobby;
+    };
+    const [lobbyState, setLobbyState] = useState(getStateFromSnapshot);
+    useEffect(() => {
+        if (!runtime.subscribeToState) {
+            return;
+        }
+        const initialState = runtime.getSnapshot?.();
+        if (initialState?.lobby) {
+            setLobbyState(initialState.lobby);
+        }
+        return runtime.subscribeToState((snapshot) => {
+            if (snapshot.lobby) {
+                setLobbyState(snapshot.lobby);
+            }
+        });
+    }, [runtime]);
+    return lobbyState;
+}
+/**
+ * Hook to subscribe to lobby state updates.
+ * Returns the latest lobby information from state-sync messages.
+ *
+ * State is provided by PluginStateProvider from host's state-sync messages.
+ * The host transforms raw SSE LOBBY_UPDATE messages into clean LobbyState objects.
+ *
+ * @returns Current lobby state (never null - throws if not available)
+ * @throws Error if lobby state is not available
+ *
+ * @example
+ * ```typescript
+ * function LobbyScreen() {
+ *   const lobby = useLobby();
+ *   // lobby is guaranteed to be non-null
+ *   return <div>{lobby.seats.length} seats</div>;
+ * }
+ * ```
+ */
+export function useLobby() {
+    const lobbyState = useLobbyState();
+    if (lobbyState === null) {
+        throw new Error("useLobby: Lobby state not available. " +
+            "The host should only render the plugin when lobby state is ready.");
+    }
+    return lobbyState;
+}

package/dist/hooks/useMe.d.ts

@@ -0,0 +1,11 @@
+import type { Player } from "../types/player-state.js";
+export type { Player } from "../types/player-state.js";
+/**
+ * Hook to get information about the player currently being controlled by this user.
+ * Returns the currently selected player that the user is controlling.
+ *
+ * @returns Currently controlled player's info
+ * @throws Error if called before session is ready or if player not found in lobby
+ */
+export declare function useMe(): Player;
+//# sourceMappingURL=useMe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useMe.d.ts","sourceRoot":"","sources":["../../src/hooks/useMe.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGvD,YAAY,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,KAAK,IAAI,MAAM,CA+B9B"}

package/dist/hooks/useMe.js

@@ -0,0 +1,32 @@
+import { useMemo } from "react";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { useLobby } from "./useLobby.js";
+/**
+ * Hook to get information about the player currently being controlled by this user.
+ * Returns the currently selected player that the user is controlling.
+ *
+ * @returns Currently controlled player's info
+ * @throws Error if called before session is ready or if player not found in lobby
+ */
+export function useMe() {
+    const { controllingPlayerId } = usePluginSession();
+    const lobby = useLobby();
+    return useMemo(() => {
+        if (!controllingPlayerId) {
+            throw new Error("useMe: No controlling player available. Ensure session is initialized and user is not a spectator.");
+        }
+        if (!lobby) {
+            throw new Error("useMe: Lobby state not available. Ensure component is rendered during lobby or game phase.");
+        }
+        const seat = lobby.seats.find((s) => s.playerId === controllingPlayerId);
+        if (!seat) {
+            throw new Error(`useMe: Player ${controllingPlayerId} not found in lobby seats. This should not happen.`);
+        }
+        return {
+            playerId: seat.playerId,
+            name: seat.displayName,
+            isHost: seat.isHost,
+            color: seat.playerColor,
+        };
+    }, [controllingPlayerId, lobby]);
+}

package/dist/hooks/usePanZoom.d.ts

@@ -0,0 +1,113 @@
+/**
+ * usePanZoom hook - Unified pan and zoom gestures using @use-gesture/react
+ *
+ * Provides a declarative API for pan and zoom interactions on board components.
+ * Works with both SVG (via viewBox) and HTML (via CSS transforms) elements.
+ *
+ * Features:
+ * - Single finger/mouse drag for panning
+ * - Pinch-to-zoom on touch devices
+ * - Mouse wheel zoom on desktop
+ * - Configurable zoom limits
+ * - Optional momentum/inertia
+ *
+ * @example SVG usage (NetworkGraph, HexGrid, etc.)
+ * ```tsx
+ * const { transform, bind, resetTransform } = usePanZoom({
+ *   enabled: enablePanZoom,
+ *   minZoom: 0.5,
+ *   maxZoom: 3,
+ * });
+ *
+ * // Apply to viewBox calculation
+ * const viewBoxWidth = contentWidth / transform.zoom;
+ * const viewBoxX = baseX - transform.pan.x;
+ *
+ * <svg {...bind()} style={{ touchAction: 'none' }}>
+ *   ...
+ * </svg>
+ * ```
+ *
+ * @example HTML usage (SlotSystem, etc.)
+ * ```tsx
+ * const { transform, bind, style } = usePanZoom({
+ *   enabled: enablePanZoom,
+ *   mode: 'css',
+ * });
+ *
+ * <div {...bind()} style={{ ...style, touchAction: 'none' }}>
+ *   ...
+ * </div>
+ * ```
+ */
+export interface PanZoomTransform {
+    /** Current zoom level (1 = 100%) */
+    zoom: number;
+    /** Current pan offset */
+    pan: {
+        x: number;
+        y: number;
+    };
+}
+export interface UsePanZoomOptions {
+    /** Whether pan/zoom is enabled */
+    enabled?: boolean;
+    /** Initial zoom level */
+    initialZoom?: number;
+    /** Minimum zoom level */
+    minZoom?: number;
+    /** Maximum zoom level */
+    maxZoom?: number;
+    /** Initial pan offset */
+    initialPan?: {
+        x: number;
+        y: number;
+    };
+    /** Transform mode: 'viewbox' for SVG, 'css' for HTML elements */
+    mode?: "viewbox" | "css";
+    /** Zoom sensitivity for wheel events (default: 0.002) */
+    wheelSensitivity?: number;
+    /** Called when transform changes */
+    onTransformChange?: (transform: PanZoomTransform) => void;
+}
+/** Type for gesture bind function that returns props to spread on element
+ * Note: We omit ref from the return type to avoid conflicts with explicit refs on elements.
+ * The gesture library handles its own internal ref binding.
+ */
+type GestureBindFunction = () => Omit<React.HTMLAttributes<Element>, "ref">;
+export interface UsePanZoomReturn {
+    /** Current transform state */
+    transform: PanZoomTransform;
+    /** Gesture handlers to spread on the target element - always returns spreadable props */
+    bind: GestureBindFunction;
+    /** Reset transform to initial values */
+    resetTransform: () => void;
+    /** Set zoom programmatically */
+    setZoom: (zoom: number) => void;
+    /** Set pan programmatically */
+    setPan: (pan: {
+        x: number;
+        y: number;
+    }) => void;
+    /** CSS transform style (for mode: 'css') */
+    style: React.CSSProperties;
+    /** Whether currently dragging/panning */
+    isDragging: boolean;
+    /** Whether currently pinching */
+    isPinching: boolean;
+}
+/**
+ * Hook for pan and zoom gestures on board components
+ */
+export declare function usePanZoom(options?: UsePanZoomOptions): UsePanZoomReturn;
+/**
+ * Helper to calculate SVG viewBox with pan/zoom applied
+ */
+export declare function calculateViewBox(bounds: {
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+}, transform: PanZoomTransform): string;
+export {};
+//# sourceMappingURL=usePanZoom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePanZoom.d.ts","sourceRoot":"","sources":["../../src/hooks/usePanZoom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,iEAAiE;IACjE,IAAI,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IACzB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC3D;AAED;;;GAGG;AACH,KAAK,mBAAmB,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;AAE5E,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,yFAAyF;IACzF,IAAI,EAAE,mBAAmB,CAAC;IAC1B,wCAAwC;IACxC,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,gCAAgC;IAChC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,+BAA+B;IAC/B,MAAM,EAAE,CAAC,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChD,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC;IAC3B,yCAAyC;IACzC,UAAU,EAAE,OAAO,CAAC;IACpB,iCAAiC;IACjC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAgK5E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACrE,SAAS,EAAE,gBAAgB,GAC1B,MAAM,CASR"}

package/dist/hooks/usePanZoom.js

@@ -0,0 +1,165 @@
+/**
+ * usePanZoom hook - Unified pan and zoom gestures using @use-gesture/react
+ *
+ * Provides a declarative API for pan and zoom interactions on board components.
+ * Works with both SVG (via viewBox) and HTML (via CSS transforms) elements.
+ *
+ * Features:
+ * - Single finger/mouse drag for panning
+ * - Pinch-to-zoom on touch devices
+ * - Mouse wheel zoom on desktop
+ * - Configurable zoom limits
+ * - Optional momentum/inertia
+ *
+ * @example SVG usage (NetworkGraph, HexGrid, etc.)
+ * ```tsx
+ * const { transform, bind, resetTransform } = usePanZoom({
+ *   enabled: enablePanZoom,
+ *   minZoom: 0.5,
+ *   maxZoom: 3,
+ * });
+ *
+ * // Apply to viewBox calculation
+ * const viewBoxWidth = contentWidth / transform.zoom;
+ * const viewBoxX = baseX - transform.pan.x;
+ *
+ * <svg {...bind()} style={{ touchAction: 'none' }}>
+ *   ...
+ * </svg>
+ * ```
+ *
+ * @example HTML usage (SlotSystem, etc.)
+ * ```tsx
+ * const { transform, bind, style } = usePanZoom({
+ *   enabled: enablePanZoom,
+ *   mode: 'css',
+ * });
+ *
+ * <div {...bind()} style={{ ...style, touchAction: 'none' }}>
+ *   ...
+ * </div>
+ * ```
+ */
+import { useState, useCallback, useEffect, useMemo } from "react";
+import { useGesture } from "@use-gesture/react";
+/**
+ * Hook for pan and zoom gestures on board components
+ */
+export function usePanZoom(options = {}) {
+    const { enabled = true, initialZoom = 1, minZoom = 0.5, maxZoom = 3, initialPan = { x: 0, y: 0 }, mode = "viewbox", wheelSensitivity = 0.002, onTransformChange, } = options;
+    const [zoom, setZoomState] = useState(initialZoom);
+    const [pan, setPanState] = useState(initialPan);
+    const [isDragging, setIsDragging] = useState(false);
+    const [isPinching, setIsPinching] = useState(false);
+    // Clamp zoom to bounds
+    const clampZoom = useCallback((z) => Math.min(maxZoom, Math.max(minZoom, z)), [minZoom, maxZoom]);
+    // Update transform and notify
+    const updateTransform = useCallback((newZoom, newPan) => {
+        const clampedZoom = clampZoom(newZoom);
+        setZoomState(clampedZoom);
+        setPanState(newPan);
+        onTransformChange?.({ zoom: clampedZoom, pan: newPan });
+    }, [clampZoom, onTransformChange]);
+    // Gesture bindings
+    const bind = useGesture({
+        onDrag: (({ delta: [dx, dy], active, pinching, }) => {
+            if (!enabled || pinching)
+                return;
+            setIsDragging(active);
+            if (active) {
+                // For viewbox mode, we invert and scale the delta
+                // For CSS mode, we apply directly
+                const scaleFactor = mode === "viewbox" ? 1 / zoom : 1;
+                setPanState((prev) => ({
+                    x: prev.x + dx * scaleFactor,
+                    y: prev.y + dy * scaleFactor,
+                }));
+            }
+        }),
+        onPinch: (({ offset: [scale], active, }) => {
+            if (!enabled)
+                return;
+            setIsPinching(active);
+            if (active) {
+                const newZoom = clampZoom(scale);
+                setZoomState(newZoom);
+                onTransformChange?.({ zoom: newZoom, pan });
+            }
+        }),
+        onWheel: (({ delta: [, dy], event }) => {
+            if (!enabled)
+                return;
+            event.preventDefault();
+            const newZoom = clampZoom(zoom - dy * wheelSensitivity);
+            setZoomState(newZoom);
+            onTransformChange?.({ zoom: newZoom, pan });
+        }),
+    }, {
+        drag: {
+            enabled,
+            filterTaps: true,
+        },
+        pinch: {
+            enabled,
+            scaleBounds: { min: minZoom, max: maxZoom },
+            from: () => [zoom, 0],
+        },
+        wheel: {
+            enabled,
+            eventOptions: { passive: false },
+        },
+    });
+    // Reset to initial values
+    const resetTransform = useCallback(() => {
+        updateTransform(initialZoom, initialPan);
+    }, [initialZoom, initialPan, updateTransform]);
+    useEffect(() => {
+        updateTransform(initialZoom, initialPan);
+    }, [initialZoom, initialPan.x, initialPan.y, updateTransform]);
+    // Programmatic setters
+    const setZoom = useCallback((newZoom) => {
+        updateTransform(clampZoom(newZoom), pan);
+    }, [pan, clampZoom, updateTransform]);
+    const setPan = useCallback((newPan) => {
+        updateTransform(zoom, newPan);
+    }, [zoom, updateTransform]);
+    // CSS transform style for HTML mode
+    const style = useMemo(() => mode === "css"
+        ? {
+            transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
+            transformOrigin: "center center",
+        }
+        : {}, [mode, pan.x, pan.y, zoom]);
+    // Current transform state
+    const transform = useMemo(() => ({ zoom, pan }), [zoom, pan]);
+    // Wrap bind to ensure it always returns spreadable props (never void)
+    // We exclude 'ref' from the result to avoid type conflicts with explicit element refs
+    const safeBind = useCallback(() => {
+        const result = bind();
+        // If bind returns void (shouldn't happen with our config), return empty object
+        // Destructure to omit ref, avoiding type conflicts with SVG/HTML element refs
+        const { ref: _ref, ...propsWithoutRef } = (result ??
+            {});
+        return propsWithoutRef;
+    }, [bind]);
+    return {
+        transform,
+        bind: safeBind,
+        resetTransform,
+        setZoom,
+        setPan,
+        style,
+        isDragging,
+        isPinching,
+    };
+}
+/**
+ * Helper to calculate SVG viewBox with pan/zoom applied
+ */
+export function calculateViewBox(bounds, transform) {
+    const viewBoxWidth = bounds.width / transform.zoom;
+    const viewBoxHeight = bounds.height / transform.zoom;
+    const viewBoxX = bounds.minX + (bounds.width - viewBoxWidth) / 2 - transform.pan.x;
+    const viewBoxY = bounds.minY + (bounds.height - viewBoxHeight) / 2 - transform.pan.y;
+    return `${viewBoxX} ${viewBoxY} ${viewBoxWidth} ${viewBoxHeight}`;
+}

package/dist/hooks/usePlayerInfo.d.ts

@@ -0,0 +1,4 @@
+import type { PlayerId } from "@dreamboard/manifest-contract";
+import type { Player } from "./useMe.js";
+export declare function usePlayerInfo(): Map<PlayerId, Player>;
+//# sourceMappingURL=usePlayerInfo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePlayerInfo.d.ts","sourceRoot":"","sources":["../../src/hooks/usePlayerInfo.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAE9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,wBAAgB,aAAa,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAsBrD"}

package/dist/hooks/usePlayerInfo.js

@@ -0,0 +1,21 @@
+import { useMemo } from "react";
+import { useLobbyState } from "./useLobby.js";
+export function usePlayerInfo() {
+    const lobby = useLobbyState();
+    return useMemo(() => {
+        if (!lobby) {
+            return new Map();
+        }
+        const playerMap = new Map();
+        for (const seat of lobby.seats) {
+            const playerId = seat.playerId;
+            playerMap.set(playerId, {
+                playerId,
+                name: seat.displayName,
+                isHost: seat.isHost,
+                color: seat.playerColor,
+            });
+        }
+        return playerMap;
+    }, [lobby]);
+}

package/dist/hooks/usePlayerTurnOrder.d.ts

@@ -0,0 +1,15 @@
+import type { PlayerId } from "@dreamboard/manifest-contract";
+/**
+ * Returns the player ids in turn order, as provided by the lobby seat
+ * assignments. Matches `q.player.order()` on the reducer side: the
+ * engine's turn order is seeded from the same seat assignments.
+ *
+ * - Returns an empty array before the first lobby snapshot arrives.
+ * - Stable reference across renders when the seats don't change.
+ *
+ * Prefer this hook (combined with `useActivePlayers()` for the current
+ * seat) over re-projecting `turnOrder` into the view — flow state
+ * belongs to the engine and the SDK, not to game-specific projections.
+ */
+export declare function usePlayerTurnOrder(): readonly PlayerId[];
+//# sourceMappingURL=usePlayerTurnOrder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePlayerTurnOrder.d.ts","sourceRoot":"","sources":["../../src/hooks/usePlayerTurnOrder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAG9D;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,QAAQ,EAAE,CAMxD"}

package/dist/hooks/usePlayerTurnOrder.js

@@ -0,0 +1,22 @@
+import { useMemo } from "react";
+import { useLobby } from "./useLobby.js";
+/**
+ * Returns the player ids in turn order, as provided by the lobby seat
+ * assignments. Matches `q.player.order()` on the reducer side: the
+ * engine's turn order is seeded from the same seat assignments.
+ *
+ * - Returns an empty array before the first lobby snapshot arrives.
+ * - Stable reference across renders when the seats don't change.
+ *
+ * Prefer this hook (combined with `useActivePlayers()` for the current
+ * seat) over re-projecting `turnOrder` into the view — flow state
+ * belongs to the engine and the SDK, not to game-specific projections.
+ */
+export function usePlayerTurnOrder() {
+    const lobby = useLobby();
+    return useMemo(() => {
+        if (!lobby)
+            return [];
+        return lobby.seats.map((seat) => seat.playerId);
+    }, [lobby]);
+}

package/dist/hooks/usePluginRuntime.d.ts

@@ -0,0 +1,45 @@
+import { type PluginRuntimeAPI } from "../runtime/createPluginRuntimeAPI.js";
+export interface UsePluginRuntimeOptions {
+    /**
+     * Timeout in milliseconds to wait for state-sync.
+     * @default 10000 (10 seconds)
+     */
+    timeout?: number;
+}
+export interface UsePluginRuntimeResult {
+    /** The RuntimeAPI instance */
+    runtime: PluginRuntimeAPI;
+    /** Whether the initial reducer-native snapshot is available and ready */
+    isReady: boolean;
+    /** Error message if initialization failed */
+    error: string | null;
+}
+/**
+ * Hook that creates and manages a PluginRuntimeAPI instance.
+ *
+ * This hook handles:
+ * 1. Creating the RuntimeAPI
+ * 2. Waiting for the first state-sync snapshot before setting isReady
+ *
+ * In the new architecture, the host only renders the plugin when a reducer-native
+ * snapshot is available, so isReady should become true quickly after init.
+ *
+ * @example
+ * ```tsx
+ * function PluginRuntime({ children }: { children: React.ReactNode }) {
+ *   const { runtime, isReady, error } = usePluginRuntime();
+ *
+ *   if (error) {
+ *     return <div>Error: {error}</div>;
+ *   }
+ *
+ *   if (!isReady) {
+ *     return <GameSkeleton message="Waiting for game state..." />;
+ *   }
+ *
+ *   return <RuntimeProvider runtime={runtime}>{children}</RuntimeProvider>;
+ * }
+ * ```
+ */
+export declare function usePluginRuntime(options?: UsePluginRuntimeOptions): UsePluginRuntimeResult;
+//# sourceMappingURL=usePluginRuntime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePluginRuntime.d.ts","sourceRoot":"","sources":["../../src/hooks/usePluginRuntime.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,sCAAsC,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,8BAA8B;IAC9B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAkExB"}

package/dist/hooks/usePluginRuntime.js

@@ -0,0 +1,92 @@
+import { useState, useEffect } from "react";
+import { createPluginRuntimeAPI, } from "../runtime/createPluginRuntimeAPI.js";
+function hasProjectedView(snapshot) {
+    return (snapshot !== null &&
+        snapshot !== undefined &&
+        snapshot.view !== null &&
+        snapshot.view !== undefined);
+}
+/**
+ * Hook that creates and manages a PluginRuntimeAPI instance.
+ *
+ * This hook handles:
+ * 1. Creating the RuntimeAPI
+ * 2. Waiting for the first state-sync snapshot before setting isReady
+ *
+ * In the new architecture, the host only renders the plugin when a reducer-native
+ * snapshot is available, so isReady should become true quickly after init.
+ *
+ * @example
+ * ```tsx
+ * function PluginRuntime({ children }: { children: React.ReactNode }) {
+ *   const { runtime, isReady, error } = usePluginRuntime();
+ *
+ *   if (error) {
+ *     return <div>Error: {error}</div>;
+ *   }
+ *
+ *   if (!isReady) {
+ *     return <GameSkeleton message="Waiting for game state..." />;
+ *   }
+ *
+ *   return <RuntimeProvider runtime={runtime}>{children}</RuntimeProvider>;
+ * }
+ * ```
+ */
+export function usePluginRuntime(options = {}) {
+    const { timeout = 10000 } = options;
+    // Create runtime once and keep stable reference
+    const [runtime] = useState(() => createPluginRuntimeAPI());
+    const [isReady, setIsReady] = useState(() => {
+        const snapshot = runtime.getSnapshot?.();
+        return hasProjectedView(snapshot);
+    });
+    const [error, setError] = useState(null);
+    // Subscribe to state-sync and set isReady when the first snapshot arrives.
+    useEffect(() => {
+        const markReadyFromSnapshot = () => {
+            const currentSnapshot = runtime.getSnapshot?.();
+            if (!hasProjectedView(currentSnapshot)) {
+                return false;
+            }
+            setError(null);
+            setIsReady(true);
+            return true;
+        };
+        if (markReadyFromSnapshot()) {
+            return;
+        }
+        // Set up timeout
+        const timeoutId = setTimeout(() => {
+            if (!markReadyFromSnapshot()) {
+                setError(`Timed out waiting for the initial projected view after ${timeout}ms. ` +
+                    "Ensure the host sends a reducer-native state-sync with a seat view.");
+            }
+        }, timeout);
+        // Fallback poll for dev/HMR flows where the runtime snapshot may already
+        // exist but the first subscribe callback is missed.
+        const pollId = setInterval(() => {
+            if (markReadyFromSnapshot()) {
+                clearInterval(pollId);
+                clearTimeout(timeoutId);
+            }
+        }, 100);
+        // Subscribe to state changes
+        const unsubscribe = runtime.subscribeToState?.((state) => {
+            if (!hasProjectedView(state)) {
+                setIsReady(false);
+                return;
+            }
+            clearInterval(pollId);
+            clearTimeout(timeoutId);
+            setError(null);
+            setIsReady(true);
+        });
+        return () => {
+            clearInterval(pollId);
+            clearTimeout(timeoutId);
+            unsubscribe?.();
+        };
+    }, [runtime, timeout]);
+    return { runtime, isReady, error };
+}