@dreamboard-games/sdk 0.2.0

package/src/runtime-internal/hooks/usePluginRuntime.ts

@@ -0,0 +1,147 @@
+import { useState, useEffect, useRef } 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;
+  /**
+   * True when the plugin was ready before but the current snapshot has no
+   * projected view — e.g. you've acted and are waiting on the rest of the
+   * table in a simultaneous phase. Lets the loading affordance read as a
+   * mid-game wait rather than a cold "still loading" stall.
+   */
+  waiting: 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);
+  // Latches once we've shown a view, so a later view-less snapshot reads as a
+  // mid-game wait rather than a fresh load. (A ref, so it never re-triggers a
+  // render on its own.)
+  const hasBeenReadyRef = useRef(false);
+  if (isReady) hasBeenReadyRef.current = true;
+
+  // 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,
+    waiting: hasBeenReadyRef.current && !isReady,
+    error,
+  };
+}

package/src/runtime-internal/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/runtime-internal/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);
+}

package/src/runtime-internal/index.ts

@@ -0,0 +1,42 @@
+export {
+  createDreamboardUI,
+  type CardKey,
+  type DreamboardUI,
+  type DreamboardUIRegister,
+  type TypedGame,
+  type UIContract,
+  type ZoneKey,
+} from "./ui-contract.js";
+export { PluginStateProvider } from "./context/PluginStateContext.js";
+export {
+  RuntimeContext,
+  RuntimeProvider,
+  useRuntimeContext,
+} from "./context/RuntimeContext.js";
+export {
+  type ClientParamSchema,
+  type ClientParamSchemaMap,
+} from "./context/ClientParamSchemaContext.js";
+export {
+  PluginRuntime,
+  type PluginRuntimeProps,
+} from "./components/PluginRuntime.js";
+export { createPluginRuntimeAPI } from "./runtime/createPluginRuntimeAPI.js";
+export { usePluginRuntime } from "./hooks/usePluginRuntime.js";
+export type * from "./hooks/usePluginRuntime.js";
+export type {
+  DraftValidation,
+  InteractionHandle,
+  InteractionHandleStatus,
+  InteractionParamsShape,
+} from "./hooks/useInteractionHandle.js";
+export type {
+  ActionInteractionDescriptor,
+  InteractionContext,
+  InteractionContextOption,
+  InteractionDescriptor,
+  InputDomainDependencyCase,
+  PluginStateSnapshot,
+  PromptInteractionDescriptor,
+} from "./types/plugin-state.js";
+export type * from "./types/runtime-api.js";

package/src/runtime-internal/internal.ts

@@ -0,0 +1,43 @@
+export {
+  RuntimeContext,
+  RuntimeProvider,
+  useRuntimeContext,
+} from "./context/RuntimeContext.js";
+export {
+  createDreamboardUI,
+  type DreamboardUI,
+  type TypedGame,
+} from "./ui-contract.js";
+export type {
+  BoardHexGridInteractionFilter,
+  BoardHexGridProps,
+  BoardHexViewProps,
+  BoardSpaceTargetProps,
+  BoardTargetProps,
+  BoardEdgeTargetProps,
+  BoardVertexTargetProps,
+  UIRootProps,
+  ZoneCardAtProps,
+  ZoneCardRenderItem,
+  ZoneListProps,
+  ZonePileCardsProps,
+} from "./primitives/index.js";
+export {
+  InteractionForm,
+  defaultFormInputs,
+  hasDefaultInteractionFormFields,
+  type InteractionFormProps,
+} from "./components/InteractionForm.js";
+export { createPluginRuntimeAPI } from "./runtime/createPluginRuntimeAPI.js";
+export {
+  PluginStateProvider,
+  usePluginActions,
+  usePluginState,
+} from "./context/PluginStateContext.js";
+export { usePluginRuntime } from "./hooks/usePluginRuntime.js";
+export type { PluginStateSnapshot } from "./types/plugin-state.js";
+export type {
+  RuntimeAPI,
+  SubmissionError,
+  ValidationResult,
+} from "./types/runtime-api.js";