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

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

@@ -1,105 +0,0 @@
-import React from "react";
-import { InteractionUiProvider } from "../context/InteractionDraftContext.js";
-import { RuntimeProvider } from "../context/RuntimeContext.js";
-import { usePluginSession } from "../context/PluginSessionContext.js";
-import { RuntimeSemanticProjectionMarker } from "../context/PluginStateContext.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__"}>
-      <RuntimeSemanticProjectionMarker />
-      {children}
-    </InteractionUiProvider>
-  );
-}

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

@@ -1,72 +0,0 @@
-import type { BoardTargetKind } from "../../utils/interaction-inputs.js";
-import type { BrowserInteractionAttributeMap } from "../../../browser-interaction/index.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;
-  browserAttributes?: BrowserInteractionAttributeMap;
-  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

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

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

@@ -1,47 +0,0 @@
-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;
-}