dreamboard 0.1.21 → 0.1.23

package/dist/runtime-packages/ui-host-runtime/src/session-state-reducer.ts

@@ -0,0 +1,814 @@
+import type {
+  GameplayPerspective,
+  GameplayViewport,
+  SessionContext,
+  UnifiedSessionModel,
+} from "./session-model.js";
+import {
+  getGameplayViewport,
+  getSessionContext,
+  resolveControllablePlayerIds,
+  withContext,
+} from "./session-model.js";
+import type {
+  NormalizedSessionEvent,
+  NormalizedSessionSnapshot,
+} from "./session-ingress.js";
+
+export type NotificationType =
+  | "YOUR_TURN"
+  | "PROMPT_OPENED"
+  | "ACTION_EXECUTED"
+  | "ACTION_REJECTED"
+  | "TURN_CHANGED"
+  | "STATE_CHANGED"
+  | "GAME_ENDED"
+  | "ERROR";
+
+export type NotificationPayload =
+  | { type: "YOUR_TURN"; activePlayers: string[] }
+  | {
+      type: "PROMPT_OPENED";
+      promptId: string;
+      promptInstanceId: string;
+      targetPlayer: string;
+      title?: string;
+    }
+  | { type: "ACTION_EXECUTED"; playerId: string; actionType: string }
+  | { type: "ACTION_REJECTED"; reason: string; targetPlayer?: string }
+  | {
+      type: "TURN_CHANGED";
+      previousPlayers: string[];
+      currentPlayers: string[];
+    }
+  | { type: "STATE_CHANGED"; newState: string }
+  | {
+      type: "GAME_ENDED";
+      winner?: string;
+      finalScores: Record<string, number>;
+      reason: string;
+    }
+  | { type: "ERROR"; message: string; code?: string };
+
+export interface Notification {
+  id: string;
+  type: NotificationType;
+  payload: NotificationPayload;
+  timestamp: number;
+  read: boolean;
+}
+
+export type HostFeedbackType =
+  | "ACTION_REJECTED"
+  | "PROMPT_OPENED"
+  | "YOUR_TURN";
+
+export type HostFeedbackPayload =
+  | { type: "ACTION_REJECTED"; reason: string; targetPlayer?: string }
+  | {
+      type: "PROMPT_OPENED";
+      promptId: string;
+      promptInstanceId: string;
+      targetPlayer: string;
+      title?: string;
+    }
+  | { type: "YOUR_TURN"; activePlayers: string[] };
+
+export interface HostFeedback {
+  id: string;
+  type: HostFeedbackType;
+  payload: HostFeedbackPayload;
+  timestamp: number;
+}
+
+export interface SSEEventEntry {
+  id: number;
+  eventType: string;
+  data: unknown;
+  timestamp: string;
+}
+
+export interface ConnectionState {
+  lobby: boolean;
+  gameplay: boolean;
+  error: string | null;
+  isConnected: boolean;
+}
+
+export interface ActivityState {
+  notifications: Notification[];
+  hostFeedback: HostFeedback[];
+  syncId: number;
+  lastSyncTimestamp: number | null;
+  lastAckTimestamp: number | null;
+}
+
+export interface DebugState {
+  sseEvents: SSEEventEntry[];
+  maxEvents: number;
+}
+
+export interface UnifiedSessionState {
+  session: UnifiedSessionModel;
+  connection: ConnectionState;
+  activity: ActivityState;
+  debug: DebugState;
+}
+
+export type SnapshotIngressSource =
+  | "short-code"
+  | "snapshot"
+  | "start"
+  | "dev-new";
+
+export type EventIngressSource = "sse" | "submit-response";
+
+export type SessionStateIngress =
+  | {
+      type: "command.loading";
+      target?: { sessionId?: string; shortCode?: string };
+    }
+  | { type: "command.failed"; message: string }
+  | {
+      type: "snapshot.loaded";
+      source: SnapshotIngressSource;
+      snapshot: NormalizedSessionSnapshot;
+      expectedPerspectivePlayerId?: string | null;
+    }
+  | {
+      type: "event.received";
+      source: EventIngressSource;
+      event: NormalizedSessionEvent;
+      debugEvent?: { eventType: string; data: unknown };
+      clientActionId?: string | null;
+    }
+  | {
+      type: "connection.prepared";
+      userId: string | null;
+      switchablePlayerIds: string[];
+    }
+  | {
+      type: "connection.changed";
+      channel: "lobby" | "gameplay";
+      connected: boolean;
+    }
+  | { type: "connection.failed"; message: string }
+  | { type: "connection.errorCleared" }
+  | {
+      type: "feedback.actionRejected";
+      reason: string;
+      targetPlayer?: string;
+    }
+  | { type: "local.playerSelected"; playerId: string; sessionId: string }
+  | { type: "activity.stateAcked" }
+  | { type: "activity.notificationRead"; id: string }
+  | { type: "activity.notificationsCleared" }
+  | { type: "activity.hostFeedbackDismissed"; id: string }
+  | { type: "activity.hostFeedbackCleared" }
+  | { type: "debug.sseEventsCleared" }
+  | { type: "streams.closed" }
+  | { type: "session.reset" };
+
+export type SessionStateEffect =
+  | {
+      type: "requestGameplayResync";
+      sessionId: string;
+      playerId: string;
+      reason: string;
+    }
+  | {
+      type: "reconnectGameplay";
+      sessionId: string;
+      playerId: string;
+      source: "player-switch";
+    }
+  | {
+      type: "perf.storeApplied";
+      gameplayVersion: number;
+      syncId: number;
+    }
+  | {
+      type: "log.warn";
+      message: string;
+    };
+
+export interface SessionStateReducerEnvironment {
+  fallbackToAllSeatsWhenUserIdMissing: boolean;
+  nextEventId: () => number;
+  nextNotificationId: () => string;
+  nowMs: () => number;
+  nowIso: () => string;
+}
+
+export interface SessionStateReducerResult {
+  state: UnifiedSessionState;
+  effects: SessionStateEffect[];
+}
+
+export function createInitialUnifiedSessionState(): UnifiedSessionState {
+  return {
+    session: { type: "idle" },
+    connection: {
+      lobby: false,
+      gameplay: false,
+      error: null,
+      isConnected: false,
+    },
+    activity: {
+      notifications: [],
+      hostFeedback: [],
+      syncId: 0,
+      lastSyncTimestamp: null,
+      lastAckTimestamp: null,
+    },
+    debug: { sseEvents: [], maxEvents: 500 },
+  };
+}
+
+function appendSseEvent(
+  state: UnifiedSessionState,
+  debugEvent: { eventType: string; data: unknown },
+  env: SessionStateReducerEnvironment,
+) {
+  const newEvent: SSEEventEntry = {
+    id: env.nextEventId(),
+    eventType: debugEvent.eventType,
+    data: debugEvent.data,
+    timestamp: env.nowIso(),
+  };
+  return [...state.debug.sseEvents, newEvent].slice(-state.debug.maxEvents);
+}
+
+function createActionRejectedArtifacts(
+  reason: string,
+  targetPlayer: string | undefined,
+  env: SessionStateReducerEnvironment,
+) {
+  return {
+    notification: {
+      id: env.nextNotificationId(),
+      type: "ACTION_REJECTED" as const,
+      payload: { type: "ACTION_REJECTED" as const, reason, targetPlayer },
+      timestamp: env.nowMs(),
+      read: false,
+    },
+    hostFeedback: {
+      id: env.nextNotificationId(),
+      type: "ACTION_REJECTED" as const,
+      payload: { type: "ACTION_REJECTED" as const, reason, targetPlayer },
+      timestamp: env.nowMs(),
+    },
+  };
+}
+
+function createPromptOpenedArtifacts(
+  prompt: {
+    interactionId: string;
+    context?: { to?: string; title?: string };
+  },
+  env: SessionStateReducerEnvironment,
+) {
+  const payload = {
+    type: "PROMPT_OPENED" as const,
+    promptId: prompt.interactionId,
+    promptInstanceId: prompt.interactionId,
+    targetPlayer: prompt.context?.to ?? "",
+    title: prompt.context?.title ?? undefined,
+  };
+  return {
+    notification: {
+      id: env.nextNotificationId(),
+      type: "PROMPT_OPENED" as const,
+      payload,
+      timestamp: env.nowMs(),
+      read: false,
+    },
+    hostFeedback: {
+      id: env.nextNotificationId(),
+      type: "PROMPT_OPENED" as const,
+      payload,
+      timestamp: env.nowMs(),
+    },
+  };
+}
+
+function getOpenedPrompts(
+  previous: ReadonlyArray<{ kind: string; interactionId: string }>,
+  next: ReadonlyArray<{
+    kind: string;
+    interactionId: string;
+    context?: { to?: string; title?: string };
+  }>,
+) {
+  const previousPromptIds = new Set(
+    previous
+      .filter((descriptor) => descriptor.kind === "prompt")
+      .map((prompt) => prompt.interactionId),
+  );
+  return next.filter(
+    (descriptor) =>
+      descriptor.kind === "prompt" &&
+      !previousPromptIds.has(descriptor.interactionId),
+  );
+}
+
+function hasBoardStaticHashMismatch(
+  gameplay: GameplayViewport | null,
+  incomingGameplay: GameplayViewport,
+): boolean {
+  const incomingHash = incomingGameplay.boardStaticHash ?? null;
+  const cachedHash = gameplay?.boardStaticHash ?? null;
+  return (
+    cachedHash !== null && incomingHash !== null && incomingHash !== cachedHash
+  );
+}
+
+function applyGameplaySnapshotToState(
+  state: UnifiedSessionState,
+  gameplay: GameplayViewport,
+  context: SessionContext,
+  options: {
+    nextSyncId: number;
+    perspective: GameplayPerspective;
+    debugEvent?: { eventType: string; data: unknown };
+    env: SessionStateReducerEnvironment;
+  },
+): UnifiedSessionState {
+  const previousGameplay = getGameplayViewport(state.session);
+  const promptArtifacts = getOpenedPrompts(
+    previousGameplay?.availableInteractions ?? [],
+    gameplay.availableInteractions,
+  ).map((prompt) => createPromptOpenedArtifacts(prompt, options.env));
+  return {
+    ...state,
+    session: {
+      type: "gameplay",
+      context,
+      perspective: options.perspective,
+      gameplay,
+    },
+    activity: {
+      ...state.activity,
+      notifications: [
+        ...state.activity.notifications,
+        ...promptArtifacts.map((artifact) => artifact.notification),
+      ],
+      hostFeedback: [
+        ...state.activity.hostFeedback,
+        ...promptArtifacts.map((artifact) => artifact.hostFeedback),
+      ],
+      syncId: options.nextSyncId,
+      lastSyncTimestamp: options.env.nowMs(),
+    },
+    debug: {
+      ...state.debug,
+      sseEvents: options.debugEvent
+        ? appendSseEvent(state, options.debugEvent, options.env)
+        : state.debug.sseEvents,
+    },
+  };
+}
+
+function assertExpectedPerspectivePlayer(
+  snapshot: NormalizedSessionSnapshot,
+  expectedPlayerId: string | null | undefined,
+) {
+  if (!expectedPlayerId || snapshot.type !== "gameplay") {
+    return;
+  }
+  if (snapshot.perspective.playerId !== expectedPlayerId) {
+    throw new Error(
+      `Switch snapshot resolved ${snapshot.perspective.playerId} instead of ${expectedPlayerId}.`,
+    );
+  }
+}
+
+function reduceSnapshotLoaded(
+  state: UnifiedSessionState,
+  ingress: Extract<SessionStateIngress, { type: "snapshot.loaded" }>,
+  env: SessionStateReducerEnvironment,
+): UnifiedSessionState {
+  assertExpectedPerspectivePlayer(
+    ingress.snapshot,
+    ingress.expectedPerspectivePlayerId,
+  );
+  const context = ingress.snapshot.context;
+  const nextSyncId = state.activity.syncId + 1;
+
+  if (ingress.snapshot.type !== "gameplay") {
+    const session: UnifiedSessionModel =
+      ingress.snapshot.type === "ended"
+        ? { type: "ended", context }
+        : {
+            type: "lobby",
+            context,
+            preferredPlayerId: ingress.snapshot.preferredPlayerId,
+          };
+    return {
+      ...state,
+      session,
+      activity: {
+        ...state.activity,
+        syncId: nextSyncId,
+        lastSyncTimestamp: env.nowMs(),
+      },
+      connection: { ...state.connection, error: null },
+    };
+  }
+
+  return {
+    ...applyGameplaySnapshotToState(state, ingress.snapshot.gameplay, context, {
+      nextSyncId,
+      perspective: ingress.snapshot.perspective,
+      env,
+    }),
+    connection: { ...state.connection, error: null },
+  };
+}
+
+function reduceEventReceived(
+  state: UnifiedSessionState,
+  ingress: Extract<SessionStateIngress, { type: "event.received" }>,
+  env: SessionStateReducerEnvironment,
+): SessionStateReducerResult {
+  const context = getSessionContext(state.session);
+  const currentGameplay = getGameplayViewport(state.session);
+  const nextSyncId = state.activity.syncId + 1;
+  const debugEvent = ingress.source === "sse" ? ingress.debugEvent : undefined;
+
+  switch (ingress.event.type) {
+    case "session.snapshot": {
+      const snapshotState = reduceSnapshotLoaded(
+        state,
+        {
+          type: "snapshot.loaded",
+          source: "snapshot",
+          snapshot: ingress.event.snapshot,
+        },
+        env,
+      );
+      return {
+        state: debugEvent
+          ? {
+              ...snapshotState,
+              debug: {
+                ...snapshotState.debug,
+                sseEvents: appendSseEvent(state, debugEvent, env),
+              },
+            }
+          : snapshotState,
+        effects: [],
+      };
+    }
+    case "session.lobbyUpdated": {
+      const nextContext = ingress.event.context;
+      if (!nextContext) return { state, effects: [] };
+      return {
+        state: {
+          ...state,
+          session: withContext(state.session, nextContext),
+          activity: {
+            ...state.activity,
+            syncId: nextSyncId,
+            lastSyncTimestamp: env.nowMs(),
+          },
+          debug: {
+            ...state.debug,
+            sseEvents: debugEvent
+              ? appendSseEvent(state, debugEvent, env)
+              : state.debug.sseEvents,
+          },
+        },
+        effects: [],
+      };
+    }
+    case "session.gameplayUpdated": {
+      if (!context || !ingress.event.context) return { state, effects: [] };
+      if (
+        ingress.source === "sse" &&
+        ((state.session.type === "gameplay" &&
+          ingress.event.perspective.playerId !==
+            state.session.perspective.playerId) ||
+          (state.session.type === "gameplayLoading" &&
+            ingress.event.perspective.playerId !==
+              state.session.requestedPlayerId))
+      ) {
+        return { state, effects: [] };
+      }
+      if (
+        currentGameplay &&
+        ingress.event.gameplay.version <= currentGameplay.version
+      ) {
+        return { state, effects: [] };
+      }
+      const updatedState = applyGameplaySnapshotToState(
+        state,
+        ingress.event.gameplay,
+        ingress.event.context,
+        {
+          nextSyncId,
+          perspective: ingress.event.perspective,
+          debugEvent,
+          env,
+        },
+      );
+      const effects: SessionStateEffect[] = [
+        {
+          type: "perf.storeApplied",
+          gameplayVersion: ingress.event.gameplay.version,
+          syncId: nextSyncId,
+        },
+      ];
+      if (hasBoardStaticHashMismatch(currentGameplay, ingress.event.gameplay)) {
+        effects.push({
+          type: "requestGameplayResync",
+          sessionId: context.identity.sessionId,
+          playerId: ingress.event.perspective.playerId,
+          reason: `boardStaticHash mismatch cached=${currentGameplay?.boardStaticHash} incoming=${ingress.event.gameplay.boardStaticHash}`,
+        });
+      }
+      return { state: updatedState, effects };
+    }
+    case "session.historyUpdated": {
+      const nextContext = ingress.event.context;
+      if (!nextContext) return { state, effects: [] };
+      return {
+        state: {
+          ...state,
+          session: withContext(state.session, nextContext),
+          activity: {
+            ...state.activity,
+            syncId: nextSyncId,
+            lastSyncTimestamp: env.nowMs(),
+          },
+          debug: {
+            ...state.debug,
+            sseEvents: debugEvent
+              ? appendSseEvent(state, debugEvent, env)
+              : state.debug.sseEvents,
+          },
+        },
+        effects: [],
+      };
+    }
+    case "session.ended": {
+      const nextContext = ingress.event.context;
+      if (!nextContext) return { state, effects: [] };
+      return {
+        state: {
+          ...state,
+          session: { type: "ended", context: nextContext },
+          activity: {
+            ...state.activity,
+            syncId: nextSyncId,
+            lastSyncTimestamp: env.nowMs(),
+          },
+          debug: {
+            ...state.debug,
+            sseEvents: debugEvent
+              ? appendSseEvent(state, debugEvent, env)
+              : state.debug.sseEvents,
+          },
+        },
+        effects: [],
+      };
+    }
+    case "session.error":
+      return {
+        state: {
+          ...state,
+          session: {
+            type: "error",
+            message: ingress.event.message,
+            context: context ?? undefined,
+          },
+          activity: {
+            ...state.activity,
+            syncId: nextSyncId,
+            lastSyncTimestamp: env.nowMs(),
+          },
+          debug: {
+            ...state.debug,
+            sseEvents: debugEvent
+              ? appendSseEvent(state, debugEvent, env)
+              : state.debug.sseEvents,
+          },
+        },
+        effects: [],
+      };
+  }
+}
+
+export function reduceSessionState(
+  state: UnifiedSessionState,
+  ingress: SessionStateIngress,
+  env: SessionStateReducerEnvironment,
+): SessionStateReducerResult {
+  switch (ingress.type) {
+    case "command.loading":
+      return {
+        state: {
+          ...state,
+          session: { type: "loading", target: ingress.target },
+          connection: { ...state.connection, error: null },
+        },
+        effects: [],
+      };
+    case "command.failed":
+      return {
+        state: {
+          ...state,
+          session: {
+            type: "error",
+            message: ingress.message,
+            context: getSessionContext(state.session) ?? undefined,
+          },
+        },
+        effects: [],
+      };
+    case "snapshot.loaded":
+      return {
+        state: reduceSnapshotLoaded(state, ingress, env),
+        effects: [],
+      };
+    case "event.received":
+      return reduceEventReceived(state, ingress, env);
+    case "connection.prepared": {
+      const context = getSessionContext(state.session);
+      if (!context) return { state, effects: [] };
+      return {
+        state: {
+          ...state,
+          session: withContext(state.session, {
+            ...context,
+            userId: ingress.userId,
+            switchablePlayerIds: ingress.switchablePlayerIds,
+          }),
+          connection: { ...state.connection, error: null },
+        },
+        effects: [],
+      };
+    }
+    case "connection.changed": {
+      const connection = {
+        ...state.connection,
+        [ingress.channel]: ingress.connected,
+      };
+      return {
+        state: {
+          ...state,
+          connection: {
+            ...connection,
+            isConnected: connection.lobby || connection.gameplay,
+          },
+        },
+        effects: [],
+      };
+    }
+    case "connection.failed":
+      return {
+        state: {
+          ...state,
+          connection: { ...state.connection, error: ingress.message },
+        },
+        effects: [],
+      };
+    case "connection.errorCleared":
+      return {
+        state: {
+          ...state,
+          connection: { ...state.connection, error: null },
+        },
+        effects: [],
+      };
+    case "feedback.actionRejected": {
+      const { notification, hostFeedback } = createActionRejectedArtifacts(
+        ingress.reason,
+        ingress.targetPlayer,
+        env,
+      );
+      return {
+        state: {
+          ...state,
+          activity: {
+            ...state.activity,
+            notifications: [...state.activity.notifications, notification],
+            hostFeedback: [...state.activity.hostFeedback, hostFeedback],
+          },
+        },
+        effects: [],
+      };
+    }
+    case "local.playerSelected": {
+      const context = getSessionContext(state.session);
+      if (!context) return { state, effects: [] };
+      const controllablePlayerIds = resolveControllablePlayerIds(
+        context.switchablePlayerIds,
+        context.seats,
+        context.userId,
+        env.fallbackToAllSeatsWhenUserIdMissing,
+      );
+      if (!controllablePlayerIds.includes(ingress.playerId)) {
+        return {
+          state,
+          effects: [
+            {
+              type: "log.warn",
+              message: `[UnifiedSession] Cannot switch to ${ingress.playerId} - not controllable`,
+            },
+          ],
+        };
+      }
+      return {
+        state: {
+          ...state,
+          session: {
+            type: "gameplayLoading",
+            context,
+            requestedPlayerId: ingress.playerId,
+          },
+        },
+        effects: [
+          {
+            type: "reconnectGameplay",
+            sessionId: ingress.sessionId,
+            playerId: ingress.playerId,
+            source: "player-switch",
+          },
+        ],
+      };
+    }
+    case "activity.stateAcked":
+      return {
+        state: {
+          ...state,
+          activity: { ...state.activity, lastAckTimestamp: env.nowMs() },
+        },
+        effects: [],
+      };
+    case "activity.notificationRead":
+      return {
+        state: {
+          ...state,
+          activity: {
+            ...state.activity,
+            notifications: state.activity.notifications.map((notification) =>
+              notification.id === ingress.id
+                ? { ...notification, read: true }
+                : notification,
+            ),
+          },
+        },
+        effects: [],
+      };
+    case "activity.notificationsCleared":
+      return {
+        state: {
+          ...state,
+          activity: { ...state.activity, notifications: [] },
+        },
+        effects: [],
+      };
+    case "activity.hostFeedbackDismissed":
+      return {
+        state: {
+          ...state,
+          activity: {
+            ...state.activity,
+            hostFeedback: state.activity.hostFeedback.filter(
+              (item) => item.id !== ingress.id,
+            ),
+          },
+        },
+        effects: [],
+      };
+    case "activity.hostFeedbackCleared":
+      return {
+        state: {
+          ...state,
+          activity: { ...state.activity, hostFeedback: [] },
+        },
+        effects: [],
+      };
+    case "debug.sseEventsCleared":
+      return {
+        state: { ...state, debug: { ...state.debug, sseEvents: [] } },
+        effects: [],
+      };
+    case "streams.closed":
+      return {
+        state: {
+          ...state,
+          connection: {
+            ...state.connection,
+            lobby: false,
+            gameplay: false,
+            isConnected: false,
+          },
+        },
+        effects: [],
+      };
+    case "session.reset":
+      return { state: createInitialUnifiedSessionState(), effects: [] };
+  }
+}