@dreamboard-games/sdk 0.2.0

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

@@ -0,0 +1,438 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import {
+  useArmedInteraction,
+  useInteractionDraft,
+  useInteractionSubmitting,
+  useInteractionUiStore,
+} from "../context/InteractionDraftContext.js";
+import { useClientParamSchema } from "../context/ClientParamSchemaContext.js";
+import { usePluginState } from "../context/PluginStateContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+import {
+  ValidationError,
+  validationErrorFromUnknown,
+} from "../errors/ValidationError.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import {
+  applyInteractionInputDefaults,
+  hasInteractionFieldErrors,
+  interactionArmScope,
+  interactionInputKeys,
+  mergeInteractionFieldErrors,
+  validateInteractionInputDomains,
+} from "../utils/interaction-inputs.js";
+import {
+  applyInteractionDraftMutation,
+  claimInteractionSubmit,
+  clearInteractionRoute,
+  getInteractionDraftReadiness,
+  shouldAutoSubmitInteraction,
+} from "../utils/interaction-router.js";
+import {
+  interactionUnavailableReason,
+  isInteractionAvailable,
+} from "../utils/interaction-status.js";
+
+/**
+ * Anything that can be used as a submit params object. Subset of TS
+ * objects so generic defaults and `keyof Params & string` hold.
+ */
+export type InteractionParamsShape = Record<string, unknown>;
+
+export type InteractionHandleStatus = "open" | "submitting" | "submitted";
+
+export type DraftValidation<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+> =
+  | {
+      ok: true;
+      params: Params;
+      fieldErrors: Partial<Record<keyof Params & string, readonly string[]>>;
+      formErrors: readonly string[];
+      missing: ReadonlyArray<keyof Params & string>;
+    }
+  | {
+      ok: false;
+      fieldErrors: Partial<Record<keyof Params & string, readonly string[]>>;
+      formErrors: readonly string[];
+      missing: ReadonlyArray<keyof Params & string>;
+    };
+
+/**
+ * Bound handle around an {@link InteractionDescriptor}. Surfaces call into
+ * this hook to submit/validate an interaction, track draft input state for
+ * multi-step prompts, and arm/disarm themselves on a surface.
+ *
+ * Availability flags are mirrored from the authoritative descriptor; UI
+ * MUST NOT recompute eligibility locally.
+ *
+ * When the surrounding workspace knows the concrete params shape (e.g.
+ * obtained from the generated `InteractionParamsOf<Id>` alias), parameterise
+ * this handle on `Params` so `submit`, `draft`, and `setInput` are all
+ * statically typed. The default `Record<string, unknown>` preserves the
+ * loosely-typed fallback for generic infrastructure.
+ */
+export interface InteractionHandle<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  DefaultedKeys extends keyof Params & string = never,
+> {
+  descriptor: InteractionDescriptor;
+  /** Draft commit policy projected by the reducer. */
+  commit: InteractionDescriptor["commit"];
+  /**
+   * Submit the interaction. When `params` is omitted the current draft (as
+   * mutated by {@link InteractionHandle.setInput}) is used instead, which is
+   * the common case for multi-input prompts.
+   */
+  submit: (params?: Params) => Promise<void>;
+  /** Run server validation using `params` (or the current draft by default). */
+  validate: (params?: Params) => Promise<void>;
+  /** Run local generated client-schema validation against the current draft. */
+  validateDraft: () => DraftValidation<Params>;
+  /** Run server validation against the current draft. */
+  validateDraftServer: () => Promise<void>;
+  /**
+   * Validate the current draft locally, submit parsed params, then clear the
+   * draft only when submission succeeds.
+   */
+  submitDraft: () => Promise<void>;
+  /** Derived from `descriptor.availability`. */
+  available: boolean;
+  /** Derived from `descriptor.availability`. */
+  unavailableReason?: string;
+  /** Local/authoritative progress for this interaction. */
+  status: InteractionHandleStatus;
+
+  // --- Draft state --------------------------------------------------------
+
+  /** Live draft values for this interaction. Empty object when unset. */
+  draft: Readonly<Partial<Params>>;
+  /**
+   * Draft values with authored input defaults applied. Fields with declared
+   * defaults are typed as present; other draft fields remain partial.
+   */
+  values: Readonly<Partial<Params> & Pick<Params, DefaultedKeys>>;
+  /** Set a single input on the draft. */
+  setInput: <K extends keyof Params & string>(key: K, value: Params[K]) => void;
+  /** Clear a single input (or the whole draft when `key` is omitted). */
+  clearInput: (key?: keyof Params & string) => void;
+  /**
+   * True when every key declared on `descriptor.inputs` has a value in
+   * the draft. Falls back to `true` when the descriptor declares no inputs.
+   */
+  isReady: boolean;
+  /**
+   * True when this interaction is the currently armed one on its surface.
+   * Armed interactions are the ones that board primitives use
+   * to highlight eligible targets and route clicks.
+   */
+  isArmed: boolean;
+  /** Arm this interaction on its surface (disarms any previously armed). */
+  arm: () => void;
+  /** Disarm this interaction (if it was armed). */
+  disarm: () => void;
+}
+
+/**
+ * Bind an {@link InteractionDescriptor} to submit/validate helpers plus
+ * draft + arming state. Use this from any surface; draft state is shared
+ * across components through {@link InteractionUiProvider}, which
+ * `PluginRuntime` auto-mounts.
+ *
+ * Example:
+ * ```tsx
+ * const handle = useInteractionHandle(placeThing);
+ * handle.setInput("cardId", card.id);
+ * handle.setInput("ringId", ring.id);
+ * if (handle.isReady) await handle.submit();
+ * ```
+ */
+export function useInteractionHandle<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  DefaultedKeys extends keyof Params & string = never,
+>(descriptor: InteractionDescriptor): InteractionHandle<Params, DefaultedKeys> {
+  const runtime = useRuntimeContext();
+  const { controllingPlayerId } = usePluginSession();
+  const store = useInteractionUiStore();
+  const submittingRef = useRef(false);
+  const autoSubmitSignatureRef = useRef<string | null>(null);
+  const simultaneousPhase = usePluginState(
+    (state) => state.gameplay.simultaneousPhase,
+  );
+
+  const { interactionId, interactionKey, phaseName } = descriptor;
+  const armScope = interactionArmScope(descriptor);
+  const inputKeys = useMemo(
+    () => interactionInputKeys(descriptor),
+    [descriptor],
+  );
+  const paramsSchema = useClientParamSchema(phaseName, interactionId);
+  const draft = useInteractionDraft(interactionKey) as Readonly<
+    Partial<Params>
+  >;
+  const values = useMemo(
+    () =>
+      applyInteractionInputDefaults<Params>(descriptor, draft) as Readonly<
+        Partial<Params> & Pick<Params, DefaultedKeys>
+      >,
+    [descriptor, draft],
+  );
+  const armedId = useArmedInteraction(armScope);
+  const isArmed = armedId === interactionKey;
+  const submitting = useInteractionSubmitting(interactionKey);
+  const submitted =
+    controllingPlayerId !== null &&
+    simultaneousPhase?.phaseName === phaseName &&
+    simultaneousPhase.interactionId === interactionId &&
+    simultaneousPhase.sealedPlayerIds.includes(controllingPlayerId);
+  const status: InteractionHandleStatus = submitted
+    ? "submitted"
+    : submitting
+      ? "submitting"
+      : "open";
+
+  const isReady = useMemo(() => {
+    return getInteractionDraftReadiness(
+      descriptor,
+      values as Record<string, unknown>,
+    ).ready;
+  }, [descriptor, values]);
+
+  const requirePlayer = useCallback(() => {
+    if (!controllingPlayerId) {
+      throw new Error("useInteractionHandle: no controlling player available");
+    }
+    return controllingPlayerId;
+  }, [controllingPlayerId]);
+
+  const submit = useCallback(
+    async (params?: Params) => {
+      if (status !== "open" || submittingRef.current) {
+        throw new ValidationError(
+          status === "submitted" ? "ALREADY_SUBMITTED" : "SUBMITTING",
+          status === "submitted"
+            ? "Interaction has already been submitted."
+            : "Interaction submission is already in progress.",
+        );
+      }
+      if (!claimInteractionSubmit(store, descriptor)) {
+        throw new ValidationError(
+          "SUBMITTING",
+          "Interaction submission is already in progress.",
+        );
+      }
+      submittingRef.current = true;
+      const finalParams = applyInteractionInputDefaults<Params>(
+        descriptor,
+        params ?? values,
+      ) as Params;
+      try {
+        await runtime.submitInteraction(
+          requirePlayer(),
+          interactionId,
+          finalParams as Record<string, unknown>,
+        );
+        clearInteractionRoute(store, descriptor);
+      } catch (error) {
+        throw validationErrorFromUnknown(error);
+      } finally {
+        submittingRef.current = false;
+        store.setSubmitting(interactionKey, false);
+      }
+    },
+    [
+      descriptor,
+      values,
+      runtime,
+      requirePlayer,
+      interactionId,
+      interactionKey,
+      store,
+      status,
+    ],
+  );
+
+  const validate = useCallback(
+    async (params?: Params) => {
+      const finalParams = applyInteractionInputDefaults<Params>(
+        descriptor,
+        params ?? values,
+      ) as Params;
+      const result = await runtime.validateInteraction(
+        requirePlayer(),
+        interactionId,
+        finalParams as Record<string, unknown>,
+      );
+      if (!result.valid) {
+        throw new ValidationError(result.errorCode, result.message);
+      }
+    },
+    [descriptor, values, runtime, requirePlayer, interactionId],
+  );
+
+  const validateDraft = useCallback((): DraftValidation<Params> => {
+    const rawDraft = { ...values } as Record<string, unknown>;
+    const required = inputKeys;
+    const missing = getInteractionDraftReadiness(descriptor, rawDraft)
+      .missingInputs as Array<keyof Params & string>;
+    const domainFieldErrors = validateInteractionInputDomains(
+      descriptor,
+      rawDraft,
+    ) as Partial<Record<keyof Params & string, readonly string[]>>;
+
+    if (!paramsSchema) {
+      if (missing.length > 0 || hasInteractionFieldErrors(domainFieldErrors)) {
+        return {
+          ok: false,
+          fieldErrors: domainFieldErrors,
+          formErrors: [],
+          missing,
+        };
+      }
+      return {
+        ok: true,
+        params: rawDraft as Params,
+        fieldErrors: {},
+        formErrors: [],
+        missing: [],
+      };
+    }
+
+    const result = paramsSchema.safeParse(rawDraft);
+    if (result.success) {
+      if (hasInteractionFieldErrors(domainFieldErrors)) {
+        return {
+          ok: false,
+          fieldErrors: domainFieldErrors,
+          formErrors: [],
+          missing,
+        };
+      }
+      return {
+        ok: true,
+        params: result.data as Params,
+        fieldErrors: {},
+        formErrors: [],
+        missing: [],
+      };
+    }
+
+    const fieldErrors: Partial<
+      Record<keyof Params & string, readonly string[]>
+    > = {};
+    const formErrors: string[] = [];
+    const missingSet = new Set<PropertyKey>(missing);
+    for (const issue of result.error.issues) {
+      const [first] = issue.path;
+      if (typeof first === "string" && required.includes(first)) {
+        if (missingSet.has(first)) continue;
+        const key = first as keyof Params & string;
+        fieldErrors[key] = [...(fieldErrors[key] ?? []), issue.message];
+      } else {
+        formErrors.push(issue.message);
+      }
+    }
+    return {
+      ok: false,
+      fieldErrors: mergeInteractionFieldErrors(
+        fieldErrors,
+        domainFieldErrors,
+      ) as Partial<Record<keyof Params & string, readonly string[]>>,
+      formErrors,
+      missing,
+    };
+  }, [descriptor, values, inputKeys, paramsSchema]);
+
+  const validateDraftServer = useCallback(async () => {
+    await validate({ ...values } as Params);
+  }, [values, validate]);
+
+  const submitDraft = useCallback(async () => {
+    const validation = validateDraft();
+    if (!validation.ok) {
+      const message =
+        validation.formErrors[0] ??
+        Object.values(validation.fieldErrors).flat()[0] ??
+        (validation.missing.length > 0
+          ? "Required inputs are missing"
+          : "Draft validation failed");
+      throw new ValidationError("INVALID_DRAFT", message);
+    }
+    await submit(validation.params);
+  }, [submit, validateDraft]);
+
+  useEffect(() => {
+    if (!shouldAutoSubmitInteraction(descriptor)) {
+      autoSubmitSignatureRef.current = null;
+      return;
+    }
+    if (!isInteractionAvailable(descriptor) || status !== "open" || !isReady) {
+      if (!isReady) autoSubmitSignatureRef.current = null;
+      return;
+    }
+    const validation = validateDraft();
+    if (!validation.ok) return;
+    const signature = `${interactionKey}:${JSON.stringify(validation.params)}`;
+    if (autoSubmitSignatureRef.current === signature) return;
+    autoSubmitSignatureRef.current = signature;
+    void submit(validation.params).catch(() => {
+      // Runtime error channels surface the failure. Keep the draft intact and
+      // suppress repeated attempts until the player changes the draft.
+    });
+  }, [
+    descriptor.availability,
+    descriptor.commit.mode,
+    descriptor.inputs,
+    interactionKey,
+    isReady,
+    status,
+    submit,
+    validateDraft,
+  ]);
+
+  const setInput = useCallback(
+    <K extends keyof Params & string>(key: K, value: Params[K]) => {
+      applyInteractionDraftMutation(store, descriptor, [{ key, value }]);
+    },
+    [store, descriptor],
+  );
+
+  const clearInput = useCallback(
+    (key?: keyof Params & string) => {
+      store.clearInput(interactionKey, key);
+    },
+    [store, interactionKey],
+  );
+
+  const arm = useCallback(() => {
+    store.arm(armScope, interactionKey);
+  }, [store, armScope, interactionKey]);
+
+  const disarm = useCallback(() => {
+    if (store.getArmed(armScope) === interactionKey) {
+      store.arm(armScope, null);
+    }
+  }, [store, armScope, interactionKey]);
+
+  return {
+    descriptor,
+    commit: descriptor.commit,
+    available: isInteractionAvailable(descriptor),
+    unavailableReason: interactionUnavailableReason(descriptor),
+    status,
+    submit,
+    validate,
+    validateDraft,
+    validateDraftServer,
+    submitDraft,
+    draft,
+    values,
+    setInput,
+    clearInput,
+    isReady,
+    isArmed,
+    arm,
+    disarm,
+  };
+}

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

@@ -0,0 +1,20 @@
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { useActivePlayers } from "./useActivePlayers.js";
+
+/**
+ * Returns whether the currently controlled player is one of the active players
+ * for the current gameplay snapshot. Uses {@link useActivePlayers}, so this is
+ * correct for `simultaneousPlayer` phases too (a seat that still owes an action
+ * counts as active until it submits).
+ */
+export function useIsMyTurn(): boolean {
+  const { controllingPlayerId } = usePluginSession();
+  const activePlayers = useActivePlayers();
+
+  return (
+    controllingPlayerId !== null &&
+    activePlayers.includes(
+      controllingPlayerId as (typeof activePlayers)[number],
+    )
+  );
+}

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

@@ -0,0 +1,76 @@
+import { useState, useEffect } from "react";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+import type { LobbyState } from "../types/plugin-state.js";
+import type { PluginRuntimeAPI } from "../runtime/createPluginRuntimeAPI.js";
+
+// Re-export LobbyState for convenience
+export type { LobbyState };
+
+/**
+ * Subscribes to lobby updates from the plugin runtime snapshot when present.
+ * Returns `null` until the host provides lobby state (SSR/tests/minimal runtimes).
+ */
+export function useLobbyState(): LobbyState | null {
+  const runtime = useRuntimeContext() as PluginRuntimeAPI;
+
+  const getStateFromSnapshot = (): LobbyState | null => {
+    if (!runtime.getSnapshot) return null;
+    const snapshot = runtime.getSnapshot();
+    if (!snapshot?.lobby) return null;
+    return snapshot.lobby;
+  };
+
+  const [lobbyState, setLobbyState] = useState<LobbyState | null>(
+    getStateFromSnapshot,
+  );
+
+  useEffect(() => {
+    if (!runtime.subscribeToState) {
+      return;
+    }
+
+    const initialState = runtime.getSnapshot?.();
+    if (initialState?.lobby) {
+      setLobbyState(initialState.lobby);
+    }
+
+    return runtime.subscribeToState((snapshot) => {
+      if (snapshot.lobby) {
+        setLobbyState(snapshot.lobby);
+      }
+    });
+  }, [runtime]);
+
+  return lobbyState;
+}
+
+/**
+ * Hook to subscribe to lobby state updates.
+ * Returns the latest lobby information from state-sync messages.
+ *
+ * State is provided by PluginStateProvider from host's state-sync messages.
+ * The host transforms raw SSE LOBBY_UPDATE messages into clean LobbyState objects.
+ *
+ * @returns Current lobby state (never null - throws if not available)
+ * @throws Error if lobby state is not available
+ *
+ * @example
+ * ```typescript
+ * function LobbyScreen() {
+ *   const lobby = useLobby();
+ *   // lobby is guaranteed to be non-null
+ *   return <div>{lobby.seats.length} seats</div>;
+ * }
+ * ```
+ */
+export function useLobby(): LobbyState {
+  const lobbyState = useLobbyState();
+  if (lobbyState === null) {
+    throw new Error(
+      "useLobby: Lobby state not available. " +
+        "The host should only render the plugin when lobby state is ready.",
+    );
+  }
+
+  return lobbyState;
+}

package/src/runtime-internal/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 "../../ui/types/player-state.js";
+
+// Re-export for consumers
+export type { Player } from "../../ui/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/runtime-internal/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/runtime-internal/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]);
+}