@dreamboard-games/sdk 0.2.0

package/src/runtime-internal/components/PluginRuntime.tsx

@@ -0,0 +1,103 @@
+import React from "react";
+import { InteractionUiProvider } from "../context/InteractionDraftContext.js";
+import { RuntimeProvider } from "../context/RuntimeContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { usePluginRuntime } from "../hooks/usePluginRuntime.js";
+import { GameSkeleton } from "../../ui.js";
+
+export interface PluginRuntimeProps {
+  /** Child components to render after state sync has started */
+  children: React.ReactNode;
+  /**
+   * Timeout in milliseconds to wait for the first state-sync snapshot.
+   * @default 10000 (10 seconds)
+   */
+  timeout?: number;
+  /** Custom loading component to show while waiting for state sync */
+  loadingComponent?: React.ReactNode;
+  /** Custom error component to show when initialization fails */
+  errorComponent?: (error: string) => React.ReactNode;
+}
+
+/**
+ * PluginRuntime provides the RuntimeContext for plugin components.
+ *
+ * This component:
+ * - Creates a RuntimeAPI instance using the SDK-provided implementation
+ * - Waits for the first reducer-native state-sync snapshot before rendering children
+ * - Provides RuntimeAPI and session state to all child components
+ *
+ * @example
+ * ```tsx
+ * // In your plugin's index.tsx
+ * import { PluginRuntime } from "./components/dreamboard";
+ * import App from './App';
+ *
+ * ReactDOM.createRoot(document.getElementById('root')!).render(
+ *   <PluginRuntime>
+ *     <App />
+ *   </PluginRuntime>
+ * );
+ * ```
+ */
+export function PluginRuntime({
+  children,
+  timeout = 10000,
+  loadingComponent,
+  errorComponent,
+}: PluginRuntimeProps) {
+  const { runtime, isReady, waiting, error } = usePluginRuntime({ timeout });
+
+  if (error) {
+    if (errorComponent) {
+      return <>{errorComponent(error)}</>;
+    }
+    return (
+      <div className="flex h-full w-full items-center justify-center bg-gray-50">
+        <div className="text-center p-6">
+          <p className="text-red-600 font-medium mb-2">Failed to load game</p>
+          <p className="text-gray-600 text-sm">{error}</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (!isReady) {
+    if (loadingComponent) {
+      return <>{loadingComponent}</>;
+    }
+    // Once the game has rendered, a view-less snapshot is a mid-game wait (you
+    // acted and are waiting on the table), not a cold load — say so rather than
+    // reading as a stalled "Waiting for game state".
+    return (
+      <GameSkeleton
+        message={
+          waiting
+            ? "Waiting for the other players…"
+            : "Waiting for game state..."
+        }
+      />
+    );
+  }
+
+  return (
+    <RuntimeProvider runtime={runtime}>
+      <SessionScopedInteractionUiProvider>
+        {children}
+      </SessionScopedInteractionUiProvider>
+    </RuntimeProvider>
+  );
+}
+
+function SessionScopedInteractionUiProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const { controllingPlayerId } = usePluginSession();
+  return (
+    <InteractionUiProvider key={controllingPlayerId ?? "__no_player__"}>
+      {children}
+    </InteractionUiProvider>
+  );
+}

package/src/runtime-internal/components/board/target-layer.ts

@@ -0,0 +1,70 @@
+import type { BoardTargetKind } from "../../utils/interaction-inputs.js";
+
+export interface InteractiveTargetState {
+  kind?: BoardTargetKind;
+  id: string;
+  eligible: boolean;
+  selectable: boolean;
+  hovered: boolean;
+  interactionKey?: string;
+  interactionId?: string;
+  inputKey?: string;
+  pending: boolean;
+  conflict: boolean;
+  conflictInteractionKeys?: readonly string[];
+  unavailableReason?: string;
+  select?: () => unknown | Promise<unknown>;
+}
+
+export interface InteractiveTargetLayer {
+  enabled?: boolean;
+  eligible?: ReadonlySet<string>;
+  selectTargetId?: (targetId: string) => unknown | Promise<unknown>;
+  targetState?: (targetId: string) => Partial<InteractiveTargetState>;
+}
+
+export interface InteractiveTargetRenderState extends InteractiveTargetState {
+  isEnabled: boolean;
+  isEligible: boolean;
+  isHovered: boolean;
+}
+
+export function interactiveTargetRenderState(
+  layer: InteractiveTargetLayer,
+  targetId: string,
+  isHovered: boolean,
+): InteractiveTargetRenderState {
+  const enabled = layer.enabled !== false;
+  const eligible = layer.eligible?.has(targetId) ?? true;
+  const extra = layer.targetState?.(targetId) ?? {};
+  const selectable =
+    extra.selectable ?? (enabled && eligible && !!layer.selectTargetId);
+  return {
+    id: targetId,
+    ...extra,
+    eligible: extra.eligible ?? eligible,
+    selectable,
+    hovered: isHovered,
+    pending: extra.pending ?? false,
+    conflict: extra.conflict ?? false,
+    select:
+      extra.select ??
+      (layer.selectTargetId
+        ? () => layer.selectTargetId?.(targetId)
+        : undefined),
+    isEnabled: enabled,
+    isEligible: extra.eligible ?? eligible,
+    isHovered,
+  };
+}
+
+export function isInteractiveTargetSelectable(
+  layer: InteractiveTargetLayer,
+  state: InteractiveTargetRenderState,
+): boolean {
+  return (
+    state.isEnabled &&
+    state.selectable &&
+    !!(state.select ?? layer.selectTargetId)
+  );
+}

package/src/runtime-internal/context/ClientParamSchemaContext.tsx

@@ -0,0 +1,44 @@
+import { createContext, useContext } from "react";
+
+export interface ClientParamSchema {
+  safeParse: (value: unknown) =>
+    | { success: true; data: Record<string, unknown> }
+    | {
+        success: false;
+        error: {
+          issues: ReadonlyArray<{
+            path: readonly PropertyKey[];
+            message: string;
+          }>;
+        };
+      };
+}
+
+export type ClientParamSchemaMap = Readonly<
+  Record<string, Readonly<Record<string, ClientParamSchema>>>
+>;
+
+const ClientParamSchemaContext = createContext<ClientParamSchemaMap>({});
+
+export function ClientParamSchemaProvider({
+  schemas,
+  children,
+}: {
+  schemas?: ClientParamSchemaMap;
+  children: React.ReactNode;
+}) {
+  return (
+    <ClientParamSchemaContext.Provider value={schemas ?? {}}>
+      {children}
+    </ClientParamSchemaContext.Provider>
+  );
+}
+
+export function useClientParamSchema(
+  phaseName: string | null | undefined,
+  interactionId: string,
+): ClientParamSchema | undefined {
+  const schemas = useContext(ClientParamSchemaContext);
+  if (!phaseName) return undefined;
+  return schemas[phaseName]?.[interactionId];
+}

package/src/runtime-internal/context/InteractionDraftContext.tsx

@@ -0,0 +1,279 @@
+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>>;
+  pendingInteractionKey: string | null;
+  pendingInteractionRevision: number;
+}
+
+/**
+ * Imperative API exposed to interaction primitives.
+ * 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;
+  /** Which interaction draft currently needs route-owned remaining input UI. */
+  getPendingInteraction(): string | null;
+  /** Mark the interaction draft currently waiting for remaining input. */
+  setPendingInteraction(interactionId: string | null): void;
+  /** Monotonic revision bumped whenever a pending interaction is routed. */
+  getPendingInteractionRevision(): number;
+  /** True while a local submission is in flight before the host echo arrives. */
+  isSubmitting(interactionId: string): boolean;
+  /** Atomically mark a submission in flight. Returns false if already busy. */
+  claimSubmitting(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: {},
+    pendingInteractionKey: null,
+    pendingInteractionRevision: 0,
+  }));
+
+  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 &&
+          prev.pendingInteractionKey === null
+        ) {
+          return prev;
+        }
+        return {
+          drafts: {},
+          arms: {},
+          submitting: {},
+          pendingInteractionKey: null,
+          pendingInteractionRevision: prev.pendingInteractionRevision + 1,
+        };
+      });
+    },
+    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 } };
+      });
+    },
+    getPendingInteraction() {
+      return store.getState().pendingInteractionKey;
+    },
+    setPendingInteraction(interactionId) {
+      store.setState((prev) => {
+        if (prev.pendingInteractionKey === interactionId) {
+          return interactionId === null
+            ? prev
+            : {
+                ...prev,
+                pendingInteractionRevision: prev.pendingInteractionRevision + 1,
+              };
+        }
+        return {
+          ...prev,
+          pendingInteractionKey: interactionId,
+          pendingInteractionRevision: prev.pendingInteractionRevision + 1,
+        };
+      });
+    },
+    getPendingInteractionRevision() {
+      return store.getState().pendingInteractionRevision;
+    },
+    isSubmitting(interactionId) {
+      return store.getState().submitting[interactionId] === true;
+    },
+    claimSubmitting(interactionId) {
+      let claimed = false;
+      store.setState((prev) => {
+        if (prev.submitting[interactionId] === true) return prev;
+        claimed = true;
+        return {
+          ...prev,
+          submitting: { ...prev.submitting, [interactionId]: true },
+        };
+      });
+      return claimed;
+    },
+    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 />
+ *   <Board.Root>{...}</Board.Root>
+ * </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();
+  useStore(
+    store,
+    useShallow(
+      (state: DraftState) => state.drafts[interactionId] ?? EMPTY_DRAFT,
+    ),
+  );
+  return store.getDraft(interactionId);
+}
+
+/** 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 the interaction draft currently waiting for pending input. */
+export function usePendingInteractionKey(): string | null {
+  const store = useInteractionUiStore();
+  const subscribed = useStore(
+    store,
+    (state: DraftState) => state.pendingInteractionKey ?? null,
+  );
+  return store.getPendingInteraction() ?? subscribed;
+}
+
+/** Subscribe to pending interaction route attempts. */
+export function usePendingInteractionRevision(): number {
+  const store = useInteractionUiStore();
+  const subscribed = useStore(
+    store,
+    (state: DraftState) => state.pendingInteractionRevision,
+  );
+  return Math.max(store.getPendingInteractionRevision(), subscribed);
+}
+
+/** 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/runtime-internal/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;
+}