@dreamboard-games/sdk 0.4.0-alpha.1 → 0.4.0-alpha.2

package/dist/testing.js

@@ -2,14 +2,27 @@ import {
   StaleContractArtifactError,
   isStaleContractArtifactError
 } from "./chunk-3OZMHZK3.js";
+import {
+  PluginRuntimeBoundary,
+  createPluginRuntimeClient
+} from "./chunk-K5ZRJTZZ.js";
+import {
+  DREAMBOARD_PLUGIN_PROTOCOL,
+  DREAMBOARD_PLUGIN_PROTOCOL_VERSION,
+  PluginProtocolFrameSchema,
+  PluginProtocolStepSchema,
+  PluginProtocolTapeSchema,
+  computePluginActionSetVersion,
+  materializePluginGameplayFrame
+} from "./chunk-O6M6PN4E.js";
 import {
   BROWSER_INTERACTION_ACTUATOR_KINDS,
   DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
   browserInteractionEffectSchema
-} from "./chunk-MALRKLRR.js";
+} from "./chunk-WUIVY2KE.js";
 import {
   RuntimeJsonSchema
-} from "./chunk-AEUXCFGM.js";
+} from "./chunk-PF7L4BMG.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/testing/definitions.ts
@@ -37,9 +50,9 @@ function matchPartial(actual, expected, path = "value") {
     if (!(key in actual)) {
       return `${path}.${key} is missing`;
     }
-    const mismatch = matchPartial(actualValue, expectedValue, `${path}.${key}`);
-    if (mismatch) {
-      return mismatch;
+    const mismatch2 = matchPartial(actualValue, expectedValue, `${path}.${key}`);
+    if (mismatch2) {
+      return mismatch2;
     }
   }
   return null;
@@ -59,9 +72,9 @@ function assertDescriptorMatches(descriptor, opts) {
   if (!opts) {
     return;
   }
-  const mismatch = matchPartial(descriptor, opts, "interaction");
-  if (mismatch) {
-    throw new Error(mismatch);
+  const mismatch2 = matchPartial(descriptor, opts, "interaction");
+  if (mismatch2) {
+    throw new Error(mismatch2);
   }
 }
 function createSubmissionErrorMatcher(actual, expected, options) {
@@ -178,9 +191,9 @@ function createExpectApi(options = {}) {
       }
     },
     toMatchObject: (expected) => {
-      const mismatch = matchPartial(actual, expected);
-      if (mismatch) {
-        throw new Error(mismatch);
+      const mismatch2 = matchPartial(actual, expected);
+      if (mismatch2) {
+        throw new Error(mismatch2);
       }
     },
     toBeDefined: () => {
@@ -422,7 +435,7 @@ function resolvePlayerIds(options) {
 function isWireZoneHandles(value) {
   return typeof value === "object" && value !== null;
 }
-function buildPluginSnapshot(options) {
+function buildPluginFrame(options) {
   const projection = options.bundle.projectSeatsDynamic({
     state: options.state,
     playerIds: [options.playerId]
@@ -457,28 +470,25 @@ function buildPluginSnapshot(options) {
       ];
     })
   );
+  const availableInteractions = hydrateRefs(
+    seat?.availableInteractionRefs
+  );
   return {
+    gameVersion: options.version,
+    actionSetVersion: computePluginActionSetVersion({
+      gameVersion: options.version,
+      availableInteractions
+    }),
+    perspectivePlayerId: options.playerId || null,
     view: seat?.view ?? null,
-    gameplay: {
+    flow: {
       currentPhase: flow.currentPhase,
       currentStage: projection.currentStage ?? null,
       activePlayers: flow.activePlayers,
-      simultaneousPhase: projection.simultaneousPhase ?? null,
-      availableInteractions: hydrateRefs(
-        seat?.availableInteractionRefs
-      ),
-      zones
-    },
-    lobby: null,
-    notifications: [],
-    session: {
-      sessionId: options.sessionId,
-      controllablePlayerIds: [...options.playerIds],
-      controllingPlayerId: options.playerId || null,
-      userId: options.userId
+      simultaneousPhase: projection.simultaneousPhase ?? null
     },
-    history: null,
-    syncId: options.version
+    availableInteractions,
+    zones
   };
 }
 function createTestRuntime(options) {
@@ -499,44 +509,37 @@ function createTestRuntime(options) {
     baseState,
     explicitPlayerIds: options.playerIds
   });
-  const userId = options.userId ?? "test-user";
   const sessionId = options.sessionId ?? "test-session";
+  const sessionDescriptor = {
+    sessionId,
+    players: playerIds.map((playerId) => ({
+      playerId,
+      displayName: options.displayNameByPlayerId?.[playerId] ?? playerId
+    }))
+  };
   let version = 0;
   let submissionCounter = 0;
   let currentPlayerId = playerIds[0] ?? "";
   const diagnosticEvents = [];
   let lastDispatch = null;
-  const stateListeners = /* @__PURE__ */ new Set();
-  const sessionListeners = /* @__PURE__ */ new Set();
-  const toReadySessionState = (snapshot) => ({
-    ...snapshot.session,
-    status: "ready"
+  const toReadySessionState = (frame) => ({
+    status: "ready",
+    sessionId,
+    controllingPlayerId: frame.perspectivePlayerId
   });
-  let lastPluginSnapshot;
+  let lastPluginFrame;
   let lastSessionState;
   const applyCurrentState = () => {
-    const previousSession = lastSessionState;
     version += 1;
-    lastPluginSnapshot = buildPluginSnapshot({
+    lastPluginFrame = buildPluginFrame({
       state: currentState,
       bundle: options.bundle,
       playerId: currentPlayerId,
-      playerIds,
-      userId,
-      sessionId,
       version,
       expectedPhase: version === 1 ? options.phase : void 0,
       baseId: options.baseId
     });
-    lastSessionState = toReadySessionState(lastPluginSnapshot);
-    for (const listener of stateListeners) {
-      listener(lastPluginSnapshot);
-    }
-    if (!previousSession || previousSession.controllingPlayerId !== lastSessionState.controllingPlayerId || previousSession.controllablePlayerIds.join("\0") !== lastSessionState.controllablePlayerIds.join("\0")) {
-      for (const listener of sessionListeners) {
-        listener(lastSessionState);
-      }
-    }
+    lastSessionState = toReadySessionState(lastPluginFrame);
   };
   applyCurrentState();
   const validate = async (playerId, interactionId, params = {}) => {
@@ -615,38 +618,16 @@ function createTestRuntime(options) {
       interactionId
     });
   };
-  const setControllingPlayer = (playerId) => {
-    if (!playerIds.includes(playerId)) {
-      throw new Error(`Unknown controlling player '${playerId}'.`);
-    }
-    currentPlayerId = playerId;
-    applyCurrentState();
-  };
   const runtime = {
-    validateInteraction: validate,
-    submitInteraction: submit,
+    validateInteraction: (interactionId, params) => validate(currentPlayerId, interactionId, params),
+    submitInteraction: (interactionId, params) => submit(currentPlayerId, interactionId, params),
     getSessionState: () => lastSessionState,
-    disconnect: () => void 0,
-    switchPlayer: (playerId) => {
-      setControllingPlayer(playerId);
-    },
-    getSnapshot: () => lastPluginSnapshot,
-    subscribeToState: (listener) => {
-      stateListeners.add(listener);
-      return () => {
-        stateListeners.delete(listener);
-      };
-    },
-    _subscribeToSessionState: (listener) => {
-      sessionListeners.add(listener);
-      return () => {
-        sessionListeners.delete(listener);
-      };
-    }
+    disconnect: () => void 0
   };
   return {
     runtime,
-    getSnapshot: () => lastPluginSnapshot,
+    getFrame: () => lastPluginFrame,
+    getSessionDescriptor: () => sessionDescriptor,
     players: () => [...playerIds],
     seat: (index) => {
       if (!Number.isInteger(index) || index < 0 || index >= playerIds.length) {
@@ -670,8 +651,7 @@ function createTestRuntime(options) {
         diagnosticEvents.length = 0;
         lastDispatch = null;
       }
-    },
-    setControllingPlayer
+    }
   };
 }
 
@@ -719,10 +699,22 @@ function digestUIFixtureJson(value) {
 }
 function digestUIFixtureRequest(request) {
   return digestUIFixtureJson({
-    digestVersion: "ui-replay-request@1",
+    digestVersion: "ui-replay-request@2",
+    request
+  });
+}
+function digestUIFixtureTransportRequest(request) {
+  return digestUIFixtureJson({
+    digestVersion: "ui-fixture-runtime-command@2",
     request
   });
 }
+function digestPluginProtocolTape(tape) {
+  return digestUIFixtureJson({
+    digestVersion: "plugin-protocol-tape@2",
+    tape
+  });
+}
 function canonicalizeUIScenarioFixture(fixture) {
   return canonicalizeUIFixtureJson({
     ...fixture,
@@ -744,11 +736,843 @@ function sha256(value) {
   return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }
 
+// src/testing/reducer-scenario/create-reducer-scenario-runner.ts
+function createReducerScenarioRunner(options) {
+  return {
+    async run(operations) {
+      let state = structuredClone(options.initialState);
+      let gameVersion = options.initialGameVersion ?? 1;
+      const frames = [];
+      const exchanges = [];
+      const appendFrame = (id) => {
+        const dynamicProjection = options.bundle.projectSeatsDynamic({
+          state,
+          playerIds: [options.viewer.playerId]
+        });
+        const staticProjection = options.bundle.projectStatic?.() ?? null;
+        const flow = readFlowState2(state);
+        const materialized = materializePluginGameplayFrame({
+          currentPhase: flow.currentPhase,
+          activePlayers: flow.activePlayers,
+          dynamicProjection,
+          staticProjection,
+          perspectivePlayerId: options.viewer.playerId,
+          gameVersion,
+          actionSetVersion: "pending"
+        });
+        const actionSetVersion = computePluginActionSetVersion({
+          gameVersion,
+          availableInteractions: materialized.availableInteractions
+        });
+        const frame = {
+          id,
+          reducerState: structuredClone(state),
+          dynamicProjection,
+          staticProjection,
+          gameVersion,
+          actionSetVersion,
+          projectionDigest: digestUIFixtureJson({
+            digestVersion: "reducer-scenario-frame@2",
+            scenarioId: options.scenarioId,
+            frameId: id,
+            dynamicProjection,
+            staticProjection,
+            gameVersion,
+            actionSetVersion
+          })
+        };
+        frames.push(frame);
+        return frame;
+      };
+      appendFrame("frame-1");
+      for (const operation of operations) {
+        const fromFrame = frames[frames.length - 1];
+        if (!fromFrame) {
+          throw new Error("Reducer scenario runner lost its initial frame.");
+        }
+        if (operation.operation === "validate") {
+          const result2 = await options.bundle.validateInput({
+            state,
+            input: operation.input
+          });
+          exchanges.push({
+            id: operation.id,
+            operation: "validate",
+            fromFrameId: fromFrame.id,
+            input: operation.input,
+            result: result2
+          });
+          continue;
+        }
+        const result = await options.bundle.dispatch({
+          state,
+          input: operation.input
+        });
+        if (result.kind === "reject") {
+          exchanges.push({
+            id: operation.id,
+            operation: "submit",
+            fromFrameId: fromFrame.id,
+            input: operation.input,
+            result: {
+              kind: "rejected",
+              diagnostics: [
+                {
+                  code: result.errorCode,
+                  message: result.message ?? result.errorCode
+                }
+              ]
+            }
+          });
+          continue;
+        }
+        state = structuredClone(result.state);
+        gameVersion += 1;
+        const toFrame = appendFrame(`frame-${frames.length + 1}`);
+        exchanges.push({
+          id: operation.id,
+          operation: "submit",
+          fromFrameId: fromFrame.id,
+          input: operation.input,
+          result: {
+            kind: "accepted",
+            toFrameId: toFrame.id
+          }
+        });
+      }
+      return {
+        scenarioId: options.scenarioId,
+        gameId: options.gameId,
+        viewer: options.viewer,
+        frames,
+        exchanges
+      };
+    }
+  };
+}
+function readFlowState2(state) {
+  return {
+    currentPhase: state.domain?.flow?.currentPhase ?? null,
+    activePlayers: [...state.domain?.flow?.activePlayers ?? []]
+  };
+}
+
+// src/testing/ui-fixture/parity.ts
+var topLevelComparisons = [
+  { path: "scenarioId", code: "fixture-source-mismatch" },
+  { path: "fixtureDigest", code: "candidate-mismatch" },
+  { path: "sdkCandidateDigest", code: "candidate-mismatch" },
+  { path: "pluginRuntimeProtocol", code: "protocol-mismatch" },
+  { path: "browserInteractionProtocol", code: "protocol-mismatch" },
+  { path: "environment.project", code: "host-setup-failure" },
+  { path: "environment.viewport.width", code: "host-setup-failure" },
+  { path: "environment.viewport.height", code: "host-setup-failure" }
+];
+var checkpointComparisons = [
+  { path: "stepId", code: "interaction-resolution-mismatch" },
+  { path: "interactionKey", code: "interaction-resolution-mismatch" },
+  { path: "interactionId", code: "interaction-resolution-mismatch" },
+  { path: "actuatorId", code: "interaction-resolution-mismatch" },
+  { path: "descriptorDigest", code: "interaction-resolution-mismatch" },
+  { path: "gameVersion", code: "projection-mismatch" },
+  { path: "actionSetVersion", code: "projection-mismatch" },
+  { path: "perspectivePlayerId", code: "projection-mismatch" },
+  { path: "projectionDigest", code: "projection-mismatch" },
+  { path: "semanticDigest", code: "semantic-snapshot-mismatch" },
+  { path: "draftDigest", code: "draft-mismatch" },
+  { path: "submissionDigest", code: "submission-mismatch" },
+  { path: "screenshot", code: "visual-mismatch" }
+];
+function createUIParityObservationFromFixture({
+  fixture,
+  sdkCandidateDigest,
+  environment,
+  fixtureDigest = digestUIScenarioFixture(fixture),
+  screenshotsByStepId = {},
+  diagnostics = []
+}) {
+  const frameById = new Map(
+    fixture.protocol.frames.map((frame) => [frame.id, frame])
+  );
+  const firstFrame = fixture.protocol.frames[0];
+  if (!firstFrame) {
+    throw new Error(
+      `Fixture '${fixture.id}' does not contain protocol frames.`
+    );
+  }
+  const checkpoints = fixture.replay.map((step, index) => {
+    const expectedFrameId = step.expect.frameId ?? firstFrame.id;
+    const frame = frameById.get(expectedFrameId);
+    if (!frame) {
+      throw new Error(
+        `Fixture '${fixture.id}' replay step '${step.stepId}' references missing frame '${expectedFrameId}'.`
+      );
+    }
+    const identity = "expectedIdentity" in step ? step.expectedIdentity : null;
+    const projectionDigest = step.expect.projectionDigest ?? frame.projectionDigest;
+    const isFinal = index === fixture.replay.length - 1;
+    const semanticDigest = step.expect.semanticDigest ?? (isFinal ? fixture.expected.finalSemanticDigest : digestUIFixtureJson({
+      scenarioId: fixture.id,
+      stepId: step.stepId,
+      frameId: frame.id,
+      projectionDigest
+    }));
+    const submissionDigest = step.expect.submissionDigest ?? (isFinal ? fixture.expected.submissionDigest : void 0);
+    return {
+      stepId: step.stepId,
+      interactionKey: identity?.interactionKey,
+      interactionId: identity?.interactionId,
+      actuatorId: identity?.actuatorId,
+      descriptorDigest: identity?.descriptorDigest,
+      draftDigest: step.expect.draftDigest ?? identity?.draftDigest,
+      gameVersion: frame.frame.gameVersion,
+      actionSetVersion: frame.frame.actionSetVersion,
+      perspectivePlayerId: frame.frame.perspectivePlayerId,
+      projectionDigest,
+      semanticDigest,
+      submissionDigest,
+      screenshot: screenshotsByStepId[step.stepId]
+    };
+  });
+  return {
+    schemaVersion: 1,
+    scenarioId: fixture.id,
+    fixtureDigest,
+    sdkCandidateDigest,
+    pluginRuntimeProtocol: fixture.pluginRuntimeProtocol,
+    browserInteractionProtocol: fixture.browserInteractionProtocol,
+    environment,
+    checkpoints,
+    diagnostics
+  };
+}
+function parseUIParityObservationV1(value) {
+  const observation = assertRecord(value, "observation");
+  if (observation.schemaVersion !== 1) {
+    throw new Error("UI parity observation schemaVersion must be 1.");
+  }
+  assertString(observation.scenarioId, "scenarioId");
+  assertString(observation.fixtureDigest, "fixtureDigest");
+  assertString(observation.sdkCandidateDigest, "sdkCandidateDigest");
+  if (observation.pluginRuntimeProtocol !== 3) {
+    throw new Error("UI parity observation pluginRuntimeProtocol must be 3.");
+  }
+  assertString(
+    observation.browserInteractionProtocol,
+    "browserInteractionProtocol"
+  );
+  const environment = assertRecord(observation.environment, "environment");
+  assertString(environment.project, "environment.project");
+  const viewport = assertRecord(environment.viewport, "environment.viewport");
+  assertNumber(viewport.width, "environment.viewport.width");
+  assertNumber(viewport.height, "environment.viewport.height");
+  const checkpoints = assertArray(observation.checkpoints, "checkpoints");
+  for (let index = 0; index < checkpoints.length; index += 1) {
+    const checkpoint = assertRecord(
+      checkpoints[index],
+      `checkpoints[${index}]`
+    );
+    assertString(checkpoint.stepId, `checkpoints[${index}].stepId`);
+    assertOptionalString(
+      checkpoint.interactionKey,
+      `checkpoints[${index}].interactionKey`
+    );
+    assertOptionalString(
+      checkpoint.interactionId,
+      `checkpoints[${index}].interactionId`
+    );
+    assertOptionalString(
+      checkpoint.actuatorId,
+      `checkpoints[${index}].actuatorId`
+    );
+    assertOptionalString(
+      checkpoint.descriptorDigest,
+      `checkpoints[${index}].descriptorDigest`
+    );
+    assertOptionalString(
+      checkpoint.draftDigest,
+      `checkpoints[${index}].draftDigest`
+    );
+    assertNumber(checkpoint.gameVersion, `checkpoints[${index}].gameVersion`);
+    assertString(
+      checkpoint.actionSetVersion,
+      `checkpoints[${index}].actionSetVersion`
+    );
+    if (checkpoint.perspectivePlayerId !== null && typeof checkpoint.perspectivePlayerId !== "string") {
+      throw new Error(
+        `checkpoints[${index}].perspectivePlayerId must be a string or null.`
+      );
+    }
+    assertString(
+      checkpoint.projectionDigest,
+      `checkpoints[${index}].projectionDigest`
+    );
+    assertString(
+      checkpoint.semanticDigest,
+      `checkpoints[${index}].semanticDigest`
+    );
+    assertOptionalString(
+      checkpoint.submissionDigest,
+      `checkpoints[${index}].submissionDigest`
+    );
+    assertOptionalString(
+      checkpoint.screenshot,
+      `checkpoints[${index}].screenshot`
+    );
+  }
+  const diagnostics = assertArray(observation.diagnostics, "diagnostics");
+  for (let index = 0; index < diagnostics.length; index += 1) {
+    const diagnostic = assertRecord(
+      diagnostics[index],
+      `diagnostics[${index}]`
+    );
+    assertString(diagnostic.code, `diagnostics[${index}].code`);
+    assertString(diagnostic.message, `diagnostics[${index}].message`);
+  }
+  return observation;
+}
+function compareUIParityObservations(expected, actual) {
+  for (const comparison of topLevelComparisons) {
+    const result = comparePath(expected, actual, comparison);
+    if (result) {
+      return result;
+    }
+  }
+  if (expected.checkpoints.length !== actual.checkpoints.length) {
+    return mismatch({
+      code: "interaction-resolution-mismatch",
+      path: "checkpoints.length",
+      expected: expected.checkpoints.length,
+      actual: actual.checkpoints.length
+    });
+  }
+  for (let index = 0; index < expected.checkpoints.length; index += 1) {
+    const expectedCheckpoint = expected.checkpoints[index];
+    const actualCheckpoint = actual.checkpoints[index];
+    for (const comparison of checkpointComparisons) {
+      const result = comparePath(
+        expectedCheckpoint,
+        actualCheckpoint,
+        comparison,
+        {
+          prefix: `checkpoints[${index}]`,
+          checkpointIndex: index,
+          stepId: expectedCheckpoint.stepId
+        }
+      );
+      if (result) {
+        return result;
+      }
+    }
+  }
+  if (!sameValue(expected.diagnostics, actual.diagnostics)) {
+    return mismatch({
+      code: "host-setup-failure",
+      path: "diagnostics",
+      expected: expected.diagnostics,
+      actual: actual.diagnostics
+    });
+  }
+  return { ok: true };
+}
+function comparePath(expected, actual, comparison, options = {}) {
+  const expectedValue = getPath(expected, comparison.path);
+  const actualValue = getPath(actual, comparison.path);
+  if (sameValue(expectedValue, actualValue)) {
+    return null;
+  }
+  const path = options.prefix ? `${options.prefix}.${comparison.path}` : comparison.path;
+  return mismatch({
+    code: comparison.code,
+    path,
+    expected: expectedValue,
+    actual: actualValue,
+    checkpointIndex: options.checkpointIndex,
+    stepId: options.stepId
+  });
+}
+function mismatch(input) {
+  return {
+    ok: false,
+    failure: {
+      ...input,
+      message: `${input.code} at ${input.path}`
+    }
+  };
+}
+function sameValue(left, right) {
+  if (left === void 0 || right === void 0) {
+    return left === right;
+  }
+  return canonicalUIFixtureJson(left) === canonicalUIFixtureJson(right);
+}
+function getPath(value, path) {
+  return path.split(".").reduce((current, key) => {
+    if (current === null || typeof current !== "object") {
+      return void 0;
+    }
+    return current[key];
+  }, value);
+}
+function assertRecord(value, path) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${path} must be an object.`);
+  }
+  return value;
+}
+function assertArray(value, path) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${path} must be an array.`);
+  }
+  return value;
+}
+function assertString(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${path} must be a non-empty string.`);
+  }
+}
+function assertOptionalString(value, path) {
+  if (value !== void 0 && (typeof value !== "string" || value.length === 0)) {
+    throw new Error(`${path} must be a non-empty string when present.`);
+  }
+}
+function assertNumber(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${path} must be a finite number.`);
+  }
+}
+
+// src/testing/ui-fixture/create-fixture-host-harness.ts
+var DEFAULT_CHANNEL_ID = "fixture-channel";
+function createFixtureHostHarness(options) {
+  const strict = options.strict ?? true;
+  const latencyMs = options.latencyMs ?? 0;
+  const channelId = options.channelId ?? DEFAULT_CHANNEL_ID;
+  const events = [];
+  const frameById = new Map(
+    options.tape.frames.map((frame) => [frame.id, frame])
+  );
+  let eventSequence = 0;
+  let envelopeSequence = 0;
+  let stepCursor = 0;
+  let currentFrameId = null;
+  let onMessage = null;
+  let firstFixtureError = null;
+  const pendingHandlers = /* @__PURE__ */ new Set();
+  const record = (event) => {
+    const entry = {
+      sequence: ++eventSequence,
+      atMs: options.nowMs?.() ?? eventSequence,
+      ...event
+    };
+    events.push(entry);
+    options.onEvent?.(entry);
+  };
+  const createFixtureError = (code, message) => {
+    record({ kind: "diagnostic" });
+    const error = new Error(message);
+    error.name = "FixtureHostHarnessError";
+    Object.assign(error, { errorCode: code });
+    return error;
+  };
+  const rememberFixtureError = (error) => {
+    if (firstFixtureError) {
+      return;
+    }
+    firstFixtureError = error instanceof Error ? error : createFixtureError(
+      "fixture-unknown-error",
+      "Fixture host failed with an unknown error."
+    );
+  };
+  const throwFixtureError = () => {
+    if (firstFixtureError) {
+      throw firstFixtureError;
+    }
+  };
+  const sendHostPayload = (payload) => {
+    if (!onMessage) {
+      return;
+    }
+    onMessage({
+      protocol: DREAMBOARD_PLUGIN_PROTOCOL,
+      version: DREAMBOARD_PLUGIN_PROTOCOL_VERSION,
+      channelId,
+      sequence: ++envelopeSequence,
+      payload
+    });
+  };
+  const sendInit = () => {
+    sendHostPayload({
+      type: "runtime.init",
+      session: options.tape.session
+    });
+  };
+  const publishFrame = (frameId) => {
+    const frame = frameById.get(frameId);
+    if (!frame) {
+      throw createFixtureError(
+        "fixture-missing-frame",
+        `Plugin protocol tape references missing frame '${frameId}'.`
+      );
+    }
+    currentFrameId = frame.id;
+    record({
+      kind: "frame-sent",
+      frameId: frame.id,
+      projectionDigest: frame.projectionDigest
+    });
+    sendHostPayload({
+      type: "gameplay.frame",
+      frame: frame.frame
+    });
+  };
+  const drainHostFrames = () => {
+    while (options.tape.steps[stepCursor]?.kind === "host.frame") {
+      const step = options.tape.steps[stepCursor];
+      stepCursor += 1;
+      publishFrame(step.frameId);
+    }
+  };
+  const drainOneHostFrame = () => {
+    if (options.tape.steps[stepCursor]?.kind !== "host.frame") {
+      return;
+    }
+    const step = options.tape.steps[stepCursor];
+    stepCursor += 1;
+    publishFrame(step.frameId);
+  };
+  const waitForConfiguredLatency = async () => {
+    if (latencyMs <= 0) {
+      await Promise.resolve();
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, latencyMs));
+  };
+  const consumeExpectedStep = (kind, requestDigest) => {
+    const step = options.tape.steps[stepCursor];
+    if (!step) {
+      throw createFixtureError(
+        "fixture-protocol-exhausted",
+        `Plugin protocol tape has no remaining step for ${kind}.`
+      );
+    }
+    if (step.kind !== kind) {
+      throw createFixtureError(
+        "fixture-protocol-step-mismatch",
+        `Expected protocol step '${step.kind}' but received '${kind}'.`
+      );
+    }
+    if (step.fromFrameId !== currentFrameId) {
+      throw createFixtureError(
+        "fixture-protocol-frame-mismatch",
+        `Expected protocol from frame '${step.fromFrameId}' but current frame is '${currentFrameId ?? "<none>"}'.`
+      );
+    }
+    if (step.requestDigest !== requestDigest) {
+      const mode = strict ? "strict" : "compatible";
+      throw createFixtureError(
+        "fixture-protocol-digest-mismatch",
+        `${mode} fixture protocol digest mismatch for ${kind}: expected ${step.requestDigest}, received ${requestDigest}.`
+      );
+    }
+    stepCursor += 1;
+    return step;
+  };
+  const handleValidate = async (command) => {
+    const requestDigest = digestUIFixtureTransportRequest({
+      operation: "validate",
+      basis: command.basis,
+      interactionId: command.interactionId,
+      payload: command.params
+    });
+    const step = consumeExpectedStep("client.validate", requestDigest);
+    record({
+      kind: "validate-received",
+      requestDigest,
+      result: step.response.valid ? "accepted" : "rejected"
+    });
+    await waitForConfiguredLatency();
+    sendHostPayload({
+      type: "interaction.validation-result",
+      requestId: command.requestId,
+      result: step.response
+    });
+  };
+  const handleSubmit = async (command) => {
+    const requestDigest = digestUIFixtureTransportRequest({
+      operation: "submit",
+      basis: command.basis,
+      interactionId: command.interactionId,
+      payload: command.params
+    });
+    const step = consumeExpectedStep("client.submit", requestDigest);
+    record({
+      kind: "submit-received",
+      requestDigest,
+      result: step.response.accepted ? "accepted" : "rejected"
+    });
+    await waitForConfiguredLatency();
+    sendHostPayload({
+      type: "interaction.submit-result",
+      requestId: command.requestId,
+      result: step.response
+    });
+    if (step.response.accepted) {
+      await waitForConfiguredLatency();
+      drainHostFrames();
+    }
+  };
+  const handleClientPayload = (payload) => {
+    const trackHandler = (promise) => {
+      pendingHandlers.add(promise);
+      promise.catch((error) => {
+        rememberFixtureError(error);
+      }).finally(() => {
+        pendingHandlers.delete(promise);
+      });
+    };
+    switch (payload.type) {
+      case "runtime.ready":
+        record({ kind: "ready-received" });
+        break;
+      case "runtime.ack":
+        record({ kind: "ack-received" });
+        break;
+      case "interaction.validate":
+        trackHandler(handleValidate(payload));
+        break;
+      case "interaction.submit":
+        trackHandler(handleSubmit(payload));
+        break;
+      case "runtime.error":
+        record({ kind: "diagnostic" });
+        break;
+      default: {
+        const _exhaustive = payload;
+        return _exhaustive;
+      }
+    }
+  };
+  const transport = {
+    start(nextOnMessage) {
+      onMessage = nextOnMessage;
+      queueMicrotask(() => {
+        sendInit();
+        drainOneHostFrame();
+      });
+      return () => {
+        onMessage = null;
+      };
+    },
+    send(message) {
+      handleClientPayload(message);
+    }
+  };
+  return {
+    transport,
+    tape: options.tape,
+    reset() {
+      eventSequence = 0;
+      envelopeSequence = 0;
+      stepCursor = 0;
+      currentFrameId = null;
+      firstFixtureError = null;
+      pendingHandlers.clear();
+      events.length = 0;
+      if (onMessage) {
+        sendInit();
+        drainOneHostFrame();
+      }
+    },
+    async flush() {
+      await waitForConfiguredLatency();
+      await Promise.resolve();
+      while (pendingHandlers.size > 0) {
+        await Promise.allSettled([...pendingHandlers]);
+      }
+      throwFixtureError();
+    },
+    async advanceHost() {
+      await waitForConfiguredLatency();
+      drainHostFrames();
+      throwFixtureError();
+    },
+    getCurrentFrameId() {
+      if (!currentFrameId) {
+        throw createFixtureError(
+          "fixture-frame-not-started",
+          "Fixture host has not emitted a gameplay frame."
+        );
+      }
+      return currentFrameId;
+    },
+    getEvents() {
+      return events.map((event) => ({ ...event }));
+    },
+    assertConsumed() {
+      throwFixtureError();
+      if (stepCursor !== options.tape.steps.length) {
+        throw createFixtureError(
+          "fixture-unconsumed-protocol-steps",
+          `Plugin protocol tape consumed ${stepCursor} of ${options.tape.steps.length} protocol step(s).`
+        );
+      }
+    }
+  };
+}
+
+// src/testing/ui-fixture/FixturePluginRuntime.tsx
+import { useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+function FixturePluginRuntime({
+  harness,
+  runtime,
+  children
+}) {
+  const fixtureRuntime = useMemo(
+    () => runtime ?? createPluginRuntimeClient({ transport: harness.transport }),
+    [harness.transport, runtime]
+  );
+  return /* @__PURE__ */ jsx(PluginRuntimeBoundary, { runtime: fixtureRuntime, children });
+}
+
+// src/testing/ui-fixture/compile-plugin-protocol-tape.ts
+function compilePluginProtocolTape(options) {
+  const frames = options.trace.frames.map(
+    (frame) => materializeTraceFrame(frame, options.trace.viewer.playerId)
+  );
+  const frameById = new Map(frames.map((frame) => [frame.id, frame]));
+  const steps = [];
+  const firstFrame = frames[0];
+  if (!firstFrame) {
+    throw new Error(
+      `Reducer scenario '${options.trace.scenarioId}' did not record frames.`
+    );
+  }
+  steps.push({
+    id: `${firstFrame.id}.host-frame`,
+    kind: "host.frame",
+    frameId: firstFrame.id
+  });
+  for (const exchange of options.trace.exchanges) {
+    const fromFrame = frameById.get(exchange.fromFrameId);
+    if (!fromFrame) {
+      throw new Error(
+        `Reducer exchange '${exchange.id}' references missing frame '${exchange.fromFrameId}'.`
+      );
+    }
+    if (exchange.operation === "validate") {
+      steps.push({
+        id: exchange.id,
+        kind: "client.validate",
+        fromFrameId: exchange.fromFrameId,
+        requestDigest: digestRuntimeCommand(exchange, fromFrame),
+        response: {
+          valid: exchange.result.valid,
+          errorCode: exchange.result.errorCode,
+          message: exchange.result.message
+        }
+      });
+      continue;
+    }
+    steps.push({
+      id: exchange.id,
+      kind: "client.submit",
+      fromFrameId: exchange.fromFrameId,
+      requestDigest: digestRuntimeCommand(exchange, fromFrame),
+      response: exchange.result.kind === "accepted" ? { accepted: true } : {
+        accepted: false,
+        errorCode: exchange.result.diagnostics[0]?.code ?? "fixture-rejected",
+        message: exchange.result.diagnostics[0]?.message
+      }
+    });
+    if (exchange.result.kind === "accepted") {
+      if (!frameById.has(exchange.result.toFrameId)) {
+        throw new Error(
+          `Reducer exchange '${exchange.id}' references missing toFrameId '${exchange.result.toFrameId}'.`
+        );
+      }
+      steps.push({
+        id: `${exchange.id}.host-frame`,
+        kind: "host.frame",
+        frameId: exchange.result.toFrameId
+      });
+    }
+  }
+  return {
+    session: options.session,
+    frames,
+    steps
+  };
+}
+function materializeTraceFrame(frame, perspectivePlayerId) {
+  const flow = readFlowState3(frame.reducerState);
+  return {
+    id: frame.id,
+    frame: materializePluginGameplayFrame({
+      currentPhase: flow.currentPhase,
+      activePlayers: flow.activePlayers,
+      dynamicProjection: frame.dynamicProjection,
+      staticProjection: frame.staticProjection,
+      perspectivePlayerId,
+      gameVersion: frame.gameVersion,
+      actionSetVersion: frame.actionSetVersion
+    }),
+    projectionDigest: frame.projectionDigest
+  };
+}
+function digestRuntimeCommand(exchange, frame) {
+  return digestUIFixtureTransportRequest({
+    operation: exchange.operation === "validate" ? "validate" : "submit",
+    basis: {
+      gameVersion: frame.frame.gameVersion,
+      actionSetVersion: frame.frame.actionSetVersion,
+      perspectivePlayerId: frame.frame.perspectivePlayerId
+    },
+    interactionId: exchange.input.interactionId,
+    payload: exchange.input.params
+  });
+}
+function readFlowState3(state) {
+  return {
+    currentPhase: state.domain?.flow?.currentPhase ?? null,
+    activePlayers: [...state.domain?.flow?.activePlayers ?? []]
+  };
+}
+
+// src/testing/ui-fixture/deterministic-environment.ts
+var defaultFixtureEnvironmentInit = {
+  clockIso: "2026-01-01T00:00:00.000Z",
+  randomSeed: "dreamboard-ui-fixture",
+  locale: "en-US",
+  timezone: "UTC",
+  reducedMotion: true,
+  network: "blocked"
+};
+function createDeterministicIdFactory(seed) {
+  let cursor = 0;
+  return () => {
+    cursor += 1;
+    return `fixture-${slug(seed)}-${cursor.toString(36).padStart(4, "0")}`;
+  };
+}
+function fixtureEnvironmentInitFor(options) {
+  return {
+    ...defaultFixtureEnvironmentInit,
+    clockIso: options.clockIso,
+    randomSeed: options.randomSeed
+  };
+}
+function slug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "seed";
+}
+
 // src/testing/ui-fixture/schema.ts
 import { z } from "zod";
-var UI_SCENARIO_FIXTURE_SCHEMA_VERSION = 1;
-var UI_SCENARIO_FIXTURE_BUNDLE_SCHEMA_VERSION = 1;
-var UI_SCENARIO_FIXTURE_SUPPORTED_BROWSER_PROTOCOL_MAJOR = 2;
+var UI_SCENARIO_FIXTURE_SCHEMA_VERSION = 2;
+var UI_SCENARIO_FIXTURE_BUNDLE_SCHEMA_VERSION = 2;
+var UI_SCENARIO_FIXTURE_SUPPORTED_BROWSER_PROTOCOL_MAJOR = 3;
+var UI_SCENARIO_FIXTURE_PLUGIN_RUNTIME_PROTOCOL = DREAMBOARD_PLUGIN_PROTOCOL_VERSION;
 var digestSchema = z.string().refine(isSha256Digest, {
   message: "Expected a sha256:<64 lowercase hex> digest."
 });
@@ -761,55 +1585,12 @@ var environmentSchema = z.object({
   timezone: z.literal("UTC"),
   viewportTags: z.array(z.enum(["desktop", "tablet", "phone", "touch"]))
 }).strict();
-var pluginSessionSchema = z.object({
-  sessionId: nonEmptyStringSchema,
-  controllablePlayerIds: z.array(nonEmptyStringSchema),
-  controllingPlayerId: nonEmptyStringSchema.nullable(),
-  userId: nonEmptyStringSchema.nullable()
-}).catchall(jsonSchema);
-var gameplaySnapshotSchema = z.object({
-  currentPhase: nonEmptyStringSchema.nullable(),
-  currentStage: nonEmptyStringSchema.nullable(),
-  activePlayers: z.array(nonEmptyStringSchema),
-  simultaneousPhase: jsonSchema.nullable().optional(),
-  availableInteractions: z.array(jsonSchema),
-  zones: z.record(z.string(), jsonSchema)
-}).catchall(jsonSchema);
-var uiFixturePluginStateSnapshotSchema = z.object({
-  view: jsonSchema.nullable(),
-  gameplay: gameplaySnapshotSchema,
-  lobby: jsonSchema.nullable(),
-  notifications: z.array(jsonSchema),
-  session: pluginSessionSchema,
-  history: jsonSchema.nullable(),
-  syncId: z.number().int().nonnegative()
-}).strict();
-var uiFixtureFrameSchema = z.object({
-  id: nonEmptyStringSchema,
-  snapshot: uiFixturePluginStateSnapshotSchema,
-  projectionDigest: digestSchema
-}).strict();
-var uiFixtureTransportExchangeSchema = z.object({
-  id: nonEmptyStringSchema,
-  fromFrameId: nonEmptyStringSchema,
-  operation: z.enum(["validate", "submit", "refresh"]),
-  requestDigest: digestSchema,
-  response: z.union([
-    z.object({
-      kind: z.literal("accepted"),
-      nextFrameId: nonEmptyStringSchema
-    }).strict(),
-    z.object({
-      kind: z.literal("rejected"),
-      diagnostics: z.array(
-        z.object({
-          code: nonEmptyStringSchema,
-          message: nonEmptyStringSchema
-        }).strict()
-      )
-    }).strict()
-  ])
-}).strict();
+var uiFixtureFrameSchema = PluginProtocolFrameSchema;
+var uiFixtureProtocolStepSchema = PluginProtocolStepSchema;
+var pluginProtocolTapeSchema = PluginProtocolTapeSchema.refine(
+  (tape) => tape.frames.length > 0,
+  "UI fixture protocol tapes require at least one gameplay frame."
+);
 var browserInteractionIntentRequestSchema = z.object({
   surface: nonEmptyStringSchema,
   scopeId: nonEmptyStringSchema.optional(),
@@ -887,6 +1668,7 @@ var uiScenarioFixtureSchema = z.object({
   browserInteractionProtocol: z.literal(
     DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION
   ),
+  pluginRuntimeProtocol: z.literal(DREAMBOARD_PLUGIN_PROTOCOL_VERSION),
   id: nonEmptyStringSchema,
   title: nonEmptyStringSchema,
   gameId: nonEmptyStringSchema,
@@ -904,8 +1686,7 @@ var uiScenarioFixtureSchema = z.object({
     playerId: nonEmptyStringSchema.optional()
   }).strict(),
   environment: environmentSchema,
-  frames: z.array(uiFixtureFrameSchema).min(1),
-  transport: z.array(uiFixtureTransportExchangeSchema),
+  protocol: pluginProtocolTapeSchema,
   replay: z.array(uiScenarioReplayStepSchema),
   expected: z.object({
     initialProjectionDigest: digestSchema,
@@ -918,6 +1699,7 @@ var uiScenarioFixtureBundleIndexSchema = z.object({
   schemaVersion: z.literal(UI_SCENARIO_FIXTURE_BUNDLE_SCHEMA_VERSION),
   bundleId: nonEmptyStringSchema,
   sdkCommit: nonEmptyStringSchema,
+  pluginRuntimeProtocol: z.literal(DREAMBOARD_PLUGIN_PROTOCOL_VERSION),
   browserInteractionProtocol: z.literal(
     DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION
   ),
@@ -963,21 +1745,29 @@ function assertSupportedBrowserInteractionProtocol(version) {
 function validateUIScenarioFixtureReferences(fixture) {
   assertSupportedBrowserInteractionProtocol(fixture.browserInteractionProtocol);
   const frameIds = /* @__PURE__ */ new Set();
-  for (const frame of fixture.frames) {
+  const stepIds = /* @__PURE__ */ new Set();
+  for (const frame of fixture.protocol.frames) {
     if (frameIds.has(frame.id)) {
       throw new Error(`Duplicate fixture frame id '${frame.id}'.`);
     }
     frameIds.add(frame.id);
   }
-  for (const exchange of fixture.transport) {
-    if (!frameIds.has(exchange.fromFrameId)) {
-      throw new Error(
-        `Transport exchange '${exchange.id}' references missing fromFrameId '${exchange.fromFrameId}'.`
-      );
+  for (const step of fixture.protocol.steps) {
+    if (stepIds.has(step.id)) {
+      throw new Error(`Duplicate protocol step id '${step.id}'.`);
+    }
+    stepIds.add(step.id);
+    if (step.kind === "host.frame") {
+      if (!frameIds.has(step.frameId)) {
+        throw new Error(
+          `Protocol step '${step.id}' references missing frameId '${step.frameId}'.`
+        );
+      }
+      continue;
     }
-    if (exchange.response.kind === "accepted" && !frameIds.has(exchange.response.nextFrameId)) {
+    if (!frameIds.has(step.fromFrameId)) {
       throw new Error(
-        `Transport exchange '${exchange.id}' references missing nextFrameId '${exchange.response.nextFrameId}'.`
+        `Protocol step '${step.id}' references missing fromFrameId '${step.fromFrameId}'.`
       );
     }
   }
@@ -1003,10 +1793,12 @@ function validateUIScenarioFixtureReferences(fixture) {
 
 // src/testing/ui-fixture/compiler.ts
 function compileUIScenarioFixture(options) {
-  const firstFrame = options.frames[0];
-  const finalFrame = options.frames[options.frames.length - 1];
+  const firstFrame = options.protocol.frames[0];
+  const finalFrame = lastPublishedFrame(options.protocol);
   if (!firstFrame || !finalFrame) {
-    throw new Error("compileUIScenarioFixture requires at least one frame.");
+    throw new Error(
+      "compileUIScenarioFixture requires at least one protocol frame."
+    );
   }
   const replay = options.replay ?? [];
   const submissionDigest = options.expected?.submissionDigest ?? digestUIFixtureJson({
@@ -1024,8 +1816,9 @@ function compileUIScenarioFixture(options) {
   });
   return parseUIScenarioFixture(
     canonicalizeUIScenarioFixture({
-      schemaVersion: 1,
+      schemaVersion: 2,
       browserInteractionProtocol: DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+      pluginRuntimeProtocol: DREAMBOARD_PLUGIN_PROTOCOL_VERSION,
       id: options.id,
       title: options.title,
       gameId: options.gameId,
@@ -1033,8 +1826,7 @@ function compileUIScenarioFixture(options) {
       source: options.source,
       viewer: options.viewer,
       environment: options.environment,
-      frames: options.frames,
-      transport: [...options.transport ?? []],
+      protocol: options.protocol,
       replay,
       expected: {
         initialProjectionDigest: options.expected?.initialProjectionDigest ?? firstFrame.projectionDigest,
@@ -1045,6 +1837,16 @@ function compileUIScenarioFixture(options) {
     })
   );
 }
+function lastPublishedFrame(protocol) {
+  const frameById = new Map(protocol.frames.map((frame) => [frame.id, frame]));
+  for (let index = protocol.steps.length - 1; index >= 0; index -= 1) {
+    const step = protocol.steps[index];
+    if (step?.kind === "host.frame") {
+      return frameById.get(step.frameId);
+    }
+  }
+  return protocol.frames[protocol.frames.length - 1];
+}
 function assertDeterministicUIScenarioFixture(first, second) {
   const firstBytes = serializeUIScenarioFixture(first);
   const secondBytes = serializeUIScenarioFixture(second);
@@ -1118,8 +1920,10 @@ function assertUIStepExpectationSatisfied(stepId, expected, actual) {
   }
 }
 export {
+  FixturePluginRuntime,
   StaleContractArtifactError,
   UI_SCENARIO_FIXTURE_BUNDLE_SCHEMA_VERSION,
+  UI_SCENARIO_FIXTURE_PLUGIN_RUNTIME_PROTOCOL,
   UI_SCENARIO_FIXTURE_SCHEMA_VERSION,
   UI_SCENARIO_FIXTURE_SUPPORTED_BROWSER_PROTOCOL_MAJOR,
   assertDeterministicUIScenarioFixture,
@@ -1129,23 +1933,34 @@ export {
   canonicalUIFixtureJson,
   canonicalizeUIFixtureJson,
   canonicalizeUIScenarioFixture,
+  compareUIParityObservations,
+  compilePluginProtocolTape,
   compileUIScenarioFixture,
+  createDeterministicIdFactory,
   createExpectApi,
+  createFixtureHostHarness,
+  createReducerScenarioRunner,
   createTestRuntime,
+  createUIParityObservationFromFixture,
+  defaultFixtureEnvironmentInit,
   defineBase,
   defineScenario,
+  digestPluginProtocolTape,
   digestUIFixtureJson,
   digestUIFixtureRequest,
+  digestUIFixtureTransportRequest,
   digestUIScenarioFixture,
+  fixtureEnvironmentInitFor,
   isSha256Digest,
   isStaleContractArtifactError,
+  parseUIParityObservationV1,
   parseUIScenarioFixture,
   parseUIScenarioFixtureBundleIndex,
+  pluginProtocolTapeSchema,
   portableSemanticReplayStepSchema,
   serializeUIScenarioFixture,
   uiFixtureFrameSchema,
-  uiFixturePluginStateSnapshotSchema,
-  uiFixtureTransportExchangeSchema,
+  uiFixtureProtocolStepSchema,
   uiReplayExecutionSchema,
   uiReplayRequestSchema,
   uiResolvedReplayIdentitySchema,