@dreamboard-games/sdk 0.2.0

package/src/testing/create-test-runtime.ts

@@ -0,0 +1,381 @@
+import type { ReducerBundleContract } from "../infrastructure/reducer-contract/bundle.js";
+import type * as Wire from "../generated/reducer-contract/wire.js";
+import type {
+  InteractionDescriptor,
+  PluginStateSnapshot,
+  ZoneHandlesSnapshot,
+} from "../runtime-internal/reducer.js";
+import type {
+  RuntimeAPI,
+  SubmissionError,
+  ValidationResult,
+} from "../runtime-internal/types/runtime-api.js";
+import type { PluginSessionState as RuntimePluginSessionState } from "../runtime-internal/types/runtime-api.js";
+
+type ReducerBundleLike = Pick<
+  ReducerBundleContract,
+  "projectSeatsDynamic" | "validateInput" | "dispatch"
+>;
+
+type DeepReadonly<T> = T extends (...args: readonly unknown[]) => unknown
+  ? T
+  : T extends readonly (infer Item)[]
+    ? readonly DeepReadonly<Item>[]
+    : T extends object
+      ? { readonly [Key in keyof T]: DeepReadonly<T[Key]> }
+      : T;
+
+type DeepMutable<T> = T extends (...args: readonly unknown[]) => unknown
+  ? T
+  : T extends readonly (infer Item)[]
+    ? DeepMutable<Item>[]
+    : T extends object
+      ? { -readonly [Key in keyof T]: DeepMutable<T[Key]> }
+      : T;
+
+type BaseStateArtifact = {
+  snapshot: DeepReadonly<Wire.ReducerSessionState>;
+  fingerprint: {
+    players: number;
+  };
+};
+
+type WireZoneHandles = {
+  cardIds?: readonly string[];
+  cardViewsById?: Readonly<Record<string, string>>;
+  playableByCardId?: Readonly<Record<string, readonly string[]>>;
+};
+
+export type CreateTestRuntimeOptions = {
+  baseId: string;
+  baseStates: Record<string, BaseStateArtifact>;
+  bundle: ReducerBundleLike;
+  phase?: string;
+  playerIds?: readonly string[];
+  sessionId?: string;
+  userId?: string | null;
+  gameId?: string;
+  displayNameByPlayerId?: Record<string, string>;
+};
+
+export type CreatedTestRuntime = {
+  runtime: RuntimeAPI & {
+    getSnapshot(): PluginStateSnapshot;
+    subscribeToState(
+      listener: (state: PluginStateSnapshot) => void,
+    ): () => void;
+    _subscribeToSessionState(
+      listener: (state: RuntimePluginSessionState) => void,
+    ): () => void;
+  };
+  getSnapshot(): PluginStateSnapshot;
+  players(): readonly string[];
+  seat(index: number): string;
+  submit(
+    playerId: string,
+    interactionId: string,
+    params?: unknown,
+  ): Promise<void>;
+  validate(
+    playerId: string,
+    interactionId: string,
+    params?: unknown,
+  ): Promise<ValidationResult>;
+  setControllingPlayer(playerId: string): void;
+};
+
+function cloneState<T>(value: T): DeepMutable<T> {
+  return structuredClone(value) as DeepMutable<T>;
+}
+
+function createSubmissionError(
+  errorCode: string | undefined,
+  message: string | undefined,
+): SubmissionError {
+  const error = new Error(message ?? "Interaction rejected") as SubmissionError;
+  error.name = "SubmissionError";
+  error.errorCode = errorCode;
+  return error;
+}
+
+function readFlowState(state: Wire.ReducerSessionState): {
+  currentPhase: string | null;
+  activePlayers: string[];
+} {
+  const flow = ((
+    state.domain as
+      | { flow?: { currentPhase?: string; activePlayers?: string[] } }
+      | undefined
+  )?.flow ?? {}) as {
+    currentPhase?: string;
+    activePlayers?: string[];
+  };
+  return {
+    currentPhase: flow.currentPhase ?? null,
+    activePlayers: Array.isArray(flow.activePlayers) ? flow.activePlayers : [],
+  };
+}
+
+function resolvePlayerIds(options: {
+  baseState: BaseStateArtifact;
+  explicitPlayerIds?: readonly string[];
+}): string[] {
+  if (options.explicitPlayerIds && options.explicitPlayerIds.length > 0) {
+    return [...options.explicitPlayerIds];
+  }
+  return Array.from(
+    { length: options.baseState.fingerprint.players },
+    (_, index) => `player-${index + 1}`,
+  );
+}
+
+function isWireZoneHandles(value: unknown): value is WireZoneHandles {
+  return typeof value === "object" && value !== null;
+}
+
+function buildPluginSnapshot(options: {
+  state: Wire.ReducerSessionState;
+  bundle: ReducerBundleLike;
+  playerId: string;
+  playerIds: readonly string[];
+  userId: string | null;
+  sessionId: string;
+  version: number;
+  expectedPhase: string | undefined;
+  baseId: string;
+}): PluginStateSnapshot {
+  const projection = options.bundle.projectSeatsDynamic({
+    state: options.state,
+    playerIds: [options.playerId],
+  });
+
+  const flow = readFlowState(options.state);
+  if (options.expectedPhase && flow.currentPhase !== options.expectedPhase) {
+    throw new Error(
+      `Expected base '${options.baseId}' to be in phase '${options.expectedPhase}', received '${
+        flow.currentPhase ?? "null"
+      }'.`,
+    );
+  }
+
+  const interactionsByRef =
+    (projection.interactionsByRef as
+      | Record<string, InteractionDescriptor>
+      | undefined) ?? {};
+  const hydrateRefs = (
+    refs: readonly string[] | undefined,
+  ): InteractionDescriptor[] =>
+    (refs ?? [])
+      .map((ref) => interactionsByRef[ref])
+      .filter((descriptor): descriptor is InteractionDescriptor =>
+        Boolean(descriptor),
+      );
+
+  const seat = projection.seats?.[options.playerId];
+  const zones = Object.fromEntries(
+    Object.entries(
+      ((seat?.zones as Record<string, unknown> | undefined) ?? {}),
+    ).map(([zoneId, zoneValue]) => {
+      const zone = isWireZoneHandles(zoneValue) ? zoneValue : {};
+      return [
+        zoneId,
+        {
+          cardIds: [...(zone.cardIds ?? [])],
+          cardViewsById: { ...(zone.cardViewsById ?? {}) },
+          playableByCardId: Object.fromEntries(
+            Object.entries(zone.playableByCardId ?? {}).map(
+              ([cardId, refs]) => [cardId, hydrateRefs(refs)],
+            ),
+          ),
+        } satisfies ZoneHandlesSnapshot,
+      ];
+    }),
+  );
+
+  return {
+    view: (seat?.view ?? null) as PluginStateSnapshot["view"],
+    gameplay: {
+      currentPhase: flow.currentPhase,
+      currentStage: projection.currentStage ?? null,
+      activePlayers: flow.activePlayers,
+      simultaneousPhase: projection.simultaneousPhase ?? null,
+      availableInteractions: hydrateRefs(
+        seat?.availableInteractionRefs as readonly string[] | undefined,
+      ),
+      zones,
+    },
+    lobby: null,
+    notifications: [],
+    session: {
+      sessionId: options.sessionId,
+      controllablePlayerIds: [...options.playerIds],
+      controllingPlayerId: options.playerId || null,
+      userId: options.userId,
+    },
+    history: null,
+    syncId: options.version,
+  };
+}
+
+export function createTestRuntime(
+  options: CreateTestRuntimeOptions,
+): CreatedTestRuntime {
+  const baseState = options.baseStates[options.baseId];
+  if (!baseState) {
+    throw new Error(`Unknown test base '${options.baseId}'.`);
+  }
+
+  let currentState = cloneState(baseState.snapshot);
+  const playerIds = resolvePlayerIds({
+    baseState,
+    explicitPlayerIds: options.playerIds,
+  });
+  const userId = options.userId ?? "test-user";
+  const sessionId = options.sessionId ?? "test-session";
+
+  let version = 0;
+  let currentPlayerId = playerIds[0] ?? "";
+  const stateListeners = new Set<(state: PluginStateSnapshot) => void>();
+  const sessionListeners = new Set<(state: RuntimePluginSessionState) => void>();
+
+  const toReadySessionState = (
+    snapshot: PluginStateSnapshot,
+  ): RuntimePluginSessionState => ({
+    ...snapshot.session,
+    status: "ready",
+  });
+
+  let lastPluginSnapshot: PluginStateSnapshot;
+  let lastSessionState: RuntimePluginSessionState;
+
+  const applyCurrentState = (): void => {
+    const previousSession = lastSessionState;
+    version += 1;
+    lastPluginSnapshot = buildPluginSnapshot({
+      state: currentState,
+      bundle: options.bundle,
+      playerId: currentPlayerId,
+      playerIds,
+      userId,
+      sessionId,
+      version,
+      expectedPhase: version === 1 ? options.phase : undefined,
+      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);
+      }
+    }
+  };
+
+  applyCurrentState();
+
+  const validate = async (
+    playerId: string,
+    interactionId: string,
+    params: unknown = {},
+  ): Promise<ValidationResult> => {
+    const result = await options.bundle.validateInput({
+      state: currentState,
+      input: {
+        kind: "interaction",
+        playerId,
+        interactionId,
+        params: params as Wire.JsonValue,
+      },
+    });
+    return {
+      valid: result.valid,
+      errorCode: result.errorCode,
+      message: result.message,
+    };
+  };
+
+  const submit = async (
+    playerId: string,
+    interactionId: string,
+    params: unknown = {},
+  ): Promise<void> => {
+    const validation = await validate(playerId, interactionId, params);
+    if (!validation.valid) {
+      throw createSubmissionError(validation.errorCode, validation.message);
+    }
+    const result = await options.bundle.dispatch({
+      state: currentState,
+      input: {
+        kind: "interaction",
+        playerId,
+        interactionId,
+        params: params as Wire.JsonValue,
+      },
+    });
+    if (result.kind === "reject") {
+      throw createSubmissionError(result.errorCode, result.message);
+    }
+    currentState = cloneState(result.state);
+    applyCurrentState();
+  };
+
+  const setControllingPlayer = (playerId: string): void => {
+    if (!playerIds.includes(playerId)) {
+      throw new Error(`Unknown controlling player '${playerId}'.`);
+    }
+    currentPlayerId = playerId;
+    applyCurrentState();
+  };
+
+  const runtime = {
+    validateInteraction: validate,
+    submitInteraction: submit,
+    getSessionState: (): RuntimePluginSessionState => lastSessionState,
+    disconnect: () => undefined,
+    switchPlayer: (playerId: string) => {
+      setControllingPlayer(playerId);
+    },
+    getSnapshot: (): PluginStateSnapshot => lastPluginSnapshot,
+    subscribeToState: (listener: (state: PluginStateSnapshot) => void) => {
+      stateListeners.add(listener);
+      return () => {
+        stateListeners.delete(listener);
+      };
+    },
+    _subscribeToSessionState: (
+      listener: (state: RuntimePluginSessionState) => void,
+    ) => {
+      sessionListeners.add(listener);
+      return () => {
+        sessionListeners.delete(listener);
+      };
+    },
+  };
+
+  return {
+    runtime,
+    getSnapshot: () => lastPluginSnapshot,
+    players: () => [...playerIds],
+    seat: (index: number) => {
+      if (!Number.isInteger(index) || index < 0 || index >= playerIds.length) {
+        throw new Error(
+          `seat(${index}) is out of range; base '${options.baseId}' has ${playerIds.length} player(s).`,
+        );
+      }
+      return playerIds[index]!;
+    },
+    submit,
+    validate,
+    setControllingPlayer,
+  };
+}

package/src/testing/definitions.ts

@@ -0,0 +1,127 @@
+export type TestRunner = "reducer" | "embedded" | "browser";
+
+export type InteractionDescriptorLike = {
+  interactionId?: string;
+  surface?: string;
+  kind?: string;
+  availability?: InteractionAvailabilityLike;
+  context?: {
+    to?: string;
+  };
+} & Record<string, unknown>;
+
+export type InteractionAvailabilityLike =
+  | { status: "available" }
+  | { status: "notYourTurn"; reason: string }
+  | {
+      status: "insufficientResources";
+      reason: string;
+      missingResources?: Record<string, unknown>;
+    }
+  | { status: "blocked"; reason: string };
+
+export type SnapshotMatcherHandler = (
+  name: string | undefined,
+  actual: unknown,
+) => void;
+
+export type RejectionExpectation = {
+  errorCode?: string;
+  message?: string | RegExp;
+};
+
+export type ExpectMatchers = {
+  toBe: (expected: unknown) => void;
+  toEqual: (expected: unknown) => void;
+  toMatchObject: (expected: Record<string, unknown>) => void;
+  toBeDefined: () => void;
+  toBeUndefined: () => void;
+  toBeNull: () => void;
+  toContain: (expected: unknown) => void;
+  toContainEqual: (expected: unknown) => void;
+  toHaveLength: (expected: number) => void;
+  toBeGreaterThan: (expected: number) => void;
+  toBeGreaterThanOrEqual: (expected: number) => void;
+  toThrow: (predicate?: string | RegExp | ((error: Error) => boolean)) => void;
+  toMatchSnapshot: (filename?: string) => void;
+  toRejectWith: (expected: RejectionExpectation) => Promise<void>;
+  toHaveInteraction: (
+    interactionId: string,
+    opts?: Partial<InteractionDescriptorLike>,
+  ) => void;
+  toBeGatedBy: (reason: string, opts?: { interactionId?: string }) => void;
+  toBeActiveFor: (playerId: string, opts?: { interactionId?: string }) => void;
+  not: {
+    toHaveInteraction: (interactionId: string) => void;
+  };
+};
+
+export type ExpectFn = (actual: unknown) => ExpectMatchers;
+
+export interface BaseContext<PlayerId extends string = string> {
+  game: {
+    start(): Promise<void>;
+    patchState?(
+      mutator: (state: Record<string, unknown>) => void,
+    ): Promise<void>;
+    submit(
+      playerId: PlayerId,
+      interactionId: string,
+      params?: unknown,
+    ): Promise<void>;
+  };
+  players(): readonly PlayerId[];
+  seat(index: number): PlayerId;
+}
+
+export interface SharedScenarioContext<
+  PlayerId extends string = string,
+  StateName extends string = string,
+  View = unknown,
+  Descriptor extends InteractionDescriptorLike = InteractionDescriptorLike,
+> extends BaseContext<PlayerId> {
+  state(): StateName;
+  view(playerId: PlayerId): View;
+  interactions(playerId: PlayerId): readonly Descriptor[];
+  expect: ExpectFn;
+}
+
+export interface BaseDefinition {
+  id: string;
+  seed?: number;
+  players?: number;
+  setupProfileId?: string | null;
+  extends?: string;
+  setup: (ctx: BaseContext) => void | Promise<void>;
+}
+
+export interface ScenarioDefinition<
+  Runners extends readonly TestRunner[] = readonly ["reducer"],
+  PhaseName extends string = string,
+  StageName extends string = string,
+> {
+  id: string;
+  description?: string;
+  from: string;
+  runners?: Runners;
+  phase?: PhaseName;
+  stage?: StageName;
+  when: (ctx: SharedScenarioContext) => void | Promise<void>;
+  then: (ctx: SharedScenarioContext) => void | Promise<void>;
+}
+
+export function defineBase<const Definition extends BaseDefinition>(
+  definition: Definition,
+): Definition {
+  return definition;
+}
+
+export function defineScenario<
+  const Runners extends readonly TestRunner[] = readonly ["reducer"],
+  const PhaseName extends string = string,
+  const StageName extends string = string,
+>(
+  definition: ScenarioDefinition<Runners, PhaseName, StageName>,
+): ScenarioDefinition<Runners, PhaseName, StageName> {
+  return definition;
+}

package/src/testing/index.ts

@@ -0,0 +1,3 @@
+export * from "./definitions.js";
+export * from "./create-expect-api.js";
+export * from "./create-test-runtime.js";

package/src/testing.ts

@@ -0,0 +1 @@
+export * from "./testing/index.js";

package/src/type-stubs/manifest-contract.d.ts

@@ -0,0 +1,42 @@
+export type PlayerId = string;
+export type ResourceId = string;
+export type CardId = string;
+export type CardIdsByDeckId = Record<string, CardId[]>;
+export type CardProperties = Record<string, unknown>;
+export type EdgeTypeId = string;
+export type VertexTypeId = string;
+export type BoardId = string;
+export type BoardBaseId = string;
+export type PieceId = string;
+export type PieceTypeId = string;
+export type SpaceId = string;
+export type SpaceTypeId = string;
+export type DieId = string;
+
+/**
+ * Stub of the `PerPlayer<Value>` primitive emitted by the real
+ * `@dreamboard-games/sdk/reducer` module. The SDK UI surface does not
+ * depend on SDK reducer directly, so we mirror the structural shape here so
+ * that view types can reference runtime-accurate per-player containers.
+ */
+export type PerPlayer<Value> = {
+  readonly __perPlayer: true;
+  readonly entries: ReadonlyArray<readonly [PlayerId, Value]>;
+};
+
+/**
+ * Stub of the `BoardRef` discriminated union. Shared boards carry only a
+ * `baseId`; per-player boards carry `baseId` plus the runtime `seat` that
+ * scopes them. Matches the structural shape produced by the codegen.
+ */
+export type SharedBoardRef = {
+  readonly baseId: BoardBaseId;
+  readonly seat?: undefined;
+};
+
+export type PerPlayerBoardRef = {
+  readonly baseId: BoardBaseId;
+  readonly seat: PlayerId;
+};
+
+export type BoardRef = SharedBoardRef | PerPlayerBoardRef;

package/src/type-stubs/manifest-contract.js

@@ -0,0 +1,72 @@
+/**
+ * manifest-contract.ts - Dynamically generated types
+ *
+ * This file will be generated based on the game's topology manifest.
+ * The ui-sdk references these types but does not bundle them.
+ *
+ * Note: Shared card collection types such as ViewCard and CardCollection live in
+ * @dreamboard-games/sdk/types, not in this generated manifest contract.
+ */
+export const AllActivePlayerStateNames = [];
+export const ActionsByPhase = {};
+export const boardHelpers = {
+    boardIdsForLayout: ((_) => []),
+    boardBaseIdsForLayout: ((_) => []),
+    boardIdsForBase: ((_) => []),
+    boardBaseIdsForTemplate: ((_) => []),
+    boardIdsForType: ((_) => []),
+    boardLayout: ((_) => "generic"),
+    boardTemplateLayout: ((_) => "generic"),
+    spaceIds: ((_) => []),
+    spaceKinds: ((_) => ({})),
+    spaceIdsForType: ((_) => []),
+    containerIds: ((_) => []),
+    containerHost: ((_, __) => ({ type: "board" })),
+    relationTypeIds: ((_) => []),
+    edgeIdsForType: ((_) => []),
+    edgeIds: ((_, __) => []),
+    authoredHexEdges: ((_) => []),
+    resolveHexEdgeId: ((_, __) => ""),
+    vertexIdsForType: ((_) => []),
+    vertexIds: ((_, __) => []),
+    authoredHexVertices: ((_) => []),
+    resolveHexVertexId: ((_, __) => ""),
+    boardRefForPlayer: ((baseId, seat) => ({ baseId, seat })),
+    sharedBoardRef: ((baseId) => ({ baseId })),
+};
+export function createInitialTable(_options) {
+    return {};
+}
+export function setupProfiles(profiles) {
+    return profiles;
+}
+export function shuffle(container) {
+    return {
+        type: "shuffle",
+        container,
+    };
+}
+export function dealToPlayerZone(options) {
+    return {
+        type: "deal",
+        ...options,
+    };
+}
+export function dealToPlayerBoardContainer(options) {
+    return {
+        type: "deal",
+        ...options,
+    };
+}
+export function seedSharedBoardContainer(options) {
+    return {
+        type: "move",
+        ...options,
+    };
+}
+export function seedSharedBoardSpace(options) {
+    return {
+        type: "move",
+        ...options,
+    };
+}

package/src/type-stubs/ui-contract.d.ts

@@ -0,0 +1,5 @@
+export type ViewName = string;
+export type GameView = Record<string, unknown>;
+export type InferView<_Name extends ViewName> = GameView;
+
+export type PhaseName = string;

package/src/type-stubs/ui-contract.js

@@ -0,0 +1 @@
+export {};