@dreamboard-games/sdk 0.2.1-alpha.1 → 0.3.0-alpha.1

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

@@ -1,381 +0,0 @@
-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

@@ -1,127 +0,0 @@
-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

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

package/src/testing.ts

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

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

@@ -1,42 +0,0 @@
-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

@@ -1,72 +0,0 @@
-/**
- * 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

@@ -1,5 +0,0 @@
-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

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