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

package/dist/runtime-api-BXd70c2e.d.ts

@@ -1,490 +0,0 @@
-import { H as HexColor } from './hex-color-MhOyuY-o.js';
-
-type PlayerId = string;
-
-/**
- * Plugin State Types
- *
- * These types define the state structure that the host app sends to the plugin
- * via state-sync messages. The plugin uses these types to access pre-computed
- * game state without needing to parse raw SSE messages.
- */
-type ActionName = string;
-interface SeatAssignment {
-    playerId: PlayerId;
-    controllerUserId?: string;
-    displayName: string;
-    playerColor?: HexColor;
-    isHost?: boolean;
-}
-interface HistoryEntrySummary {
-    id: string;
-    version: number;
-    timestamp: string;
-    description: string;
-    playerId?: PlayerId;
-    actionType?: ActionName;
-    isCurrent: boolean;
-}
-/**
- * Lobby state for the pre-game lobby phase
- */
-interface LobbyState {
-    /** Current seat assignments in the lobby */
-    seats: SeatAssignment[];
-    /** Whether the game can be started (all seats filled) */
-    canStart: boolean;
-    /** User ID of the session host */
-    hostUserId: string;
-}
-/**
- * Notification types that get queued for the plugin
- */
-type NotificationType = "YOUR_TURN" | "PROMPT_OPENED" | "ACTION_EXECUTED" | "ACTION_REJECTED" | "TURN_CHANGED" | "STATE_CHANGED" | "GAME_ENDED" | "ERROR";
-/**
- * YOUR_TURN notification payload
- */
-interface YourTurnPayload {
-    type: "YOUR_TURN";
-    activePlayers: PlayerId[];
-}
-/**
- * PROMPT_OPENED notification payload
- */
-interface PromptOpenedPayload {
-    type: "PROMPT_OPENED";
-    promptId: string;
-    promptInstanceId: string;
-    targetPlayer: PlayerId;
-    title?: string;
-}
-/**
- * ACTION_EXECUTED notification payload
- */
-interface ActionExecutedPayload {
-    type: "ACTION_EXECUTED";
-    playerId: PlayerId;
-    actionType: string;
-}
-/**
- * ACTION_REJECTED notification payload
- */
-interface ActionRejectedPayload {
-    type: "ACTION_REJECTED";
-    reason: string;
-    targetPlayer?: string;
-}
-/**
- * STATE_CHANGED notification payload
- */
-interface StateChangedPayload {
-    type: "STATE_CHANGED";
-    newState: string;
-}
-/**
- * TURN_CHANGED notification payload
- */
-interface TurnChangedPayload {
-    type: "TURN_CHANGED";
-    previousPlayers: PlayerId[];
-    currentPlayers: PlayerId[];
-}
-/**
- * GAME_ENDED notification payload
- */
-interface GameEndedPayload {
-    type: "GAME_ENDED";
-    winner?: string;
-    finalScores: Record<string, number>;
-    reason: string;
-}
-/**
- * ERROR notification payload
- */
-interface ErrorPayload {
-    type: "ERROR";
-    message: string;
-    code?: string;
-}
-/**
- * Union of all notification payloads
- */
-type NotificationPayload = YourTurnPayload | PromptOpenedPayload | ActionExecutedPayload | ActionRejectedPayload | TurnChangedPayload | StateChangedPayload | GameEndedPayload | ErrorPayload;
-/**
- * Notification entry in the queue.
- * Notifications are ephemeral events that the plugin can consume and mark as read.
- */
-interface Notification {
-    /** Unique notification ID */
-    id: string;
-    /** Type of notification */
-    type: NotificationType;
-    /** Type-specific payload */
-    payload: NotificationPayload;
-    /** Timestamp when the notification was created */
-    timestamp: number;
-    /** Whether the plugin has marked this notification as read */
-    read: boolean;
-}
-/**
- * Session state that gets synchronized to the plugin.
- * This includes player switching info that was previously sent via
- * separate player-switched messages.
- */
-interface PluginSessionState$1 {
-    /** Current session ID */
-    sessionId: string | null;
-    /** Player IDs that this user can control (immutable after game starts) */
-    controllablePlayerIds: PlayerId[];
-    /** The currently selected player ID that the user is controlling */
-    controllingPlayerId: PlayerId | null;
-    /** User ID of the controller */
-    userId: string | null;
-}
-/**
- * History state for the host's history navigator.
- * Only sent to the host user.
- */
-interface HistoryState {
-    /** List of history entries (newest first when displayed) */
-    entries: HistoryEntrySummary[];
-    /** Index of the current state in the history */
-    currentIndex: number;
-    /** Whether there are earlier states to restore to */
-    canGoBack: boolean;
-    /** Whether there are later states to restore to */
-    canGoForward: boolean;
-}
-/** Choice option surfaced on a prompt-kind interaction's structured context. */
-interface InteractionContextOption {
-    id: string;
-    label?: string;
-}
-/** Structured context attached to a prompt-kind InteractionDescriptor. */
-interface InteractionContext {
-    /** Addressed player id. */
-    to: string;
-    title?: string;
-    /** Authored prompt payload. Shape is defined by the game's prompt schema. */
-    payload?: Record<string, unknown>;
-    /** Selectable options for choice-kind prompts. */
-    options?: readonly InteractionContextOption[];
-}
-type InteractionCommitPolicy = {
-    mode: "manual";
-} | {
-    mode: "autoWhenReady";
-};
-type InputSelection = {
-    mode: "single";
-} | {
-    mode: "many";
-    min: number;
-    max?: number;
-    distinct?: boolean;
-};
-type InputDomain = CardTargetDomain | BoardTargetDomain | ResourceMapDomain | BoundedNumberDomain | ChoiceDomain | ChoiceListDomain;
-type InputDomainResolver = EagerInputDomainDependencies | LazyInputDomainDependencies;
-interface EagerInputDomainDependencies {
-    mode: "eager";
-    dependentCases: readonly InputDomainDependencyCase[];
-}
-interface LazyInputDomainDependencies {
-    mode: "lazy";
-    dependsOn: readonly string[];
-    resolver: {
-        interactionKey?: string;
-        inputKey: string;
-    };
-}
-interface ResolvedCardTargetDomain {
-    type: "cardTarget";
-    projection: "resolved";
-    zoneId?: string;
-    zoneIds?: readonly string[];
-    eligibleTargets: readonly string[];
-    selection?: InputSelection;
-    dependencies?: InputDomainResolver;
-}
-interface LazyCardTargetDomain {
-    type: "cardTarget";
-    projection: "lazy";
-    zoneId?: string;
-    zoneIds?: readonly string[];
-    selection?: InputSelection;
-    dependencies: LazyInputDomainDependencies;
-}
-type CardTargetDomain = ResolvedCardTargetDomain | LazyCardTargetDomain;
-interface ResolvedBoardTargetDomain {
-    type: "boardTarget";
-    projection: "resolved";
-    targetKind: string;
-    boardId?: string;
-    eligibleTargets: readonly string[];
-    selection?: InputSelection;
-    dependencies?: InputDomainResolver;
-}
-interface LazyBoardTargetDomain {
-    type: "boardTarget";
-    projection: "lazy";
-    targetKind: string;
-    boardId?: string;
-    selection?: InputSelection;
-    dependencies: LazyInputDomainDependencies;
-}
-type BoardTargetDomain = ResolvedBoardTargetDomain | LazyBoardTargetDomain;
-interface ResourceMapDomain {
-    type: "resourceMap";
-    resources?: ReadonlyArray<{
-        resourceId: string;
-        label?: string;
-        icon?: string;
-        min: number;
-        max: number;
-    }>;
-    dependencies?: InputDomainResolver;
-}
-interface BoundedNumberDomain {
-    type: "boundedNumber";
-    min?: number;
-    max?: number;
-    step?: number;
-    dependencies?: InputDomainResolver;
-}
-interface ChoiceDomain {
-    type: "choice";
-    choices?: readonly InteractionChoiceOption[];
-    selection?: InputSelection;
-    dependencies?: InputDomainResolver;
-}
-interface ChoiceListDomain {
-    type: "choiceList";
-    choices?: readonly InteractionChoiceOption[];
-    min?: number;
-    max?: number;
-    selection?: InputSelection;
-    dependencies?: InputDomainResolver;
-}
-interface InputDomainDependencyCase {
-    when: Readonly<Record<string, string>>;
-    domain: InputDomain;
-}
-interface InteractionChoiceOption {
-    value: string | null;
-    label: string;
-    icon?: string;
-    badge?: string;
-    description?: string;
-    disabled?: boolean;
-    disabledReason?: string;
-}
-interface InteractionInputDescriptor {
-    key: string;
-    kind: string;
-    domain: InputDomain;
-    defaultValue?: unknown;
-}
-interface InteractionDiagnosticReason {
-    ruleId: string;
-    errorCode: string;
-}
-type InteractionAvailability = {
-    status: "available";
-} | {
-    status: "notYourTurn";
-    reason: string;
-} | {
-    status: "insufficientResources";
-    reason: string;
-    missingResources: Readonly<Record<string, number>>;
-} | {
-    status: "blocked";
-    reason: string;
-    code?: string;
-};
-interface InteractionDescriptorBase<Key extends string = string> {
-    phaseName: string;
-    interactionKey: Key;
-    interactionId: string;
-    /** Draft commit policy. Always materialized by the trusted reducer bundle. */
-    commit: InteractionCommitPolicy;
-    /** Canonical descriptor digest used by browser replay/protocol tooling when projected by the host. */
-    descriptorDigest?: string;
-    /** Explicit authoring/runtime actor seat used by browser replay draft digests. */
-    actorSeat?: number;
-    /** Canonical draft digest used by browser replay/protocol tooling when projected by the host. */
-    draftDigest?: string;
-    /** Source zone id for zone-scoped interactions (e.g., cardInput). */
-    zoneId?: string;
-    /** Source zone ids for zone-scoped interactions that span multiple zones. */
-    zoneIds?: readonly string[];
-    /** Ordered input descriptors. This is the canonical source for input keys, collector kind, and valid-value domains. */
-    inputs: readonly InteractionInputDescriptor[];
-    /** Resolved cost map keyed by resource id (if interaction declares one). */
-    cost?: Record<string, unknown>;
-    /** Snapshot of seat's currently available resources keyed by resource id. */
-    currentResources?: Record<string, unknown>;
-    /** Authoritative availability state for this descriptor. */
-    availability: InteractionAvailability;
-    /** Optional verbose diagnostics for dev tooling; omitted from production projections. */
-    reasons?: readonly InteractionDiagnosticReason[];
-}
-type ActionInteractionDescriptor<Key extends string = string> = InteractionDescriptorBase<Key> & {
-    kind: "action";
-};
-type PromptInteractionDescriptor<Key extends string = string> = InteractionDescriptorBase<Key> & {
-    kind: "prompt";
-    /** Structured prompt context for prompt-kind interactions. */
-    context: InteractionContext;
-};
-type InteractionDescriptor<Key extends string = string> = ActionInteractionDescriptor<Key> | PromptInteractionDescriptor<Key>;
-/**
- * Per-player view of a single zone. Mirrors the ZoneHandles wire shape from
- * the trusted bundle's resolveZoneHandles; `cardViewsById` is JSON-serialized
- * `ViewCard` and `playableByCardId` lists the interactions that are playable
- * on each card (eligibility already filtered by each interaction's validate).
- */
-interface ZoneHandlesSnapshot<InteractionType extends string = string> {
-    cardIds: readonly string[];
-    cardViewsById: Readonly<Record<string, string>>;
-    playableByCardId: Readonly<Record<string, ReadonlyArray<InteractionDescriptor<InteractionType>>>>;
-}
-interface SimultaneousPhaseSnapshot {
-    phaseName: string;
-    interactionId: string;
-    actorIds: PlayerId[];
-    sealedPlayerIds: PlayerId[];
-    pendingPlayerIds: PlayerId[];
-}
-interface GameplaySnapshot<PhaseType extends string = string, StageType extends string = string, InteractionType extends string = string> {
-    currentPhase: PhaseType | null;
-    currentStage: StageType | null;
-    activePlayers: PlayerId[];
-    simultaneousPhase?: SimultaneousPhaseSnapshot | null;
-    availableInteractions: ReadonlyArray<InteractionDescriptor<InteractionType>>;
-    /**
-     * Zone handles scoped to the controlling player. Keyed by zoneId.
-     * Authored via phase `zones`; projected from `resolveZoneHandles`.
-     */
-    zones: Readonly<Record<string, ZoneHandlesSnapshot<InteractionType>>>;
-}
-/**
- * The complete state snapshot sent to the plugin via state-sync.
- * This is the single source of truth for all reducer-native plugin state.
- */
-interface PluginStateSnapshot<View = unknown, PhaseType extends string = string, StageType extends string = string, InteractionType extends string = string> {
-    /** Projected seat-specific reducer-native view for the controlling player */
-    view: View | null;
-    /** Gameplay transport state that sits alongside the projected reducer view */
-    gameplay: GameplaySnapshot<PhaseType, StageType, InteractionType>;
-    /** Lobby state (from LOBBY_UPDATE) - null if game has started */
-    lobby: LobbyState | null;
-    /** Notification queue (from YOUR_TURN, ACTION_REJECTED, PROMPT_OPENED, etc.) */
-    notifications: Notification[];
-    /** Session state (includes controllingPlayerId for player switching) */
-    session: PluginSessionState$1;
-    /** History state for host navigation (null if not host or history disabled) */
-    history: HistoryState | null;
-    /** Monotonic sync ID for acknowledgment tracking */
-    syncId: number;
-}
-
-/**
- * Result of validating a player action
- */
-interface ValidationResult {
-    /** Whether the action is valid */
-    valid: boolean;
-    /** Machine-readable error code if validation failed */
-    errorCode?: string;
-    /** Human-readable error message if validation failed */
-    message?: string;
-}
-/**
- * Structured authoritative submission failure returned by runtime submit APIs.
- */
-interface SubmissionError extends Error {
-    /** Machine-readable error code when available */
-    errorCode?: string;
-}
-/**
- * Plugin session state
- */
-interface PluginSessionState {
-    /** Session initialization status */
-    status: "loading" | "ready";
-    /** Current session ID (null if not initialized) */
-    sessionId: string | null;
-    /** Player IDs that this user can control (immutable after game starts) */
-    controllablePlayerIds: PlayerId[];
-    /** The currently selected player ID that the user is controlling */
-    controllingPlayerId: PlayerId | null;
-    /** User ID of the controller (null if not initialized) */
-    userId: string | null;
-}
-/**
- * RuntimeAPI provides the interface between plugin code and the game runtime.
- * This API is exposed to plugin iframes for subscribing to game events and submitting actions.
- */
-interface RuntimeAPI {
-    /**
-     * Validate a player interaction before submitting it. `params` is typed
-     * as `unknown` because a `promptInput` collector can declare a scalar
-     * response schema (`z.enum([...])`, `z.string()`, `z.number()`, ...)
-     * while ordinary collectors pass an object.
-     *
-     * @param playerId - ID of the player performing the interaction
-     * @param interactionId - Identifier of the interaction
-     * @param params - Interaction-specific payload
-     * @returns Promise that resolves with validation result
-     */
-    validateInteraction: (playerId: PlayerId, interactionId: string, params: unknown) => Promise<ValidationResult>;
-    /**
-     * Submit a player interaction to the game server. `submitInteraction`
-     * is the single submission verb for every interaction kind — authors
-     * do not split between "action" and "prompt response" calls.
-     *
-     * @param playerId - ID of the player performing the interaction
-     * @param interactionId - Identifier of the interaction
-     * @param params - Interaction-specific payload (see
-     *   {@link validateInteraction} for the `unknown` typing rationale)
-     * @throws SubmissionError if submission is rejected by the authority.
-     */
-    submitInteraction: (playerId: PlayerId, interactionId: string, params: unknown) => Promise<void>;
-    /**
-     * Get the current plugin session state.
-     * Returns initialization status and session/player IDs.
-     *
-     * @returns Current plugin session state
-     *
-     * @example
-     * ```typescript
-     * const { status, sessionId, playerId } = runtime.getSessionState();
-     * if (status === "ready") {
-     *   console.log('Connected to session:', sessionId);
-     * }
-     * ```
-     */
-    getSessionState: () => PluginSessionState;
-    /**
-     * Disconnect from the runtime and clean up all listeners.
-     * Should be called when the plugin is unmounting.
-     */
-    disconnect: () => void;
-    /**
-     * Request to switch to a different player.
-     * Only works if the user controls multiple seats.
-     * The parent window will handle the switch and update the session state.
-     *
-     * @param playerId - ID of the player to switch to
-     *
-     * @example
-     * ```typescript
-     * // Switch to player-2
-     * runtime.switchPlayer?.('player-2');
-     * ```
-     */
-    switchPlayer?: (playerId: PlayerId) => void;
-}
-
-export type { GameplaySnapshot as G, InputDomain as I, PlayerId as P, RuntimeAPI as R, SubmissionError as S, ValidationResult as V, ZoneHandlesSnapshot as Z, InteractionDescriptor as a, InteractionInputDescriptor as b, PluginSessionState as c, PluginStateSnapshot as d };