dreamboard 0.1.21 → 0.1.22

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

@@ -0,0 +1,138 @@
+import { PluginBridge } from "./plugin-bridge.js";
+import type { LoggerLike } from "./logger.js";
+import { consoleLogger } from "./logger.js";
+
+export interface HealthCheckConfig {
+  pingInterval: number;
+  pongTimeout: number;
+  maxMissedPongs: number;
+}
+
+const DEFAULT_CONFIG: HealthCheckConfig = {
+  pingInterval: 5000,
+  pongTimeout: 2000,
+  maxMissedPongs: 3,
+};
+
+export class PluginHealthCheck {
+  private bridge: PluginBridge;
+  private config: HealthCheckConfig;
+  private onUnhealthy: () => void;
+  private logger: LoggerLike;
+
+  private pingIntervalId: ReturnType<typeof setInterval> | null = null;
+  private pongTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  private missedPongCount = 0;
+  private isRunning = false;
+  private pongUnsubscribe: (() => void) | null = null;
+
+  constructor(
+    bridge: PluginBridge,
+    options: {
+      config?: Partial<HealthCheckConfig>;
+      onUnhealthy: () => void;
+      logger?: LoggerLike;
+    },
+  ) {
+    this.bridge = bridge;
+    this.config = { ...DEFAULT_CONFIG, ...options.config };
+    this.onUnhealthy = options.onUnhealthy;
+    this.logger = options.logger ?? consoleLogger;
+  }
+
+  start(): void {
+    if (this.isRunning) {
+      this.logger.warn("[HealthCheck] Already running");
+      return;
+    }
+
+    this.isRunning = true;
+    this.missedPongCount = 0;
+
+    this.pongUnsubscribe = this.bridge.onPluginMessage("pong", () => {
+      this.handlePong();
+    });
+
+    this.pingIntervalId = setInterval(() => {
+      this.sendPing();
+    }, this.config.pingInterval);
+
+    this.sendPing();
+  }
+
+  stop(): void {
+    if (!this.isRunning) {
+      return;
+    }
+
+    this.isRunning = false;
+
+    if (this.pingIntervalId) {
+      clearInterval(this.pingIntervalId);
+      this.pingIntervalId = null;
+    }
+
+    if (this.pongTimeoutId) {
+      clearTimeout(this.pongTimeoutId);
+      this.pongTimeoutId = null;
+    }
+
+    if (this.pongUnsubscribe) {
+      this.pongUnsubscribe();
+      this.pongUnsubscribe = null;
+    }
+
+    this.missedPongCount = 0;
+    this.logger.log("[HealthCheck] Stopped monitoring");
+  }
+
+  private sendPing(): void {
+    if (!this.isRunning) {
+      return;
+    }
+
+    if (this.pongTimeoutId) {
+      clearTimeout(this.pongTimeoutId);
+    }
+
+    this.bridge.sendPing();
+
+    this.pongTimeoutId = setTimeout(() => {
+      this.handleMissedPong();
+    }, this.config.pongTimeout);
+  }
+
+  private handlePong(): void {
+    if (this.pongTimeoutId) {
+      clearTimeout(this.pongTimeoutId);
+      this.pongTimeoutId = null;
+    }
+
+    if (this.missedPongCount > 0) {
+      this.logger.log("[HealthCheck] Plugin recovered");
+      this.missedPongCount = 0;
+    }
+  }
+
+  private handleMissedPong(): void {
+    this.missedPongCount++;
+
+    this.logger.warn(
+      `[HealthCheck] Missed pong #${this.missedPongCount}/${this.config.maxMissedPongs}`,
+    );
+
+    if (this.missedPongCount >= this.config.maxMissedPongs) {
+      this.logger.error("[HealthCheck] Plugin iframe is unresponsive!");
+      this.stop();
+      this.onUnhealthy();
+    }
+  }
+
+  isHealthCheckRunning(): boolean {
+    return this.isRunning;
+  }
+
+  getMissedPongCount(): number {
+    return this.missedPongCount;
+  }
+}

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

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import type { PluginStateSnapshot } from "@dreamboard/ui-sdk/reducer";
+
+export const InitMessageSchema = z.object({
+  type: z.literal("init"),
+  sessionId: z.string(),
+  controllablePlayerIds: z.array(z.string()),
+  controllingPlayerId: z.string(),
+  userId: z.string().nullable(),
+});
+
+export const PingMessageSchema = z.object({
+  type: z.literal("ping"),
+});
+
+export const StateSyncMessageSchema = z.object({
+  type: z.literal("state-sync"),
+  syncId: z.number(),
+  state: z.custom<PluginStateSnapshot>((data) => {
+    return (
+      typeof data === "object" &&
+      data !== null &&
+      "session" in data &&
+      "notifications" in data
+    );
+  }),
+});
+
+export const SubmitResultMessageSchema = z.object({
+  type: z.literal("submit-result"),
+  messageId: z.string(),
+  accepted: z.boolean(),
+  errorCode: z.string().optional(),
+  message: z.string().optional(),
+});
+
+export const MainToPluginMessageSchema = z.discriminatedUnion("type", [
+  InitMessageSchema,
+  PingMessageSchema,
+  StateSyncMessageSchema,
+  SubmitResultMessageSchema,
+]);
+
+export type MainToPluginMessage = z.infer<typeof MainToPluginMessageSchema>;
+
+export const ReadyMessageSchema = z.object({
+  type: z.literal("ready"),
+});
+
+// `params` is intentionally `z.unknown()` rather than `z.record(...)`. The
+// unified interaction wire carries every player input — actions and prompt
+// responses alike — and the ingress layer's `runtimePayloadSchema` already
+// accepts scalars (`z.boolean() | z.number() | z.string() | z.null() |
+// Array<...> | Record<...>`). Constraining this bridge field to an object
+// would make the host stricter than the ingress it forwards into, which
+// would mask legitimate scalar payloads (e.g. if a future authoring API
+// exposes runtime-opened prompts with a scalar `responseSchema`). Safety
+// still lives downstream: the reducer re-validates prompt responses via
+// `validatePromptResponseInput` and actions via collector schemas, so this
+// widening doesn't weaken end-to-end validation.
+export const InteractionMessageSchema = z.object({
+  type: z.literal("interaction"),
+  messageId: z.string(),
+  playerId: z.string(),
+  interactionId: z.string(),
+  params: z.unknown(),
+  // Optional client-minted correlation id (UUID) that lets the whole
+  // click-to-render path be stitched across plugin iframe, web host,
+  // backend spans/logs and SSE. Added for Tier-0 input-latency
+  // observability; the backend rides it through as an HTTP header
+  // (`X-Dreamboard-Client-Action-Id`) but no wire contract changed.
+  clientActionId: z.string().optional(),
+  // Plugin-iframe `Date.now()` captured right before the postMessage
+  // is sent, used as the `t0_click` timestamp on the host-side perf
+  // buffer. Date.now() is intentional: the iframe and the host share
+  // a wall-clock base, but not a `performance.now()` origin.
+  clientSubmittedAtMs: z.number().optional(),
+});
+
+export const ValidateInteractionMessageSchema = z.object({
+  type: z.literal("validate-interaction"),
+  playerId: z.string(),
+  interactionId: z.string(),
+  params: z.unknown(),
+  messageId: z.string(),
+});
+
+export const ValidateInteractionResultMessageSchema = z.object({
+  type: z.literal("validate-interaction-result"),
+  messageId: z.string(),
+  result: z.object({
+    valid: z.boolean(),
+    errorCode: z.string().optional(),
+    message: z.string().optional(),
+  }),
+});
+
+export const PluginErrorMessageSchema = z.object({
+  type: z.literal("error"),
+  message: z.string(),
+  code: z.string().optional(),
+});
+
+export const PongMessageSchema = z.object({
+  type: z.literal("pong"),
+});
+
+export const SwitchPlayerMessageSchema = z.object({
+  type: z.literal("switch-player"),
+  playerId: z.string(),
+});
+
+export const StateAckMessageSchema = z.object({
+  type: z.literal("state-ack"),
+  syncId: z.number(),
+  // Plugin-iframe `Date.now()` captured when the state-sync message
+  // was received. Threaded so the host-side perf HUD can compute the
+  // `t7_state_sync_received` mark without needing perf to be enabled
+  // inside the plugin iframe itself.
+  clientReceivedAtMs: z.number().optional(),
+});
+
+/**
+ * Plugin -> host message sent from a `queueMicrotask` scheduled inside
+ * the state-sync handler so the timestamp reflects roughly when React
+ * would have committed the DOM update for the new state. Dev-only /
+ * perf-only: host records it as `t8_render_commit` on the perf HUD.
+ */
+export const StateRenderedMessageSchema = z.object({
+  type: z.literal("state-rendered"),
+  syncId: z.number(),
+  clientReceivedAtMs: z.number(),
+  clientRenderedAtMs: z.number(),
+});
+
+export const MarkNotificationReadMessageSchema = z.object({
+  type: z.literal("mark-notification-read"),
+  notificationId: z.string(),
+});
+
+export const RestoreHistoryMessageSchema = z.object({
+  type: z.literal("restore-history"),
+  entryId: z.string(),
+});
+
+export const PluginToMainMessageSchema = z.discriminatedUnion("type", [
+  ReadyMessageSchema,
+  InteractionMessageSchema,
+  ValidateInteractionMessageSchema,
+  PluginErrorMessageSchema,
+  PongMessageSchema,
+  SwitchPlayerMessageSchema,
+  StateAckMessageSchema,
+  StateRenderedMessageSchema,
+  MarkNotificationReadMessageSchema,
+  RestoreHistoryMessageSchema,
+]);
+
+export type PluginToMainMessage = z.infer<typeof PluginToMainMessageSchema>;