dreamboard 0.1.21 → 0.1.22

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

@@ -0,0 +1,162 @@
+import {
+  disconnectSessionEvents,
+  getSessionByShortCode,
+  getSessionSnapshot,
+  restoreHistory,
+  startGame,
+  submitPlayerAction,
+  subscribeToSessionEvents,
+} from "@dreamboard/api-client";
+import type {
+  HostActionSubmitWireResponse,
+  HostSessionWireEvent,
+  HostSessionWireSnapshot,
+} from "./session-ingress.js";
+
+export interface HostSessionStream {
+  stream: AsyncIterable<HostSessionWireEvent | null | undefined>;
+}
+
+export interface HostSessionTransport {
+  loadSessionByShortCode(input: {
+    shortCode: string;
+    requestedPlayerId?: string | null;
+  }): Promise<HostSessionWireSnapshot>;
+  loadSessionSnapshot(input: {
+    sessionId: string;
+    requestedPlayerId?: string | null;
+  }): Promise<HostSessionWireSnapshot>;
+  startSession(input: { sessionId: string }): Promise<HostSessionWireSnapshot>;
+  createDevSessionSnapshot?(input: {
+    seed?: number | null;
+  }): Promise<HostSessionWireSnapshot>;
+  submitInteraction(input: {
+    sessionId: string;
+    playerId: string;
+    interactionId: string;
+    expectedVersion: number;
+    actionSetVersion: string;
+    params: unknown;
+    clientActionId?: string | null;
+  }): Promise<HostActionSubmitWireResponse>;
+  restoreHistory(input: { sessionId: string; entryId: string }): Promise<void>;
+  subscribeToSessionEvents(input: {
+    sessionId: string;
+    clientId: string;
+    connectionAttemptId: string;
+    clientSource?: string;
+    playerId?: string;
+    signal?: AbortSignal;
+    onSseError?: (error: unknown) => void;
+  }): Promise<HostSessionStream>;
+  disconnectSessionEvents(input: {
+    sessionId: string;
+    clientId: string;
+    connectionAttemptId: string;
+    playerId?: string;
+  }): Promise<void>;
+}
+
+const CLIENT_ACTION_ID_HEADER = "X-Dreamboard-Client-Action-Id";
+
+function asInputs(params: unknown): Record<string, unknown> {
+  return params && typeof params === "object" && !Array.isArray(params)
+    ? (params as Record<string, unknown>)
+    : {};
+}
+
+async function requireData<T>(
+  result: { data?: T; error?: unknown },
+  message: string,
+): Promise<T> {
+  if (result.error || !result.data) {
+    throw result.error ?? new Error(message);
+  }
+  return result.data;
+}
+
+export const defaultHostSessionTransport: HostSessionTransport = {
+  async loadSessionByShortCode(input) {
+    return requireData(
+      await getSessionByShortCode({
+        path: { shortCode: input.shortCode },
+        query: input.requestedPlayerId
+          ? { playerId: input.requestedPlayerId }
+          : undefined,
+      }),
+      "Failed to load session by short code",
+    );
+  },
+  async loadSessionSnapshot(input) {
+    return requireData(
+      await getSessionSnapshot({
+        path: { sessionId: input.sessionId },
+        query: input.requestedPlayerId
+          ? { playerId: input.requestedPlayerId }
+          : undefined,
+      }),
+      "Failed to load session snapshot",
+    );
+  },
+  async startSession(input) {
+    return requireData(
+      await startGame({ path: { sessionId: input.sessionId } }),
+      "Failed to start session",
+    );
+  },
+  async submitInteraction(input) {
+    const headers = input.clientActionId
+      ? { [CLIENT_ACTION_ID_HEADER]: input.clientActionId }
+      : undefined;
+    return requireData(
+      await submitPlayerAction({
+        path: {
+          sessionId: input.sessionId,
+          playerId: input.playerId,
+          interactionId: input.interactionId,
+        },
+        body: {
+          expectedVersion: input.expectedVersion,
+          actionSetVersion: input.actionSetVersion,
+          inputs: asInputs(input.params) as never,
+        },
+        ...(headers ? { headers } : {}),
+      }),
+      "Failed to submit interaction",
+    );
+  },
+  async restoreHistory(input) {
+    const { error } = await restoreHistory({
+      path: { sessionId: input.sessionId },
+      body: { entryId: input.entryId },
+    });
+    if (error) {
+      throw error;
+    }
+  },
+  async subscribeToSessionEvents(input) {
+    const result = await subscribeToSessionEvents({
+      path: { sessionId: input.sessionId },
+      query: {
+        clientId: input.clientId,
+        connectionAttemptId: input.connectionAttemptId,
+        clientSource: input.clientSource,
+        playerId: input.playerId,
+      },
+      sseMaxRetryAttempts: 0,
+      signal: input.signal,
+      onSseError: input.onSseError,
+    });
+    return { stream: result.stream };
+  },
+  async disconnectSessionEvents(input) {
+    await disconnectSessionEvents({
+      path: { sessionId: input.sessionId },
+      query: {
+        clientId: input.clientId,
+        connectionAttemptId: input.connectionAttemptId,
+        playerId: input.playerId,
+      },
+    });
+  },
+};

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

@@ -0,0 +1,2 @@
+export * from "./components/index.js";
+export * from "./runtime/index.js";

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

@@ -0,0 +1,11 @@
+export interface LoggerLike {
+  log: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+export const consoleLogger: LoggerLike = {
+  log: (...args) => console.log(...args),
+  warn: (...args) => console.warn(...args),
+  error: (...args) => console.error(...args),
+};

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

@@ -0,0 +1,253 @@
+/**
+ * Dev-only Tier-0 input-latency perf instrumentation.
+ *
+ * This module is used by the web host (and re-exported for the dev HUD)
+ * to record `t0..t8` timing marks for each submitted interaction,
+ * keyed by the client-minted `clientActionId`. It is deliberately
+ * stateless across page reloads (in-memory ring buffer on `window`)
+ * and gated behind `import.meta.env.DEV` or
+ * `localStorage.getItem("dreamboard.perf") === "1"` so prod users
+ * pay nothing.
+ *
+ * Design notes
+ * - The plugin iframe lives in a separate window/performance context,
+ *   so plugin-side `performance.mark` entries are not reachable from
+ *   the host. We work around this by shipping plugin-minted `Date.now()`
+ *   timestamps across `postMessage` boundaries and recording them on
+ *   the host-side buffer keyed by `clientActionId`. Date.now() is used
+ *   (not `performance.now()`) because it shares a wall-clock base
+ *   across the iframe and the host.
+ * - SSE `gameplay.updated` messages do not carry `clientActionId`; they
+ *   carry `version`. The host records a `version -> actionId` mapping
+ *   on `t3_http_response` (when the POST action submit response comes back
+ *   with `version`) so downstream marks (`t4_sse_received`,
+ *   `t5_store_applied`, `t6_state_sync_posted`) can be stitched by
+ *   version. Similarly `syncId -> actionId` is captured at `t5` so
+ *   plugin-side state-ack / state-rendered callbacks (which carry
+ *   `syncId`) can resolve back to the originating action.
+ */
+
+export const PERF_MARK_NAMES = {
+  T0_CLICK: "t0_click",
+  T1_HOST_RECEIVED: "t1_host_received",
+  T2_HTTP_SENT: "t2_http_sent",
+  T3_HTTP_RESPONSE: "t3_http_response",
+  /**
+   * Fires when the store applies the submitter's gameplay snapshot
+   * directly from the HTTP response (the Phase B2 eager-apply path).
+   * Sits between `t3_http_response` and `t5_store_applied`; its delta
+   * vs `t3_http_response` measures pure apply-in-store cost and its
+   * delta vs `t4_sse_received` tells us how much SSE tail the eager
+   * apply cuts off for the submitter.
+   */
+  T3B_RESPONSE_APPLIED: "t3b_response_applied",
+  T4_SSE_RECEIVED: "t4_sse_received",
+  T5_STORE_APPLIED: "t5_store_applied",
+  T6_STATE_SYNC_POSTED: "t6_state_sync_posted",
+  T7_STATE_SYNC_RECEIVED: "t7_state_sync_received",
+  T8_RENDER_COMMIT: "t8_render_commit",
+} as const;
+
+export type PerfMarkName =
+  (typeof PERF_MARK_NAMES)[keyof typeof PERF_MARK_NAMES];
+
+export interface PerfMarkRecord {
+  name: string;
+  timestampMs: number;
+  extra?: Record<string, unknown>;
+}
+
+export interface PerfEntry {
+  clientActionId: string;
+  version?: number;
+  syncId?: number;
+  createdAtMs: number;
+  marks: PerfMarkRecord[];
+}
+
+interface PerfBuffer {
+  entries: PerfEntry[];
+  versionIndex: Map<number, string>;
+  syncIdIndex: Map<number, string>;
+}
+
+const GLOBAL_KEY = "__dreamboardPerf__";
+const DUMP_KEY = "__dreamboardPerfDump__";
+const MAX_ENTRIES = 50;
+
+type PerfGlobal = typeof globalThis & {
+  [GLOBAL_KEY]?: PerfBuffer;
+  [DUMP_KEY]?: () => PerfEntry[];
+};
+
+function getBuffer(): PerfBuffer | null {
+  if (typeof globalThis === "undefined") {
+    return null;
+  }
+  const scope = globalThis as PerfGlobal;
+  const existing = scope[GLOBAL_KEY];
+  if (existing) {
+    return existing;
+  }
+  const buffer: PerfBuffer = {
+    entries: [],
+    versionIndex: new Map(),
+    syncIdIndex: new Map(),
+  };
+  scope[GLOBAL_KEY] = buffer;
+  scope[DUMP_KEY] = () => buffer.entries.slice();
+  return buffer;
+}
+
+/**
+ * Perf marks + HUD are off by default in prod. Enabled in dev builds
+ * or when a maintainer opts in via `localStorage.dreamboard.perf = 1`.
+ */
+export function isPerfEnabled(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  try {
+    const env = (import.meta as unknown as { env?: { DEV?: boolean } }).env;
+    if (env?.DEV) {
+      return true;
+    }
+  } catch {
+    // import.meta may be unavailable in non-Vite contexts; fall through
+  }
+  try {
+    return window.localStorage.getItem("dreamboard.perf") === "1";
+  } catch {
+    return false;
+  }
+}
+
+function nowMs(): number {
+  return Date.now();
+}
+
+function findOrCreateEntry(
+  buffer: PerfBuffer,
+  clientActionId: string,
+): PerfEntry {
+  const existing = buffer.entries.find(
+    (entry) => entry.clientActionId === clientActionId,
+  );
+  if (existing) {
+    return existing;
+  }
+  const created: PerfEntry = {
+    clientActionId,
+    createdAtMs: nowMs(),
+    marks: [],
+  };
+  buffer.entries.push(created);
+  while (buffer.entries.length > MAX_ENTRIES) {
+    const evicted = buffer.entries.shift();
+    if (!evicted) break;
+    if (evicted.version !== undefined) {
+      buffer.versionIndex.delete(evicted.version);
+    }
+    if (evicted.syncId !== undefined) {
+      buffer.syncIdIndex.delete(evicted.syncId);
+    }
+  }
+  return created;
+}
+
+export interface RecordMarkOptions {
+  timestampMs?: number;
+  extra?: Record<string, unknown>;
+}
+
+/**
+ * Record a perf mark against a `clientActionId`. No-ops silently when
+ * perf is disabled or the runtime has no usable window/globalThis.
+ */
+export function recordMark(
+  clientActionId: string | undefined | null,
+  name: string,
+  options: RecordMarkOptions = {},
+): void {
+  if (!clientActionId) return;
+  if (!isPerfEnabled()) return;
+  const buffer = getBuffer();
+  if (!buffer) return;
+
+  const timestampMs = options.timestampMs ?? nowMs();
+  const entry = findOrCreateEntry(buffer, clientActionId);
+  entry.marks.push({
+    name,
+    timestampMs,
+    extra: options.extra,
+  });
+
+  if (
+    typeof performance !== "undefined" &&
+    typeof performance.mark === "function"
+  ) {
+    try {
+      performance.mark(`dreamboard.${name}.${clientActionId}`, {
+        detail: { clientActionId, ...options.extra },
+      });
+    } catch {
+      // performance.mark detail arg not supported in older browsers; ignore
+    }
+  }
+}
+
+/**
+ * Associate the server-returned `version` (from SubmitInputResponse)
+ * with a client-minted actionId so downstream SSE marks keyed by
+ * `version` can resolve back to the original action.
+ */
+export function correlateVersion(
+  clientActionId: string,
+  version: number,
+): void {
+  if (!isPerfEnabled()) return;
+  const buffer = getBuffer();
+  if (!buffer) return;
+  const entry = findOrCreateEntry(buffer, clientActionId);
+  entry.version = version;
+  buffer.versionIndex.set(version, clientActionId);
+}
+
+/**
+ * Associate the local `syncId` assigned when the store applies the
+ * gameplay.updated with a clientActionId, so plugin-side state-ack /
+ * state-rendered callbacks (which carry syncId rather than actionId)
+ * can resolve back to the original action.
+ */
+export function correlateSyncId(clientActionId: string, syncId: number): void {
+  if (!isPerfEnabled()) return;
+  const buffer = getBuffer();
+  if (!buffer) return;
+  const entry = findOrCreateEntry(buffer, clientActionId);
+  entry.syncId = syncId;
+  buffer.syncIdIndex.set(syncId, clientActionId);
+}
+
+export function findActionIdByVersion(version: number): string | undefined {
+  const buffer = getBuffer();
+  return buffer?.versionIndex.get(version);
+}
+
+export function findActionIdBySyncId(syncId: number): string | undefined {
+  const buffer = getBuffer();
+  return buffer?.syncIdIndex.get(syncId);
+}
+
+export function getPerfEntries(): PerfEntry[] {
+  const buffer = getBuffer();
+  return buffer ? buffer.entries.slice() : [];
+}
+
+/** Drop every recorded entry; used by tests and the HUD "Clear" action. */
+export function clearPerfEntries(): void {
+  const buffer = getBuffer();
+  if (!buffer) return;
+  buffer.entries = [];
+  buffer.versionIndex.clear();
+  buffer.syncIdIndex.clear();
+}

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

@@ -0,0 +1,195 @@
+import type { PluginStateSnapshot } from "@dreamboard/ui-sdk/reducer";
+import {
+  MainToPluginMessageSchema,
+  PluginToMainMessageSchema,
+  type MainToPluginMessage,
+  type PluginToMainMessage,
+} from "./plugin-messages.js";
+import type { LoggerLike } from "./logger.js";
+import { consoleLogger } from "./logger.js";
+
+type MessageHandler<T> = (data: T) => void;
+
+export interface PluginBridgeOptions {
+  logger?: LoggerLike;
+}
+
+export class PluginBridge {
+  private iframe: HTMLIFrameElement;
+  private targetOrigin: string;
+  private allowedOrigins: Set<string>;
+  private handlers: Map<
+    PluginToMainMessage["type"],
+    Set<MessageHandler<PluginToMainMessage>>
+  > = new Map();
+  private messageListener: ((event: MessageEvent) => void) | null = null;
+  private logger: LoggerLike;
+
+  constructor(
+    iframe: HTMLIFrameElement,
+    targetOrigin: string,
+    options: PluginBridgeOptions = {},
+  ) {
+    if (!iframe.contentWindow) {
+      throw new Error("iframe.contentWindow is not available");
+    }
+
+    this.iframe = iframe;
+    this.targetOrigin = targetOrigin;
+    this.allowedOrigins = resolveAllowedOrigins(iframe);
+    this.logger = options.logger ?? consoleLogger;
+    this.setupMessageListener();
+  }
+
+  private validateOrigin(origin: string): boolean {
+    return this.allowedOrigins.has(origin);
+  }
+
+  private setupMessageListener(): void {
+    this.messageListener = (event: MessageEvent) => {
+      if (event.source !== this.iframe.contentWindow) {
+        return;
+      }
+      if (!this.validateOrigin(event.origin)) {
+        return;
+      }
+
+      const result = PluginToMainMessageSchema.safeParse(event.data);
+      if (!result.success) {
+        return;
+      }
+
+      this.emit(result.data.type, result.data);
+    };
+
+    window.addEventListener("message", this.messageListener);
+  }
+
+  sendInit(
+    sessionId: string,
+    controllablePlayerIds: string[],
+    controllingPlayerId: string,
+    userId: string | null,
+  ): void {
+    this.sendToPlugin({
+      type: "init",
+      sessionId,
+      controllablePlayerIds,
+      controllingPlayerId,
+      userId,
+    });
+  }
+
+  sendPing(): void {
+    this.sendToPlugin({
+      type: "ping",
+    });
+  }
+
+  sendStateSync(syncId: number, state: PluginStateSnapshot): void {
+    this.sendToPlugin({
+      type: "state-sync",
+      syncId,
+      state,
+    });
+  }
+
+  sendSubmitResult(result: {
+    messageId: string;
+    accepted: boolean;
+    errorCode?: string;
+    message?: string;
+  }): void {
+    this.sendToPlugin({
+      type: "submit-result",
+      ...result,
+    });
+  }
+
+  send(message: Record<string, unknown>): void {
+    if (!this.iframe.contentWindow) {
+      this.logger.error(
+        "[PluginBridge] iframe contentWindow not available for message:",
+        message.type,
+      );
+      return;
+    }
+
+    this.iframe.contentWindow.postMessage(message, this.targetOrigin);
+  }
+
+  private sendToPlugin(message: MainToPluginMessage): void {
+    if (!this.iframe.contentWindow) {
+      this.logger.error(
+        "[PluginBridge] iframe contentWindow not available for message:",
+        message.type,
+      );
+      return;
+    }
+
+    const result = MainToPluginMessageSchema.safeParse(message);
+    if (!result.success) {
+      this.logger.error(
+        "[PluginBridge] Failed to validate outgoing message:",
+        message,
+      );
+      return;
+    }
+
+    this.iframe.contentWindow.postMessage(result.data, this.targetOrigin);
+  }
+
+  onPluginMessage<T extends PluginToMainMessage["type"]>(
+    type: T,
+    handler: MessageHandler<Extract<PluginToMainMessage, { type: T }>>,
+  ): () => void {
+    if (!this.handlers.has(type)) {
+      this.handlers.set(type, new Set());
+    }
+
+    const handlers = this.handlers.get(type);
+    if (!handlers) {
+      throw new Error(`Handler for type ${type} not found`);
+    }
+
+    handlers.add(handler as MessageHandler<PluginToMainMessage>);
+
+    return () => {
+      handlers.delete(handler as MessageHandler<PluginToMainMessage>);
+    };
+  }
+
+  private emit(
+    type: PluginToMainMessage["type"],
+    data: PluginToMainMessage,
+  ): void {
+    const handlers = this.handlers.get(type);
+    if (handlers) {
+      handlers.forEach((handler) => handler(data));
+    }
+  }
+
+  disconnect(): void {
+    if (this.messageListener) {
+      window.removeEventListener("message", this.messageListener);
+      this.messageListener = null;
+    }
+
+    this.handlers.clear();
+  }
+}
+
+function resolveAllowedOrigins(iframe: HTMLIFrameElement): Set<string> {
+  const allowedOrigins = new Set<string>(["null"]);
+
+  try {
+    const iframeUrl = new URL(iframe.src, window.location.href);
+    if (iframeUrl.origin && iframeUrl.origin !== "null") {
+      allowedOrigins.add(iframeUrl.origin);
+    }
+  } catch {
+    // Ignore invalid or unset iframe URLs and keep the sandboxed null origin.
+  }
+
+  return allowedOrigins;
+}