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

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

@@ -1,105 +0,0 @@
-import { useRef, useSyncExternalStore } from "react";
-import { useRuntimeContext } from "../context/RuntimeContext.js";
-import type { GameView } from "#dreamboard/ui-contract";
-import type { PluginStateSnapshot } from "../types/reducer-state.js";
-import type { PluginRuntimeAPI } from "../runtime/createPluginRuntimeAPI.js";
-
-type EqualityFn<T> = (left: T, right: T) => boolean;
-
-interface SelectorCache<T> {
-  rawView: GameView;
-  selected: T;
-}
-
-function defaultEquality<T>(left: T, right: T): boolean {
-  return Object.is(left, right);
-}
-
-function requireProjectedView(
-  snapshot: PluginStateSnapshot | null | undefined,
-  message: string,
-): GameView {
-  const view = snapshot?.view;
-  if (view === null || typeof view === "undefined") {
-    throw new Error(message);
-  }
-  return view;
-}
-
-/**
- * Hook to select a derived value from the projected reducer view.
- * Only re-renders when the selected slice changes according to the equalityFn.
- *
- * @param selector - Function to extract data from the projected view
- * @param equalityFn - Optional equality function for selected slice comparison
- * @returns Selected value from the current projected view
- */
-export function useGameSelector<T>(
-  selector: (state: GameView) => T,
-  equalityFn: EqualityFn<T> = defaultEquality,
-): T {
-  const runtime = useRuntimeContext() as PluginRuntimeAPI;
-  const selectorRef = useRef(selector);
-  const equalityRef = useRef(equalityFn);
-  const cacheRef = useRef<SelectorCache<T> | null>(null);
-
-  if (selectorRef.current !== selector || equalityRef.current !== equalityFn) {
-    selectorRef.current = selector;
-    equalityRef.current = equalityFn;
-    cacheRef.current = null;
-  }
-
-  const message =
-    "useGameSelector: Projected view not available. Ensure the reducer-native host payload is initialized.";
-
-  const getSelectedFromSnapshot = (
-    snapshot: PluginStateSnapshot | null | undefined,
-  ): T => {
-    const view = requireProjectedView(snapshot, message);
-    const cached = cacheRef.current;
-    if (cached && cached.rawView === view) {
-      return cached.selected;
-    }
-
-    const nextSelected = selectorRef.current(view);
-    if (cached && equalityRef.current(cached.selected, nextSelected)) {
-      cacheRef.current = {
-        rawView: view,
-        selected: cached.selected,
-      };
-      return cached.selected;
-    }
-
-    cacheRef.current = {
-      rawView: view,
-      selected: nextSelected,
-    };
-    return nextSelected;
-  };
-
-  const subscribe = (onStoreChange: () => void) => {
-    if (!runtime.subscribeToState) {
-      return () => {};
-    }
-
-    return runtime.subscribeToState((snapshot) => {
-      const previousCache = cacheRef.current;
-      const nextSelected = getSelectedFromSnapshot(
-        snapshot as PluginStateSnapshot,
-      );
-      if (
-        !previousCache ||
-        !equalityRef.current(previousCache.selected, nextSelected)
-      ) {
-        onStoreChange();
-      }
-    });
-  };
-
-  const getSnapshot = () =>
-    getSelectedFromSnapshot(
-      (runtime.getSnapshot?.() ?? null) as PluginStateSnapshot | null,
-    );
-
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-}

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

@@ -1,9 +0,0 @@
-import type { GameView } from "#dreamboard/ui-contract";
-import { useGameSelector } from "./useGameSelector.js";
-
-/**
- * Hook to access the current seat-projected reducer-native view.
- */
-export function useGameView(): GameView {
-  return useGameSelector((view) => view);
-}

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

@@ -1,354 +0,0 @@
-import { 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,
-  inputByKey,
-  isInputValueReady,
-  interactionArmScope,
-  interactionInputKeys,
-  mergeInteractionFieldErrors,
-  validateInteractionInputDomains,
-} from "../utils/interaction-inputs.js";
-import type {
-  DraftValidation,
-  InteractionHandle,
-  InteractionHandleStatus,
-  InteractionParamsShape,
-} from "./useInteractionHandle.js";
-import {
-  interactionUnavailableReason,
-  isInteractionAvailable,
-} from "../utils/interaction-status.js";
-import { shouldAutoSubmitInteraction } from "../utils/interaction-router.js";
-
-/**
- * Look up an interaction descriptor by phase-qualified key on the controlling seat's
- * inbox and return a bound {@link InteractionHandle}. Returns `null`
- * when no matching descriptor is currently projected.
- *
- * Prefer this over manual `inbox.bySurface.panel?.find(...)` + sentinel
- * descriptor patterns — it keeps hook-call order stable and guarantees
- * the handle reflects the freshest descriptor.
- *
- * Types:
- * - `Key` narrows the key literal. When called from the workspace-local
- *   `useInteractionByKey` re-export generated in `ui-contract.ts`, `Key` is
- *   constrained to the generated `InteractionKey` union so typos become
- *   compile errors.
- * - `Params` is the params shape (`InteractionParamsOf<Key>` in the
- *   generated re-export). It flows through to `draft`, `submit`,
- *   `validate`, and `setInput` for compile-time safety.
- *
- * ```tsx
- * // from the generated workspace re-export
- * const handle = useInteractionByKey("play.placeThingCard");
- * if (!handle) return <Waiting/>;
- * handle.setInput("cardId", card.id); // typed to ThingsDeckCardId
- * await handle.submit();
- * ```
- */
-export function useInteractionByKey<
-  Key extends string = string,
-  Params extends InteractionParamsShape = InteractionParamsShape,
-  DefaultedKeys extends keyof Params & string = never,
->(
-  interactionKey: Key | null | undefined,
-): InteractionHandle<Params, DefaultedKeys> | null {
-  const runtime = useRuntimeContext();
-  const { controllingPlayerId } = usePluginSession();
-  const store = useInteractionUiStore();
-  const submittingRef = useRef(false);
-  const autoSubmitSignatureRef = useRef<string | null>(null);
-
-  const descriptors = usePluginState(
-    (state) => state.gameplay.availableInteractions ?? [],
-  );
-  const simultaneousPhase = usePluginState(
-    (state) => state.gameplay.simultaneousPhase,
-  );
-
-  const descriptor = useMemo<InteractionDescriptor | null>(() => {
-    if (!interactionKey) return null;
-    return descriptors.find((d) => d.interactionKey === interactionKey) ?? null;
-  }, [descriptors, interactionKey]);
-
-  const armScope = descriptor
-    ? interactionArmScope(descriptor)
-    : "interaction:missing";
-  const resolvedPhaseName = descriptor?.phaseName;
-  const resolvedInteractionId = descriptor?.interactionId ?? "";
-  const resolvedInteractionKey = descriptor?.interactionKey ?? "";
-  const paramsSchema = useClientParamSchema(
-    resolvedPhaseName,
-    resolvedInteractionId,
-  );
-  const draft = useInteractionDraft(resolvedInteractionKey);
-  const armedId = useArmedInteraction(armScope);
-  const submitting = useInteractionSubmitting(resolvedInteractionKey);
-
-  const handle = useMemo<InteractionHandle<
-    Params,
-    DefaultedKeys
-  > | null>(() => {
-    if (!descriptor) return null;
-    const typedDraft = draft as Readonly<Partial<Params>>;
-    const typedValues = applyInteractionInputDefaults<Params>(
-      descriptor,
-      typedDraft,
-    ) as Readonly<Partial<Params> & Pick<Params, DefaultedKeys>>;
-    const inputKeys = interactionInputKeys(descriptor);
-    const isReady =
-      inputKeys.length === 0
-        ? true
-        : inputKeys.every((key) => {
-            const input = inputByKey(descriptor, key);
-            const value = (typedValues as Record<string, unknown>)[key];
-            return input
-              ? isInputValueReady(input, value)
-              : value !== null && value !== undefined;
-          });
-    const isArmed = armedId === descriptor.interactionKey;
-    const submitted =
-      controllingPlayerId !== null &&
-      simultaneousPhase?.phaseName === descriptor.phaseName &&
-      simultaneousPhase.interactionId === descriptor.interactionId &&
-      simultaneousPhase.sealedPlayerIds.includes(controllingPlayerId);
-    const status: InteractionHandleStatus = submitted
-      ? "submitted"
-      : submitting
-        ? "submitting"
-        : "open";
-
-    const requirePlayer = () => {
-      if (!controllingPlayerId) {
-        throw new Error("useInteractionByKey: no controlling player available");
-      }
-      return controllingPlayerId;
-    };
-
-    const submit = 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.",
-        );
-      }
-      submittingRef.current = true;
-      store.setSubmitting(descriptor.interactionKey, true);
-      const finalParams = applyInteractionInputDefaults<Params>(
-        descriptor,
-        params ?? typedValues,
-      ) as Params;
-      try {
-        await runtime.submitInteraction(
-          requirePlayer(),
-          descriptor.interactionId,
-          finalParams as Record<string, unknown>,
-        );
-        store.clearInput(descriptor.interactionKey);
-        if (store.getArmed(armScope) === descriptor.interactionKey) {
-          store.arm(armScope, null);
-        }
-      } catch (error) {
-        throw validationErrorFromUnknown(error);
-      } finally {
-        submittingRef.current = false;
-        store.setSubmitting(descriptor.interactionKey, false);
-      }
-    };
-
-    const validate = async (params?: Params) => {
-      const finalParams = applyInteractionInputDefaults<Params>(
-        descriptor,
-        params ?? typedValues,
-      ) as Params;
-      const result = await runtime.validateInteraction(
-        requirePlayer(),
-        descriptor.interactionId,
-        finalParams as Record<string, unknown>,
-      );
-      if (!result.valid) {
-        throw new ValidationError(result.errorCode, result.message);
-      }
-    };
-
-    const validateDraft = (): DraftValidation<Params> => {
-      const rawDraft = { ...typedValues } as Record<string, unknown>;
-      const missing = inputKeys.filter((key) => {
-        const input = inputByKey(descriptor, key);
-        const value = rawDraft[key];
-        return input
-          ? !isInputValueReady(input, value)
-          : value === null || value === undefined;
-      }) 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[] = [];
-      for (const issue of result.error.issues) {
-        const [first] = issue.path;
-        if (typeof first === "string" && inputKeys.includes(first)) {
-          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,
-      };
-    };
-
-    const validateDraftServer = async () => {
-      await validate({ ...typedValues } as Params);
-    };
-
-    const submitDraft = 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);
-    };
-
-    return {
-      descriptor,
-      commit: descriptor.commit,
-      available: isInteractionAvailable(descriptor),
-      unavailableReason: interactionUnavailableReason(descriptor),
-      status,
-      submit,
-      validate,
-      validateDraft,
-      validateDraftServer,
-      submitDraft,
-      draft: typedDraft,
-      values: typedValues,
-      setInput: <K extends keyof Params & string>(key: K, value: Params[K]) =>
-        store.setInput(descriptor.interactionKey, key, value as unknown),
-      clearInput: (key?: keyof Params & string) =>
-        store.clearInput(descriptor.interactionKey, key),
-      isReady,
-      isArmed,
-      arm: () => store.arm(armScope, descriptor.interactionKey),
-      disarm: () => {
-        if (store.getArmed(armScope) === descriptor.interactionKey) {
-          store.arm(armScope, null);
-        }
-      },
-    };
-  }, [
-    descriptor,
-    draft,
-    armedId,
-    armScope,
-    runtime,
-    store,
-    controllingPlayerId,
-    paramsSchema,
-    simultaneousPhase,
-    submitting,
-  ]);
-
-  useEffect(() => {
-    if (!handle) {
-      autoSubmitSignatureRef.current = null;
-      return;
-    }
-    if (!shouldAutoSubmitInteraction(handle.descriptor)) {
-      autoSubmitSignatureRef.current = null;
-      return;
-    }
-    if (!handle.available || handle.status !== "open" || !handle.isReady) {
-      if (!handle.isReady) autoSubmitSignatureRef.current = null;
-      return;
-    }
-    const validation = handle.validateDraft();
-    if (!validation.ok) return;
-    const signature = `${handle.descriptor.interactionKey}:${JSON.stringify(
-      validation.params,
-    )}`;
-    if (autoSubmitSignatureRef.current === signature) return;
-    autoSubmitSignatureRef.current = signature;
-    void handle.submit(validation.params).catch(() => {
-      // Runtime error channels surface the failure. Keep the draft intact and
-      // suppress repeated attempts until the player changes the draft.
-    });
-  }, [handle]);
-
-  return handle;
-}