@dreamboard-games/sdk 0.2.0

package/dist/runtime-api-3dshj6kK.d.ts

@@ -0,0 +1,101 @@
+type PlayerId = string;
+
+/**
+ * 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 { PlayerId as P, RuntimeAPI as R, SubmissionError as S, ValidationResult as V, PluginSessionState as a };

package/dist/runtime-api-DWxvTr-O.d.ts

@@ -0,0 +1,379 @@
+import { P as PlayerId } from './runtime-api-3dshj6kK.js';
+import { H as HexColor } from './hex-color-MhOyuY-o.js';
+
+/**
+ * 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 {
+    /** 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;
+}
+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;
+    /** 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;
+}
+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;
+    /** History state for host navigation (null if not host or history disabled) */
+    history: HistoryState | null;
+    /** Monotonic sync ID for acknowledgment tracking */
+    syncId: number;
+}
+
+export type { GameplaySnapshot as G, InputDomain as I, PluginStateSnapshot as P, ZoneHandlesSnapshot as Z, InteractionDescriptor as a, InteractionInputDescriptor as b };

package/dist/runtime.d.ts

@@ -0,0 +1,58 @@
+import { b3 as UIContract$1, A as DreamboardUI$1, b1 as TypedGame$1 } from './ui-contract-iQfTtUSL.js';
+export { a as InteractionDescriptor } from './runtime-api-DWxvTr-O.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import react__default from 'react';
+import './hex-board-view-D_07hO6O.js';
+import './ui/types/player-state.js';
+import './cards-Sl3b40Mv.js';
+import './hex-color-MhOyuY-o.js';
+import './ThemeProvider-fy0_QzgO.js';
+import './runtime-api-3dshj6kK.js';
+
+interface PluginRuntimeProps {
+    /** Child components to render after state sync has started */
+    children: react__default.ReactNode;
+    /**
+     * Timeout in milliseconds to wait for the first state-sync snapshot.
+     * @default 10000 (10 seconds)
+     */
+    timeout?: number;
+    /** Custom loading component to show while waiting for state sync */
+    loadingComponent?: react__default.ReactNode;
+    /** Custom error component to show when initialization fails */
+    errorComponent?: (error: string) => react__default.ReactNode;
+}
+/**
+ * PluginRuntime provides the RuntimeContext for plugin components.
+ *
+ * This component:
+ * - Creates a RuntimeAPI instance using the SDK-provided implementation
+ * - Waits for the first reducer-native state-sync snapshot before rendering children
+ * - Provides RuntimeAPI and session state to all child components
+ *
+ * @example
+ * ```tsx
+ * // In your plugin's index.tsx
+ * import { PluginRuntime } from "./components/dreamboard";
+ * import App from './App';
+ *
+ * ReactDOM.createRoot(document.getElementById('root')!).render(
+ *   <PluginRuntime>
+ *     <App />
+ *   </PluginRuntime>
+ * );
+ * ```
+ */
+declare function PluginRuntime({ children, timeout, loadingComponent, errorComponent, }: PluginRuntimeProps): react_jsx_runtime.JSX.Element;
+
+interface DreamboardUIRegister {
+}
+type UIContract = UIContract$1;
+type RegisteredUIContract = DreamboardUIRegister extends {
+    ui: infer Registered extends UIContract;
+} ? Registered : UIContract;
+type RegisteredUI = RegisteredUIContract;
+type DreamboardUI<Contract extends UIContract = RegisteredUI> = DreamboardUI$1<Contract>;
+type TypedGame<Contract extends UIContract, View = unknown, Player extends string = string, Phase extends string = string> = TypedGame$1<Contract, View, Player, Phase>;
+
+export { type DreamboardUI, type DreamboardUIRegister, PluginRuntime, type PluginRuntimeProps, type RegisteredUI, type TypedGame, type UIContract };

package/dist/runtime.js

@@ -0,0 +1,13 @@
+import {
+  PluginRuntime
+} from "./chunk-7YAHLYBR.js";
+import "./chunk-U5C6BONG.js";
+import "./chunk-TDSWKVZ4.js";
+import "./chunk-KAELH4KC.js";
+import "./chunk-WYPQ3GG5.js";
+import "./chunk-VDXOF4FW.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  PluginRuntime
+};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/slots-1GPGihk8.d.ts

@@ -0,0 +1,8 @@
+interface ViewSlotOccupant<PieceIdValue extends string = string, PlayerIdValue extends string = string, SlotIdValue extends string = string, Data extends Record<string, unknown> = Record<string, unknown>> {
+    pieceId: PieceIdValue;
+    playerId: PlayerIdValue | null;
+    slotId: SlotIdValue;
+    data?: Data;
+}
+
+export type { ViewSlotOccupant as V };