@dreamboard-games/ui-sdk 0.0.41

package/src/context/InteractionDraftContext.tsx

@@ -0,0 +1,204 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { useStore } from "zustand";
+import { createStore, type StoreApi } from "zustand/vanilla";
+import { useShallow } from "zustand/shallow";
+
+type Draft = Readonly<Record<string, unknown>>;
+
+const EMPTY_DRAFT: Draft = Object.freeze({});
+
+interface DraftState {
+  drafts: Readonly<Record<string, Draft>>;
+  arms: Readonly<Record<string, string>>;
+  submitting: Readonly<Record<string, true>>;
+}
+
+/**
+ * Imperative API exposed to `useInteractionHandle` and `<BoardSurface>`.
+ * Intentionally small; the vanilla zustand store underneath powers
+ * fine-grained subscriptions via {@link useDraft} and {@link useArmed}.
+ */
+export interface InteractionUiStore {
+  /** Read the current draft for an interaction id. Never undefined. */
+  getDraft(interactionId: string): Draft;
+  /** Merge a single input key into the draft. Creates the draft if needed. */
+  setInput(interactionId: string, key: string, value: unknown): void;
+  /** Clear a single input, or the whole draft if `key` is omitted. */
+  clearInput(interactionId: string, key?: string): void;
+  /** Clear every draft and arming state. */
+  clearAll(): void;
+  /** Which interaction (if any) is currently armed on the given surface. */
+  getArmed(surface: string): string | null;
+  /** Arm a specific interaction on a surface. Pass `null` to disarm. */
+  arm(surface: string, interactionId: string | null): void;
+  /** True while a local submission is in flight before the host echo arrives. */
+  isSubmitting(interactionId: string): boolean;
+  /** Mark or clear a local submission in flight. */
+  setSubmitting(interactionId: string, submitting: boolean): void;
+}
+
+/** Vanilla zustand store implementing {@link InteractionUiStore}. */
+export type InteractionUiStoreApi = StoreApi<DraftState> & InteractionUiStore;
+
+export function createInteractionUiStore(): InteractionUiStoreApi {
+  const store = createStore<DraftState>()(() => ({
+    drafts: {},
+    arms: {},
+    submitting: {},
+  }));
+
+  const api: InteractionUiStore = {
+    getDraft(interactionId) {
+      return store.getState().drafts[interactionId] ?? EMPTY_DRAFT;
+    },
+    setInput(interactionId, key, value) {
+      store.setState((prev) => {
+        const current = prev.drafts[interactionId];
+        if (current && current[key] === value) return prev;
+        return {
+          ...prev,
+          drafts: {
+            ...prev.drafts,
+            [interactionId]: { ...(current ?? {}), [key]: value },
+          },
+        };
+      });
+    },
+    clearInput(interactionId, key) {
+      store.setState((prev) => {
+        const current = prev.drafts[interactionId];
+        if (!current) return prev;
+        if (key === undefined) {
+          const { [interactionId]: _omit, ...rest } = prev.drafts;
+          return { ...prev, drafts: rest };
+        }
+        if (!(key in current)) return prev;
+        const { [key]: _omitKey, ...remainingKeys } = current;
+        if (Object.keys(remainingKeys).length === 0) {
+          const { [interactionId]: _omit, ...rest } = prev.drafts;
+          return { ...prev, drafts: rest };
+        }
+        return {
+          ...prev,
+          drafts: { ...prev.drafts, [interactionId]: remainingKeys },
+        };
+      });
+    },
+    clearAll() {
+      store.setState((prev) => {
+        if (
+          Object.keys(prev.drafts).length === 0 &&
+          Object.keys(prev.arms).length === 0 &&
+          Object.keys(prev.submitting).length === 0
+        ) {
+          return prev;
+        }
+        return { drafts: {}, arms: {}, submitting: {} };
+      });
+    },
+    getArmed(surface) {
+      return store.getState().arms[surface] ?? null;
+    },
+    arm(surface, interactionId) {
+      store.setState((prev) => {
+        const current = prev.arms[surface] ?? null;
+        if (current === interactionId) return prev;
+        if (interactionId === null) {
+          const { [surface]: _omit, ...rest } = prev.arms;
+          return { ...prev, arms: rest };
+        }
+        return { ...prev, arms: { ...prev.arms, [surface]: interactionId } };
+      });
+    },
+    isSubmitting(interactionId) {
+      return store.getState().submitting[interactionId] === true;
+    },
+    setSubmitting(interactionId, submitting) {
+      store.setState((prev) => {
+        const current = prev.submitting[interactionId] === true;
+        if (current === submitting) return prev;
+        if (!submitting) {
+          const { [interactionId]: _omit, ...rest } = prev.submitting;
+          return { ...prev, submitting: rest };
+        }
+        return {
+          ...prev,
+          submitting: { ...prev.submitting, [interactionId]: true },
+        };
+      });
+    },
+  };
+
+  return Object.assign(store, api);
+}
+
+const InteractionUiCtx = createContext<InteractionUiStoreApi | null>(null);
+
+/**
+ * React provider that holds draft input state shared across every surface
+ * inside the tree. Auto-installed by `<PluginRuntime>`; authors rarely
+ * mount it directly. Mount manually when rendering surface components in
+ * isolation (e.g., Storybook, snapshot tests).
+ *
+ * ```tsx
+ * <InteractionUiProvider>
+ *   <PanelSurface />
+ *   <BoardSurface>{(ctx) => <Board ctx={ctx} />}</BoardSurface>
+ * </InteractionUiProvider>
+ * ```
+ */
+export function InteractionUiProvider({
+  children,
+  store,
+}: {
+  children: ReactNode;
+  store?: InteractionUiStoreApi;
+}) {
+  const ownedStore = useMemo(() => createInteractionUiStore(), []);
+  return (
+    <InteractionUiCtx.Provider value={store ?? ownedStore}>
+      {children}
+    </InteractionUiCtx.Provider>
+  );
+}
+
+/**
+ * Access the active draft store. Falls back to an inert in-memory store
+ * when no provider is mounted, so surface hooks remain callable in bare
+ * test harnesses without crashing — draft state simply isn't shared
+ * across components in that case.
+ */
+export function useInteractionUiStore(): InteractionUiStoreApi {
+  const ctx = useContext(InteractionUiCtx);
+  const fallback = useMemo(() => createInteractionUiStore(), []);
+  return ctx ?? fallback;
+}
+
+/**
+ * Subscribe to the draft for a single interaction id with per-slice
+ * re-renders. Returns a stable empty object when the draft is unset.
+ */
+export function useInteractionDraft(interactionId: string): Draft {
+  const store = useInteractionUiStore();
+  return useStore(
+    store,
+    useShallow(
+      (state: DraftState) => state.drafts[interactionId] ?? EMPTY_DRAFT,
+    ),
+  );
+}
+
+/** Subscribe to the armed interaction id on a given surface. */
+export function useArmedInteraction(surface: string): string | null {
+  const store = useInteractionUiStore();
+  return useStore(store, (state: DraftState) => state.arms[surface] ?? null);
+}
+
+/** Subscribe to local submitting status for a single interaction key. */
+export function useInteractionSubmitting(interactionId: string): boolean {
+  const store = useInteractionUiStore();
+  return useStore(
+    store,
+    (state: DraftState) => state.submitting[interactionId] === true,
+  );
+}

package/src/context/PluginSessionContext.tsx

@@ -0,0 +1,47 @@
+import { createContext, useContext } from "react";
+import type { PluginSessionState } from "../types/runtime-api";
+
+/**
+ * Context for plugin session metadata.
+ * This context is provided by the RuntimeContext after receiving init message from parent.
+ */
+export const PluginSessionContext = createContext<PluginSessionState | null>(
+  null,
+);
+
+/**
+ * Hook to access plugin session metadata.
+ * Returns session initialization status and IDs.
+ *
+ * @returns Plugin session state with status, sessionId, controllablePlayerIds, and controllingPlayerId
+ *
+ * @example
+ * ```tsx
+ * function MyPluginComponent() {
+ *   const { status, sessionId, controllablePlayerIds, controllingPlayerId } = usePluginSession();
+ *
+ *   if (status === "loading") {
+ *     return <div>Initializing...</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Session: {sessionId}</p>
+ *       <p>Can control: {controllablePlayerIds.join(", ")}</p>
+ *       <p>Currently controlling: {controllingPlayerId}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePluginSession(): PluginSessionState {
+  const context = useContext(PluginSessionContext);
+
+  if (context === null) {
+    throw new Error(
+      "usePluginSession must be used within a PluginSessionContext.Provider (provided by RuntimeContext)",
+    );
+  }
+
+  return context;
+}

package/src/context/PluginStateContext.tsx

@@ -0,0 +1,254 @@
+import {
+  default as React,
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from "react";
+import type { PluginStateSnapshot } from "../types/plugin-state.js";
+import { useRuntimeContext } from "./RuntimeContext.js";
+import type { PluginRuntimeAPI } from "../runtime/createPluginRuntimeAPI.js";
+
+/**
+ * React Context for providing plugin state from state-sync messages.
+ * This is the new architecture where the host app maintains state and syncs to plugin.
+ */
+const PluginStateContext = createContext<PluginStateSnapshot | null>(null);
+
+/**
+ * Loading component shown while waiting for initial state
+ */
+function DefaultLoadingScreen() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        height: "100%",
+        width: "100%",
+        color: "#666",
+      }}
+    >
+      <div style={{ textAlign: "center" }}>
+        <div
+          style={{
+            width: "40px",
+            height: "40px",
+            border: "3px solid #e0e0e0",
+            borderTopColor: "#666",
+            borderRadius: "50%",
+            animation: "spin 1s linear infinite",
+            margin: "0 auto 12px",
+          }}
+        />
+        <style>{`@keyframes spin { to { transform: rotate(360deg); } }`}</style>
+        <p>Loading game view...</p>
+      </div>
+    </div>
+  );
+}
+
+export interface PluginStateProviderProps {
+  children: React.ReactNode;
+  /**
+   * Custom loading component to show while waiting for state
+   * @default DefaultLoadingScreen
+   */
+  loadingComponent?: React.ReactNode;
+}
+
+/**
+ * PluginStateProvider subscribes to state-sync messages from the host
+ * and provides the state to child components via context.
+ *
+ * In the new architecture:
+ * - Host only renders authored game UI after state-sync begins
+ * - Plugin receives complete state in first state-sync message
+ * - No buffering or waiting needed - state is immediately available
+ *
+ * This replaces the complex usePluginRuntime hook which had:
+ * - waitForGameStart() promise handling
+ * - finishSetup() coordination with queueMicrotask
+ * - Error timeout handling
+ *
+ * @example
+ * ```tsx
+ * function PluginRoot() {
+ *   return (
+ *     <RuntimeProvider runtime={runtime}>
+ *       <PluginStateProvider>
+ *         <App />
+ *       </PluginStateProvider>
+ *     </RuntimeProvider>
+ *   );
+ * }
+ * ```
+ */
+export function PluginStateProvider({
+  children,
+  loadingComponent = <DefaultLoadingScreen />,
+}: PluginStateProviderProps) {
+  const runtime = useRuntimeContext() as PluginRuntimeAPI;
+  const [state, setState] = useState<PluginStateSnapshot | null>(
+    () => runtime.getSnapshot?.() ?? null,
+  );
+
+  useEffect(() => {
+    // Get initial state if available
+    const initialState = runtime.getSnapshot?.();
+    if (initialState) {
+      setState(initialState);
+    }
+
+    // Subscribe to state changes
+    if (runtime.subscribeToState) {
+      return runtime.subscribeToState((newState) => {
+        setState(newState);
+      });
+    }
+
+    return () => {};
+  }, [runtime]);
+
+  // Don't render children until state is available
+  // In the new architecture, host guarantees state exists before rendering plugin
+  if (!state) {
+    return <>{loadingComponent}</>;
+  }
+
+  return (
+    <PluginStateContext.Provider value={state}>
+      {children}
+    </PluginStateContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the full plugin state snapshot.
+ *
+ * @throws Error if used outside of PluginStateProvider
+ * @returns Current plugin state snapshot
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const state = usePluginStateSnapshot();
+ *   console.log('Current phase:', state.gameplay.currentPhase);
+ * }
+ * ```
+ */
+export function usePluginStateSnapshot(): PluginStateSnapshot {
+  const state = useContext(PluginStateContext);
+
+  if (!state) {
+    throw new Error(
+      "usePluginStateSnapshot must be used within PluginStateProvider. " +
+        "Make sure you have wrapped your app with <PluginStateProvider>.",
+    );
+  }
+
+  return state;
+}
+
+/**
+ * Hook to select a specific part of the plugin state.
+ * Uses useSyncExternalStore for optimal performance - only re-renders
+ * when the selected value changes (using reference equality).
+ *
+ * @param selector - Function to select a part of the state
+ * @returns Selected value from state
+ *
+ * @example
+ * ```typescript
+ * // Only re-renders when gameplay.currentPhase changes
+ * function CurrentStateDisplay() {
+ *   const currentState = usePluginState((s) => s.gameplay.currentPhase);
+ *   return <div>State: {currentState}</div>;
+ * }
+ * ```
+ */
+export function usePluginState<T>(
+  selector: (state: PluginStateSnapshot) => T,
+): T {
+  const runtime = useRuntimeContext() as PluginRuntimeAPI;
+
+  const subscribe = (onStoreChange: () => void) => {
+    if (!runtime.subscribeToState) {
+      return () => {};
+    }
+    return runtime.subscribeToState(() => {
+      onStoreChange();
+    });
+  };
+
+  const getSnapshot = () => {
+    const state = runtime.getSnapshot?.();
+    if (!state) {
+      throw new Error(
+        "usePluginState: No state available. " +
+          "Make sure you have wrapped your app with <PluginStateProvider>.",
+      );
+    }
+    return state;
+  };
+
+  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return useMemo(() => selector(state), [selector, state]);
+}
+
+/**
+ * Hook to access plugin actions (like marking notifications read).
+ *
+ * @returns Object with action functions
+ *
+ * @example
+ * ```typescript
+ * function NotificationsList() {
+ *   const notifications = usePluginState((s) => s.notifications);
+ *   const { markNotificationRead, switchPlayer } = usePluginActions();
+ *
+ *   return (
+ *     <ul>
+ *       {notifications.map((n) => (
+ *         <li key={n.id} onClick={() => markNotificationRead(n.id)}>
+ *           {n.type}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function usePluginActions() {
+  const runtime = useRuntimeContext() as PluginRuntimeAPI;
+
+  return {
+    /**
+     * Mark a notification as read.
+     * Sends message to host which updates the notification in GameSessionStore.
+     */
+    markNotificationRead: (notificationId: string) => {
+      window.parent.postMessage(
+        { type: "mark-notification-read", notificationId },
+        "*",
+      );
+    },
+
+    /**
+     * Switch to a different player (for users controlling multiple seats).
+     */
+    switchPlayer: (playerId: string) => {
+      runtime.switchPlayer?.(playerId);
+    },
+
+    /**
+     * Submit a player interaction (action or prompt response).
+     */
+    submitInteraction: runtime.submitInteraction,
+  };
+}
+
+export { PluginStateContext };

package/src/context/RuntimeContext.tsx

@@ -0,0 +1,96 @@
+import React, { createContext, useContext, useState, useEffect } from "react";
+import type { RuntimeAPI, PluginSessionState } from "../types/runtime-api.js";
+import { PluginSessionContext } from "./PluginSessionContext.js";
+
+/**
+ * React Context for providing RuntimeAPI to plugin components.
+ * This context must be provided by the plugin wrapper, not by the plugin code itself.
+ */
+export const RuntimeContext = createContext<RuntimeAPI | null>(null);
+
+/**
+ * Hook to access the RuntimeAPI from context.
+ *
+ * @throws Error if used outside of RuntimeContext.Provider
+ * @returns RuntimeAPI instance
+ *
+ * @example
+ * ```typescript
+ * function MyPluginComponent() {
+ *   const runtime = useRuntimeContext();
+ *   return (
+ *     <button onClick={() => runtime.submitInteraction("player-1", "pass", {})}>
+ *       Pass
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useRuntimeContext(): RuntimeAPI {
+  const context = useContext(RuntimeContext);
+
+  if (!context) {
+    throw new Error(
+      "useRuntimeContext must be used within a RuntimeContext.Provider",
+    );
+  }
+
+  return context;
+}
+
+/**
+ * RuntimeProvider component that provides both RuntimeAPI and PluginSessionContext.
+ * This component subscribes to session state changes from the RuntimeAPI and provides
+ * them through PluginSessionContext.
+ *
+ * @example
+ * ```tsx
+ * function PluginRoot() {
+ *   const runtime = createPluginRuntimeAPI();
+ *
+ *   return (
+ *     <RuntimeProvider runtime={runtime}>
+ *       <App />
+ *     </RuntimeProvider>
+ *   );
+ * }
+ * ```
+ */
+export function RuntimeProvider({
+  runtime,
+  children,
+}: {
+  runtime: RuntimeAPI;
+  children: React.ReactNode;
+}) {
+  // Subscribe to session state changes
+  const [sessionState, setSessionState] = useState<PluginSessionState>(() =>
+    runtime.getSessionState(),
+  );
+
+  useEffect(() => {
+    // Subscribe to session state changes via internal API
+    const runtimeWithInternal = runtime as RuntimeAPI & {
+      _subscribeToSessionState?: (
+        listener: (state: PluginSessionState) => void,
+      ) => () => void;
+    };
+
+    if (runtimeWithInternal._subscribeToSessionState) {
+      return runtimeWithInternal._subscribeToSessionState((state) => {
+        setSessionState(state);
+      });
+    }
+
+    // Fallback: no session state subscription available
+    return () => {};
+  }, [runtime]);
+
+  return (
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={sessionState}>
+        {children}
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>
+  );
+}