@dreamboard/ui-sdk

Reducer-native UI SDK for Dreamboard game workspaces. It provides the runtime, headless primitives, visual primitives, default wrappers, and hook escape hatches that turn server-authoritative interaction descriptors into playable React UIs.

API Layers

Authored game UIs usually import from two layers:

• @dreamboard/ui-contract: generated per workspace. Prefer this for workspace-typed primitives and hooks: Interaction, Prompt, PromptInbox, Zone, Board, useGameView, useInteractionByKey, useBoardInteractions, and typed ids for inputs, prompt options, zones, cards, phases, and board targets.
• @dreamboard/ui-sdk: framework-owned primitives and escape hatches that are not game-specific, such as Card, HexGrid, ResourceCounter, ToastProvider, GameEndDisplay, PluginRuntime, and low-level hooks.

Optional styled defaults live at @dreamboard/ui-sdk/defaults.

Rule of thumb: if TypeScript should know this game's interaction id, input key, zone, card id, phase, or board target, import through @dreamboard/ui-contract.

Component-First UI

Reducers declare interactions, inputs, prompts, zones, cards, board targets, and validation. UI components consume those authoritative facts. Reducers should not author visual placement, salience, labels, icons, dialog presentation, or surface grouping metadata.

The generated scaffold starts with primitives:

import { PromptInbox } from "@dreamboard/ui-contract";

export default function App() {
  return (
    <main>
      <PromptInbox.Root>
        <PromptInbox.Empty>No available prompts.</PromptInbox.Empty>
        <PromptInbox.Items />
      </PromptInbox.Root>
    </main>
  );
}

Common primitive families:

• Interaction.Root, Interaction.Label, Interaction.Input, Interaction.CardInput, Interaction.Submit
• Prompt.Root, Prompt.Title, Prompt.Message, Prompt.Options, Prompt.Option
• PromptInbox.Root, PromptInbox.Empty, PromptInbox.Items
• Zone.Root, Zone.List, Zone.Item
• Board typed ids and generated board helpers

Defaults compose those primitives:

import { DefaultPromptInbox, GameLayout } from "@dreamboard/ui-sdk/defaults";

export default function App() {
  return (
    <GameLayout.Root>
      <GameLayout.Sidebar>
        <DefaultPromptInbox />
      </GameLayout.Sidebar>
    </GameLayout.Root>
  );
}

Hooks

Hooks remain available for custom rendering and framework code:

• useGameView() / useGameSelector(...)
• useSeatInbox()
• useInteractionHandle(descriptor)
• useInteractionByKey(key)
• useBoardInteractions()
• useIsMyTurn()
• usePlayerInfo() / useMe()
• usePluginSession()

Prefer the generated re-exports from @dreamboard/ui-contract when the hook is parameterized by a workspace interaction, view, zone, or board target. Use hooks as escape hatches for SVG/canvas boards, advanced gesture layers, or local draft styling; ordinary prompts, actions, card inputs, and zones should be component composition.

Board Rendering

For custom boards, keep reducer-projected eligibility authoritative and route clicks through generated useBoardInteractions():

import { useBoardInteractions } from "@dreamboard/ui-contract";
import { HexGrid } from "@dreamboard/ui-sdk";

function Board() {
  const board = useBoardInteractions();
  return (
    <HexGrid
      interactiveVertices={board.targetLayers.vertex()}
      interactiveEdges={board.targetLayers.edge()}
      interactiveSpaces={board.targetLayers.space()}
    />
  );
}

useBoardInteractions merges currently projected target domains and submits the best matching descriptor. UI code should not recompute legality.

Data Model

Reducer-native plugins receive:

• the projected reducer view for the controlling seat
• current phase and active players
• availableInteractions, the authoritative descriptors for actions and prompts
• zone snapshots for card and collection rendering
• lobby, history, notifications, and session metadata

Plugins do not receive raw reducer/table internals. Availability, costs, target eligibility, and validation are authoritative on descriptors and runtime responses.

Public Package Boundaries

• @dreamboard/ui-sdk: headless runtime behavior, primitives, stable types, visual primitives, and hook escape hatches.
• @dreamboard/ui-sdk/defaults: styled default wrappers over primitives.
• @dreamboard/ui-contract: generated workspace-specific typed aliases and registration.

Deprecated shell/surface helpers are not exported from the public component barrel. Existing internal tests may still cover legacy implementation files until they are deleted, but authored workspaces should not use them.

References

• UI scaffolding policy
• SDK design principles
• Published examples:
  • Hearts
  • Sketchbook
  • Star Settlers