dreamboard 0.1.21 → 0.1.22

package/dist/runtime-packages/ui-host-runtime/src/plugin-session-gateway.ts

@@ -0,0 +1,524 @@
+import type { PluginStateSnapshot } from "@dreamboard/ui-sdk/reducer";
+import type { ValidationResult } from "@dreamboard/ui-sdk/types/runtime-api";
+import { PluginBridge } from "./plugin-bridge.js";
+import { PluginHealthCheck } from "./plugin-health-check.js";
+import type { LoggerLike } from "./logger.js";
+import { consoleLogger } from "./logger.js";
+import { PERF_MARK_NAMES, findActionIdBySyncId, recordMark } from "./perf.js";
+
+export interface GameSessionStoreApi {
+  getStateSnapshot: () => PluginStateSnapshot;
+  subscribe: (callback: () => void) => () => void;
+  onStateAck: (syncId: number) => void;
+  markNotificationRead: (notificationId: string) => void;
+}
+
+export type GatewayState = "loading" | "handshaking" | "connected" | "error";
+
+/**
+ * Per-interaction metadata the gateway forwards from the plugin down to
+ * `onInteraction`. Currently carries just the client-minted correlation id
+ * used by Tier-0 input-latency observability; keeping it as a bag lets
+ * future perf/debug fields (e.g. plugin-side timestamps) ride along
+ * without another signature change.
+ */
+export interface InteractionMeta {
+  clientActionId?: string;
+}
+
+export interface PluginSessionGatewayConfig {
+  iframe: HTMLIFrameElement;
+  sessionId: string;
+  controllablePlayerIds: string[];
+  controllingPlayerId: string;
+  userId: string | null;
+  onReady: () => void;
+  onError: (error: Error) => void;
+  onInteraction: (
+    playerId: string,
+    interactionId: string,
+    params: unknown,
+    meta?: InteractionMeta,
+  ) => void | Promise<void>;
+  onValidateInteraction: (
+    playerId: string,
+    interactionId: string,
+    params: unknown,
+  ) => Promise<ValidationResult>;
+  onSwitchPlayer?: (playerId: string) => void;
+  onRestoreHistory?: (entryId: string) => void;
+  logger?: LoggerLike;
+}
+
+export class PluginSessionGateway {
+  private bridge: PluginBridge | null = null;
+  private healthCheck: PluginHealthCheck | null = null;
+  private state: GatewayState = "loading";
+  private unsubscribeHandlers: Array<() => void> = [];
+  private config: PluginSessionGatewayConfig;
+  private readyTimeout: ReturnType<typeof setTimeout> | null = null;
+  private initStartTimeout: ReturnType<typeof setTimeout> | null = null;
+  private initRetryInterval: ReturnType<typeof setInterval> | null = null;
+  private storeUnsubscribe: (() => void) | null = null;
+  private gameSessionStore: GameSessionStoreApi | null = null;
+  private lastSentSyncId: number | null = null;
+  private logger: LoggerLike;
+
+  constructor(config: PluginSessionGatewayConfig) {
+    this.config = config;
+    this.logger = config.logger ?? consoleLogger;
+  }
+
+  connect(): void {
+    if (this.bridge) {
+      this.logger.warn("[Gateway] Already connected");
+      return;
+    }
+
+    this.state = "loading";
+
+    const targetOrigin = "*";
+    this.bridge = new PluginBridge(this.config.iframe, targetOrigin, {
+      logger: this.logger,
+    });
+
+    this.readyTimeout = setTimeout(() => {
+      if (this.state !== "connected") {
+        this.handleError(
+          new Error("Plugin failed to send ready message within 10 seconds"),
+        );
+      }
+    }, 10000);
+
+    this.setupInteractionHandler();
+    this.setupValidateInteractionHandler();
+    this.setupReadyHandler();
+    this.setupErrorHandler();
+    this.setupSwitchPlayerHandler();
+    this.setupRestoreHistoryHandler();
+    this.setupStateAckHandler();
+    this.setupStateRenderedHandler();
+    this.setupMarkNotificationReadHandler();
+
+    this.state = "handshaking";
+
+    this.initStartTimeout = setTimeout(() => {
+      this.initStartTimeout = null;
+      if (this.state === "error") {
+        return;
+      }
+      this.sendInit();
+      this.initRetryInterval = setInterval(() => {
+        if (this.state === "connected") {
+          this.clearInitRetryInterval();
+          return;
+        }
+        this.sendInit();
+      }, 250);
+    }, 50);
+  }
+
+  attachStore(store: GameSessionStoreApi): void {
+    if (this.state !== "connected") {
+      this.logger.warn(
+        "[Gateway] Cannot attach store - plugin not ready yet (state: " +
+          this.state +
+          ")",
+      );
+      return;
+    }
+
+    if (this.storeUnsubscribe) {
+      this.logger.warn("[Gateway] Store already attached");
+      return;
+    }
+
+    this.gameSessionStore = store;
+
+    const sendStateSync = () => {
+      if (!this.bridge) return;
+
+      const snapshot = store.getStateSnapshot();
+
+      if (snapshot.syncId !== this.lastSentSyncId) {
+        this.lastSentSyncId = snapshot.syncId;
+        this.logger.log("[Gateway] State snapshot view present:", {
+          syncId: snapshot.syncId,
+          hasView: snapshot.view !== null,
+          controllingPlayerId: snapshot.session.controllingPlayerId,
+          controllablePlayerIds: snapshot.session.controllablePlayerIds,
+        });
+        this.bridge.sendStateSync(snapshot.syncId, snapshot);
+        // Tier-0 perf: stitch the outgoing state-sync to the action
+        // that caused it (via the syncId -> actionId map populated
+        // at `t5_store_applied`). For non-action-driven syncs (lobby
+        // updates etc.) the lookup returns undefined and the mark is
+        // a no-op.
+        const actionId = findActionIdBySyncId(snapshot.syncId);
+        if (actionId) {
+          recordMark(actionId, PERF_MARK_NAMES.T6_STATE_SYNC_POSTED, {
+            extra: { syncId: snapshot.syncId },
+          });
+        }
+        this.logger.log("[Gateway] Sent state-sync, syncId:", snapshot.syncId);
+      }
+    };
+
+    sendStateSync();
+
+    this.storeUnsubscribe = store.subscribe(() => {
+      sendStateSync();
+    });
+  }
+
+  getState(): GatewayState {
+    return this.state;
+  }
+
+  disconnect(): void {
+    if (this.readyTimeout) {
+      clearTimeout(this.readyTimeout);
+      this.readyTimeout = null;
+    }
+
+    if (this.initStartTimeout) {
+      clearTimeout(this.initStartTimeout);
+      this.initStartTimeout = null;
+    }
+
+    this.clearInitRetryInterval();
+
+    if (this.healthCheck) {
+      this.healthCheck.stop();
+      this.healthCheck = null;
+    }
+
+    if (this.bridge) {
+      this.bridge.disconnect();
+      this.bridge = null;
+    }
+
+    if (this.storeUnsubscribe) {
+      this.storeUnsubscribe();
+      this.storeUnsubscribe = null;
+    }
+
+    this.unsubscribeHandlers.forEach((unsubscribe) => unsubscribe());
+    this.unsubscribeHandlers = [];
+
+    this.state = "loading";
+    this.lastSentSyncId = null;
+  }
+
+  private setupReadyHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage("ready", () => {
+      if (this.readyTimeout) {
+        clearTimeout(this.readyTimeout);
+        this.readyTimeout = null;
+      }
+      this.clearInitRetryInterval();
+
+      this.state = "connected";
+
+      if (this.bridge) {
+        this.healthCheck = new PluginHealthCheck(this.bridge, {
+          onUnhealthy: () => {
+            this.handleError(new Error("Plugin iframe is unresponsive"));
+          },
+          logger: this.logger,
+        });
+        this.healthCheck.start();
+      }
+
+      this.config.onReady();
+    });
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private sendInit(): void {
+    if (!this.bridge) {
+      return;
+    }
+
+    this.bridge.sendInit(
+      this.config.sessionId,
+      this.config.controllablePlayerIds,
+      this.config.controllingPlayerId,
+      this.config.userId,
+    );
+  }
+
+  private clearInitRetryInterval(): void {
+    if (this.initRetryInterval) {
+      clearInterval(this.initRetryInterval);
+      this.initRetryInterval = null;
+    }
+  }
+
+  private setupInteractionHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage(
+      "interaction",
+      async (message) => {
+        // Tier-0 perf: record plugin-supplied `t0_click` and our own
+        // `t1_host_received` against the client-minted actionId so the
+        // rest of the pipeline (http submit, SSE, store apply) can
+        // attach their marks to the same entry.
+        if (message.clientActionId) {
+          if (typeof message.clientSubmittedAtMs === "number") {
+            recordMark(message.clientActionId, PERF_MARK_NAMES.T0_CLICK, {
+              timestampMs: message.clientSubmittedAtMs,
+              extra: { source: "plugin" },
+            });
+          }
+          recordMark(message.clientActionId, PERF_MARK_NAMES.T1_HOST_RECEIVED, {
+            extra: { messageId: message.messageId },
+          });
+        }
+
+        try {
+          await this.config.onInteraction(
+            message.playerId,
+            message.interactionId,
+            message.params,
+            message.clientActionId
+              ? { clientActionId: message.clientActionId }
+              : undefined,
+          );
+          this.sendSubmitResult(message.messageId, { accepted: true });
+        } catch (error) {
+          this.logger.error("[Gateway] Interaction submission error:", error);
+          this.sendSubmitResult(
+            message.messageId,
+            this.describeSubmissionFailure(error, "Interaction rejected"),
+          );
+        }
+      },
+    );
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private setupValidateInteractionHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage(
+      "validate-interaction",
+      async (message) => {
+        try {
+          const result = await this.config.onValidateInteraction(
+            message.playerId,
+            message.interactionId,
+            message.params,
+          );
+
+          this.bridge?.send({
+            type: "validate-interaction-result",
+            messageId: message.messageId,
+            result,
+          });
+        } catch (error) {
+          this.logger.error("[Gateway] Validate interaction error:", error);
+
+          this.bridge?.send({
+            type: "validate-interaction-result",
+            messageId: message.messageId,
+            result: {
+              valid: false,
+              errorCode: "validation-error",
+              message:
+                error instanceof Error ? error.message : "Validation failed",
+            },
+          });
+        }
+      },
+    );
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private setupErrorHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage("error", (message) => {
+      this.logger.error("[Gateway] Plugin error:", message.message);
+      if (message.code) {
+        this.logger.error("[Gateway] Error code:", message.code);
+      }
+      const error = new Error(
+        message.code ? `${message.code}: ${message.message}` : message.message,
+      );
+      error.name = "PluginRuntimeError";
+      this.handleError(error);
+    });
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private setupSwitchPlayerHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage(
+      "switch-player",
+      (message) => {
+        this.logger.log("[Gateway] Switch player request:", message.playerId);
+        if (this.config.onSwitchPlayer) {
+          this.config.onSwitchPlayer(message.playerId);
+        }
+      },
+    );
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private setupRestoreHistoryHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage(
+      "restore-history",
+      (message) => {
+        this.logger.log("[Gateway] Restore history request:", message.entryId);
+        if (this.config.onRestoreHistory) {
+          this.config.onRestoreHistory(message.entryId);
+        }
+      },
+    );
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private setupStateAckHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage("state-ack", (message) => {
+      this.logger.log("[Gateway] Received state-ack, syncId:", message.syncId);
+      // Tier-0 perf: mark `t7_state_sync_received` using the plugin's
+      // own `Date.now()` captured at state-sync receipt. Uses the
+      // syncId -> actionId map populated at t5.
+      if (typeof message.clientReceivedAtMs === "number") {
+        const actionId = findActionIdBySyncId(message.syncId);
+        if (actionId) {
+          recordMark(actionId, PERF_MARK_NAMES.T7_STATE_SYNC_RECEIVED, {
+            timestampMs: message.clientReceivedAtMs,
+            extra: { syncId: message.syncId, source: "plugin" },
+          });
+        }
+      }
+      this.gameSessionStore?.onStateAck(message.syncId);
+    });
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private setupStateRenderedHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage(
+      "state-rendered",
+      (message) => {
+        // Tier-0 perf only: the plugin sends this after its post-sync
+        // microtask/rAF completes so the host HUD can show t8 - t0
+        // ("total" click-to-render). No functional side effects.
+        const actionId = findActionIdBySyncId(message.syncId);
+        if (!actionId) return;
+        recordMark(actionId, PERF_MARK_NAMES.T7_STATE_SYNC_RECEIVED, {
+          timestampMs: message.clientReceivedAtMs,
+          extra: { syncId: message.syncId, source: "plugin" },
+        });
+        recordMark(actionId, PERF_MARK_NAMES.T8_RENDER_COMMIT, {
+          timestampMs: message.clientRenderedAtMs,
+          extra: { syncId: message.syncId, source: "plugin" },
+        });
+      },
+    );
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private setupMarkNotificationReadHandler(): void {
+    if (!this.bridge) return;
+
+    const unsubscribe = this.bridge.onPluginMessage(
+      "mark-notification-read",
+      (message) => {
+        this.logger.log(
+          "[Gateway] Mark notification read:",
+          message.notificationId,
+        );
+        this.gameSessionStore?.markNotificationRead(message.notificationId);
+      },
+    );
+
+    this.unsubscribeHandlers.push(unsubscribe);
+  }
+
+  private handleError(error: Error): void {
+    if (this.state === "error") {
+      return;
+    }
+    if (this.readyTimeout) {
+      clearTimeout(this.readyTimeout);
+      this.readyTimeout = null;
+    }
+    if (this.initStartTimeout) {
+      clearTimeout(this.initStartTimeout);
+      this.initStartTimeout = null;
+    }
+    this.clearInitRetryInterval();
+    if (this.healthCheck) {
+      this.healthCheck.stop();
+      this.healthCheck = null;
+    }
+    this.logger.error("[Gateway] Error:", error);
+    this.state = "error";
+    this.config.onError(error);
+  }
+
+  private sendSubmitResult(
+    messageId: string,
+    result: {
+      accepted: boolean;
+      errorCode?: string;
+      message?: string;
+    },
+  ): void {
+    this.bridge?.sendSubmitResult({
+      messageId,
+      accepted: result.accepted,
+      errorCode: result.errorCode,
+      message: result.message,
+    });
+  }
+
+  private describeSubmissionFailure(
+    error: unknown,
+    fallbackMessage: string,
+  ): {
+    accepted: false;
+    errorCode?: string;
+    message: string;
+  } {
+    const errorCode =
+      typeof error === "object" &&
+      error !== null &&
+      "errorCode" in error &&
+      typeof error.errorCode === "string"
+        ? error.errorCode
+        : undefined;
+    const message =
+      error instanceof Error
+        ? error.message
+        : typeof error === "string"
+          ? error
+          : fallbackMessage;
+    return {
+      accepted: false,
+      errorCode,
+      message,
+    };
+  }
+}

package/dist/runtime-packages/ui-host-runtime/src/runtime/index.ts

@@ -0,0 +1,12 @@
+export * from "../actor-principal.js";
+export * from "../logger.js";
+export * from "../host-session-transport.js";
+export * from "../perf.js";
+export * from "../plugin-bridge.js";
+export * from "../plugin-health-check.js";
+export * from "../plugin-messages.js";
+export * from "../plugin-session-gateway.js";
+export * from "../screenshot/projection-to-snapshot.js";
+export * from "../screenshot/static-store-api.js";
+export * from "../sse-manager.js";
+export * from "../unified-session-store.js";

package/dist/runtime-packages/ui-host-runtime/src/screenshot/projection-to-snapshot.ts

@@ -0,0 +1,122 @@
+import type { SeatAssignment } from "@dreamboard/api-client";
+import type { PluginStateSnapshot } from "@dreamboard/ui-sdk/reducer";
+import { seatsForPluginSnapshot } from "../actor-principal.js";
+
+const DEFAULT_PLAYER_IDS = [
+  "player-1",
+  "player-2",
+  "player-3",
+  "player-4",
+] as const;
+
+const PLAYER_COLORS = [
+  "#f97316",
+  "#0ea5e9",
+  "#22c55e",
+  "#a855f7",
+  "#ef4444",
+  "#eab308",
+] as const;
+
+export interface ScreenshotProjection {
+  currentPhase?: string | null;
+  currentStage?: string | null;
+  stageSeats?: string[];
+  simultaneousPhase?: PluginStateSnapshot["gameplay"]["simultaneousPhase"];
+  view?: unknown;
+  availableInteractions?: PluginStateSnapshot["gameplay"]["availableInteractions"];
+  zones?: PluginStateSnapshot["gameplay"]["zones"];
+}
+
+export interface ProjectionToSnapshotOptions {
+  sessionId?: string | null;
+  userId?: string | null;
+  controllingPlayerId?: string;
+  playerIds?: string[];
+  syncId?: number;
+}
+
+export function projectionToSnapshot(
+  projection: ScreenshotProjection,
+  options: ProjectionToSnapshotOptions = {},
+): PluginStateSnapshot {
+  const controllingPlayerId =
+    options.controllingPlayerId ??
+    projection.stageSeats?.[0] ??
+    DEFAULT_PLAYER_IDS[0];
+  const playerIds = normalizePlayerIds(options.playerIds, controllingPlayerId);
+  const userId = options.userId ?? "screenshot-user";
+  const seats = buildSeatAssignments(playerIds, userId);
+
+  return {
+    view: (projection.view ?? null) as PluginStateSnapshot["view"],
+    gameplay: {
+      currentPhase:
+        projection.currentPhase ??
+        viewCurrentPhase(projection.view) ??
+        projection.currentStage ??
+        null,
+      currentStage: projection.currentStage ?? null,
+      activePlayers:
+        projection.stageSeats && projection.stageSeats.length > 0
+          ? projection.stageSeats
+          : [controllingPlayerId],
+      simultaneousPhase: projection.simultaneousPhase ?? null,
+      availableInteractions: projection.availableInteractions ?? [],
+      zones: projection.zones ?? {},
+    },
+    lobby: {
+      seats: seatsForPluginSnapshot(seats),
+      canStart: true,
+      hostUserId: userId,
+    },
+    notifications: [],
+    session: {
+      sessionId: options.sessionId ?? null,
+      controllablePlayerIds: [controllingPlayerId],
+      controllingPlayerId,
+      userId,
+    },
+    history: null,
+    syncId: options.syncId ?? 1,
+  };
+}
+
+function viewCurrentPhase(view: unknown): string | null {
+  if (!view || typeof view !== "object" || !("currentPhase" in view)) {
+    return null;
+  }
+  const value = (view as { currentPhase?: unknown }).currentPhase;
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function normalizePlayerIds(
+  playerIds: string[] | undefined,
+  controllingPlayerId: string,
+): string[] {
+  const normalized = (playerIds?.length ? playerIds : [...DEFAULT_PLAYER_IDS])
+    .map((playerId) => playerId.trim())
+    .filter(Boolean);
+  return Array.from(new Set([controllingPlayerId, ...normalized]));
+}
+
+function buildSeatAssignments(
+  playerIds: string[],
+  userId: string,
+): SeatAssignment[] {
+  return playerIds.map((playerId, index) => ({
+    playerId,
+    controllerActor: {
+      kind: "DEMO_GUEST",
+      demoActorSessionId: userId,
+    },
+    displayName: displayNameForPlayer(playerId),
+    playerColor: PLAYER_COLORS[index % PLAYER_COLORS.length],
+    isHost: index === 0,
+  }));
+}
+
+function displayNameForPlayer(playerId: string): string {
+  const match = /^player-(\d+)$/.exec(playerId);
+  return match ? `Player ${match[1]}` : playerId;
+}

package/dist/runtime-packages/ui-host-runtime/src/screenshot/static-store-api.ts

@@ -0,0 +1,26 @@
+import type { PluginStateSnapshot } from "@dreamboard/ui-sdk/reducer";
+import type { GameSessionStoreApi } from "../plugin-session-gateway.js";
+
+export function createStaticStoreApi(
+  snapshot: PluginStateSnapshot,
+): GameSessionStoreApi {
+  const frozenSnapshot = deepFreeze(snapshot);
+  return {
+    getStateSnapshot: () => frozenSnapshot,
+    subscribe: () => () => undefined,
+    onStateAck: () => undefined,
+    markNotificationRead: () => undefined,
+  };
+}
+
+function deepFreeze<T>(value: T): T {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) {
+    return value;
+  }
+
+  for (const nested of Object.values(value as Record<string, unknown>)) {
+    deepFreeze(nested);
+  }
+
+  return Object.freeze(value);
+}