@dreamboard-games/ui-sdk 0.0.41

package/src/hooks/useMe.ts

@@ -0,0 +1,48 @@
+import { useMemo } from "react";
+import type { PlayerId } from "@dreamboard/manifest-contract";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { useLobby } from "./useLobby.js";
+import type { Player } from "../types/player-state.js";
+
+// Re-export for consumers
+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 function useMe(): Player {
+  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 as PlayerId,
+      name: seat.displayName,
+      isHost: seat.isHost,
+      color: seat.playerColor,
+    };
+  }, [controllingPlayerId, lobby]);
+}

package/src/hooks/usePanZoom.ts

@@ -0,0 +1,278 @@
+/**
+ * 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, type Handler } from "@use-gesture/react";
+
+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 function usePanZoom(options: UsePanZoomOptions = {}): UsePanZoomReturn {
+  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: number) => Math.min(maxZoom, Math.max(minZoom, z)),
+    [minZoom, maxZoom],
+  );
+
+  // Update transform and notify
+  const updateTransform = useCallback(
+    (newZoom: number, newPan: { x: number; y: number }) => {
+      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,
+      }: Parameters<Handler<"drag">>[0]) => {
+        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,
+          }));
+        }
+      }) as Handler<"drag">,
+      onPinch: (({
+        offset: [scale],
+        active,
+      }: Parameters<Handler<"pinch">>[0]) => {
+        if (!enabled) return;
+
+        setIsPinching(active);
+
+        if (active) {
+          const newZoom = clampZoom(scale);
+          setZoomState(newZoom);
+          onTransformChange?.({ zoom: newZoom, pan });
+        }
+      }) as Handler<"pinch">,
+      onWheel: (({ delta: [, dy], event }: Parameters<Handler<"wheel">>[0]) => {
+        if (!enabled) return;
+
+        event.preventDefault();
+        const newZoom = clampZoom(zoom - dy * wheelSensitivity);
+        setZoomState(newZoom);
+        onTransformChange?.({ zoom: newZoom, pan });
+      }) as Handler<"wheel">,
+    },
+    {
+      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: number) => {
+      updateTransform(clampZoom(newZoom), pan);
+    },
+    [pan, clampZoom, updateTransform],
+  );
+
+  const setPan = useCallback(
+    (newPan: { x: number; y: number }) => {
+      updateTransform(zoom, newPan);
+    },
+    [zoom, updateTransform],
+  );
+
+  // CSS transform style for HTML mode
+  const style = useMemo<React.CSSProperties>(
+    () =>
+      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<PanZoomTransform>(
+    () => ({ 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: GestureBindFunction = 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 ??
+      {}) as React.HTMLAttributes<Element> & { ref?: unknown };
+    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: { minX: number; minY: number; width: number; height: number },
+  transform: PanZoomTransform,
+): string {
+  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/src/hooks/usePlayerInfo.ts

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

package/src/hooks/usePlayerTurnOrder.ts

@@ -0,0 +1,23 @@
+import { useMemo } from "react";
+import type { PlayerId } from "@dreamboard/manifest-contract";
+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(): readonly PlayerId[] {
+  const lobby = useLobby();
+  return useMemo(() => {
+    if (!lobby) return [];
+    return lobby.seats.map((seat) => seat.playerId as PlayerId);
+  }, [lobby]);
+}

package/src/hooks/usePluginRuntime.test.tsx

@@ -0,0 +1,102 @@
+import { afterEach, expect, mock, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import type { PluginStateSnapshot } from "../types/plugin-state.js";
+import type { PluginSessionState } from "../types/runtime-api.js";
+
+const actualCreatePluginRuntimeModule = await import(
+  "../runtime/createPluginRuntimeAPI.js"
+);
+
+type RuntimeModule = typeof actualCreatePluginRuntimeModule;
+
+const createPluginRuntimeApiMock = mock();
+
+mock.module("../runtime/createPluginRuntimeAPI.js", () => ({
+  ...(actualCreatePluginRuntimeModule as RuntimeModule),
+  createPluginRuntimeAPI: createPluginRuntimeApiMock,
+}));
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createSnapshot(
+  view: PluginStateSnapshot["view"],
+): PluginStateSnapshot {
+  return {
+    view,
+    gameplay: {
+      currentPhase: "setup",
+      currentStage: null,
+      activePlayers: ["player-1"],
+      availableInteractions: [],
+      zones: {},
+    },
+    lobby: null,
+    notifications: [],
+    session: createSessionState(),
+    history: null,
+    syncId: 1,
+  };
+}
+
+function createRuntime(snapshot: PluginStateSnapshot) {
+  return {
+    validateInteraction: async () => ({ valid: true }),
+    submitInteraction: async () => undefined,
+    getSessionState: () => snapshot.session,
+    disconnect: () => undefined,
+    getSnapshot: () => snapshot,
+    subscribeToState: () => () => undefined,
+  };
+}
+
+async function loadUsePluginRuntime() {
+  return import(`./usePluginRuntime.ts?test=${Math.random()}`);
+}
+
+afterEach(() => {
+  createPluginRuntimeApiMock.mockReset();
+});
+
+test("usePluginRuntime stays unready when the initial snapshot has no projected view", async () => {
+  createPluginRuntimeApiMock.mockReturnValue(
+    createRuntime(createSnapshot(null)),
+  );
+  const { usePluginRuntime } = await loadUsePluginRuntime();
+  let captured: ReturnType<typeof usePluginRuntime> | null = null;
+
+  function Harness() {
+    captured = usePluginRuntime();
+    return null;
+  }
+
+  renderToString(<Harness />);
+
+  expect(captured?.isReady).toBe(false);
+  expect(captured?.error).toBeNull();
+});
+
+test("usePluginRuntime is ready when the initial snapshot already has a projected view", async () => {
+  createPluginRuntimeApiMock.mockReturnValue(
+    createRuntime(createSnapshot({ board: "ready" })),
+  );
+  const { usePluginRuntime } = await loadUsePluginRuntime();
+  let captured: ReturnType<typeof usePluginRuntime> | null = null;
+
+  function Harness() {
+    captured = usePluginRuntime();
+    return null;
+  }
+
+  renderToString(<Harness />);
+
+  expect(captured?.isReady).toBe(true);
+  expect(captured?.error).toBeNull();
+});

package/src/hooks/usePluginRuntime.ts

@@ -0,0 +1,130 @@
+import { useState, useEffect } from "react";
+import {
+  createPluginRuntimeAPI,
+  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;
+}
+
+function hasProjectedView(
+  snapshot: ReturnType<PluginRuntimeAPI["getSnapshot"]> | null | undefined,
+): boolean {
+  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: UsePluginRuntimeOptions = {},
+): UsePluginRuntimeResult {
+  const { timeout = 10000 } = options;
+
+  // Create runtime once and keep stable reference
+  const [runtime] = useState<PluginRuntimeAPI>(() => createPluginRuntimeAPI());
+  const [isReady, setIsReady] = useState(() => {
+    const snapshot = runtime.getSnapshot?.();
+    return hasProjectedView(snapshot);
+  });
+  const [error, setError] = useState<string | null>(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 };
+}

package/src/hooks/useSeatInbox.ts

@@ -0,0 +1,61 @@
+import { usePluginState } from "../context/PluginStateContext.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import {
+  eligibleTargetsByBoardKind,
+  hasBoardTargetInput,
+} from "../utils/interaction-inputs.js";
+
+/**
+ * Structured inbox view of the controlling seat's available interactions.
+ * Interactions are grouped into UI behavior buckets. Prompt-kind interactions
+ * (authored via `promptInput(...)`) surface at `bySurface.inbox`.
+ */
+export interface SeatInbox {
+  /** Interactions grouped by derived UI bucket id. */
+  bySurface: Record<string, readonly InteractionDescriptor[]>;
+  /** Prompt-kind interactions addressed to the controlling seat. */
+  prompts: readonly InteractionDescriptor[];
+  /** Flat list of all available interactions (ungrouped). */
+  all: readonly InteractionDescriptor[];
+}
+
+/**
+ * Returns the controlling seat's available interactions grouped by UI bucket.
+ * Prompt-kind interactions (authored via `promptInput(...)`) appear both in
+ * `bySurface.inbox` and in `prompts`. Backed by authoritative descriptors
+ * from the trusted bundle — clients MUST NOT recompute availability.
+ */
+export function useSeatInbox(): SeatInbox {
+  const interactions = usePluginState(
+    (s) => s.gameplay.availableInteractions ?? [],
+  );
+
+  const bySurface: Record<string, InteractionDescriptor[]> = {};
+  const prompts: InteractionDescriptor[] = [];
+  for (const descriptor of interactions) {
+    const surface = bucketForDescriptor(descriptor);
+    (bySurface[surface] ??= []).push(descriptor);
+    if (descriptor.kind === "prompt") {
+      prompts.push(descriptor);
+    }
+  }
+
+  return {
+    bySurface,
+    prompts,
+    all: interactions,
+  };
+}
+
+function bucketForDescriptor(descriptor: InteractionDescriptor): string {
+  if (descriptor.kind === "prompt") return "inbox";
+  if (descriptor.zoneId) return "hand";
+  if (hasBoardTargetInput(descriptor)) {
+    const byKind = eligibleTargetsByBoardKind(descriptor);
+    if (byKind.vertex) return "board-vertex";
+    if (byKind.edge) return "board-edge";
+    if (byKind.tile) return "board-tile";
+    if (byKind.space) return "board-space";
+  }
+  return "panel";
+}

package/src/hooks/useSimultaneousPhase.ts

@@ -0,0 +1,10 @@
+import { usePluginState } from "../context/PluginStateContext.js";
+import type { SimultaneousPhaseSnapshot } from "../types/plugin-state.js";
+
+/**
+ * Returns visibility-safe progress metadata for the active simultaneous-player
+ * phase, or null when no simultaneous submission barrier is active.
+ */
+export function useSimultaneousPhase(): SimultaneousPhaseSnapshot | null {
+  return usePluginState((state) => state.gameplay.simultaneousPhase ?? null);
+}