@dreamboard-games/sdk 0.2.1-alpha.0 → 0.3.0-alpha.1

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

@@ -1,147 +0,0 @@
-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

@@ -1,61 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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";