dreamboard 0.1.21 → 0.1.23

package/skills/dreamboard/references/core-concepts.md

@@ -1,514 +0,0 @@
-# Core concepts
-
-Learn Dreamboard's core concepts through real reducer, UI, and test code.
-
-Dreamboard games are authored as a small TypeScript program. The same authored
-program feeds the reducer runtime, generated UI contract, generated testing
-contract, and local CLI checks.
-
-The snippets below use generic SDK-shaped code and scaffold patterns.
-
-## Manifest
-
-The manifest is the static table model. Author it in `manifest.ts` with
-`defineTopologyManifest`.
-
-```ts
-import { defineTopologyManifest } from "@dreamboard/sdk-types";
-
-export default defineTopologyManifest({
-  players: {
-    minPlayers: 3,
-    maxPlayers: 4,
-    optimalPlayers: 4,
-  },
-
-  zones: [
-    {
-      id: "action-deck",
-      name: "Action Deck",
-      scope: "shared",
-      allowedCardSetIds: ["action-cards"],
-      visibility: "hidden",
-    },
-    {
-      id: "player-hand",
-      name: "Player Hand",
-      scope: "perPlayer",
-      allowedCardSetIds: ["action-cards"],
-      visibility: "ownerOnly",
-    },
-    {
-      id: "played-cards",
-      name: "Played Cards",
-      scope: "shared",
-      allowedCardSetIds: ["action-cards"],
-      visibility: "public",
-    },
-  ],
-
-  boardTemplates: [
-    {
-      id: "shared-board-template",
-      name: "Shared board template",
-      layout: "hex",
-      orientation: "pointy-top",
-      spaces: [
-        { id: "cell-01", q: 0, r: 0, typeId: "standard" },
-        { id: "cell-02", q: 1, r: -1, typeId: "standard" },
-      ],
-    },
-  ],
-});
-```
-
-`dreamboard sync` turns the manifest into generated ID unions, ID schemas,
-runtime table types, board helpers, setup helpers, and typed UI/test contracts.
-
-## Game contract
-
-The game contract binds the generated manifest contract to reducer state schemas
-and phase names.
-
-```ts
-import { z } from "zod";
-import { ids, manifestContract } from "../shared/manifest-contract";
-import {
-  defineGameContract,
-  sparseCounts,
-  type GameStateOf,
-} from "@dreamboard/app-sdk/reducer";
-
-const playerTurnPhaseStateSchema = z.object({
-  step: z.enum(["roll", "resolve", "main", "cleanup"]),
-  diceRolled: z.boolean(),
-  diceValues: z
-    .tuple([z.number().int().min(1).max(6), z.number().int().min(1).max(6)])
-    .nullable(),
-});
-
-export const gameContract = defineGameContract({
-  manifest: manifestContract,
-  state: {
-    public: z.object({
-      progressByPlayer: sparseCounts(ids.playerId),
-    }),
-    private: z.object({}),
-    hidden: z.object({}),
-  },
-  phaseNames: ["setup", "playerTurn"] as const,
-});
-
-export type GameContract = typeof gameContract;
-export type GameState = GameStateOf<GameContract>;
-export type PlayerTurnPhaseState = z.infer<typeof playerTurnPhaseStateSchema>;
-```
-
-The contract is the reducer's type root. If a phase name, player id, card id,
-zone id, board id, or state field changes, dependent reducer/UI/test code should
-fail to compile.
-
-## Game definition
-
-`defineGame` assembles the contract into a runnable reducer definition. Initial
-state belongs here, not in `defineGameContract`.
-
-```ts
-import {
-  defineGame,
-  type ReducerGameDefinition,
-} from "@dreamboard/app-sdk/reducer";
-import { gameContract, type GameContract } from "./game-contract";
-import { phases } from "./phases";
-import { playerView } from "./player-view";
-import { boardStatic } from "./board-static";
-import setupProfiles from "./setup-profiles";
-
-const views = {
-  player: playerView,
-};
-
-const game: ReducerGameDefinition<GameContract, typeof phases, typeof views> =
-  defineGame({
-    contract: gameContract,
-    initial: {
-      public: ({ playerIds }) => {
-        const progressByPlayer: Record<string, number> = {};
-        for (const pid of playerIds) {
-          // Session-time player ids come from the manifest-backed setup.
-          progressByPlayer[pid] = 0;
-        }
-        return { progressByPlayer };
-      },
-      private: () => ({}),
-      hidden: () => ({}),
-    },
-    initialPhase: "setup",
-    setupProfiles,
-    phases,
-    views,
-    staticView: boardStatic,
-  });
-
-export default game;
-```
-
-Generated UI and testing contracts read from this definition. Registered phases,
-interactions, zones, and board targets become typed UI/test primitives
-automatically.
-
-## Phase
-
-A phase owns a slice of game flow: phase-local state, actor selection, optional
-entry behavior, interactions, card actions, stages, and zones.
-
-```ts
-import { definePhase, pipe } from "@dreamboard/app-sdk/reducer";
-import { zones } from "../../../shared/manifest-contract";
-import {
-  playerTurnPhaseStateSchema,
-  type GameContract,
-} from "../../game-contract";
-import { rollDice } from "./roll-dice";
-import { playActionCard } from "./card-actions";
-import { endTurn } from "./end-turn";
-import { FRESH_TURN } from "./turn-state";
-
-export const playerTurn = definePhase<GameContract>()({
-  kind: "player",
-  state: playerTurnPhaseStateSchema,
-  initialState: () => ({ ...FRESH_TURN }),
-  enter({ state, accept, ops, q }) {
-    const activePlayer = state.flow.activePlayers[0] ?? q.player.order()[0]!;
-
-    // Entering from setup seeds the first turn. Later turns are set by endTurn.
-    return accept(pipe(state, ops.setActivePlayers([activePlayer])));
-  },
-  actor: ({ state }) => state.flow.activePlayers,
-  zones: [zones.playerHand],
-  cardActions: {
-    playActionCard,
-  },
-  interactions: {
-    rollDice,
-    endTurn,
-  },
-});
-```
-
-Use phases for real game-flow states: setup, turn, discard, resolve prompt,
-round cleanup, and end game.
-
-## Interaction
-
-An interaction is a player-submitted command or prompt. The trusted runtime
-authorizes the actor, validates input collectors, parses params, and only then
-calls `reduce`.
-
-```ts
-import {
-  defineInteraction,
-  rngInput,
-  pipe,
-} from "@dreamboard/app-sdk/reducer";
-import {
-  playerTurnPhaseStateSchema,
-  type GameContract,
-} from "../../game-contract";
-
-export const rollDice = defineInteraction<
-  GameContract,
-  typeof playerTurnPhaseStateSchema
->()({
-  step: "roll",
-  visibility: "all",
-  inputs: {
-    // The client submits no dice values. The trusted reducer bundle samples
-    // both dice and passes the result to reduce as input.params.dice.values.
-    dice: rngInput.d6(2),
-  },
-  validate({ state }) {
-    if (state.phase.diceRolled) {
-      return {
-        errorCode: "ALREADY_ROLLED",
-        message: "Already rolled this turn.",
-      };
-    }
-    return null;
-  },
-  reduce({ state, input, accept, ops }) {
-    const [d1, d2] = input.params.dice.values;
-    return accept(
-      pipe(
-        state,
-        ops.patchPhaseState({
-          step: "main",
-          diceRolled: true,
-          diceValues: [d1!, d2!],
-        }),
-      ),
-    );
-  },
-});
-```
-
-Use `validate` for business rules. Do not repeat turn authorization in every
-interaction when phase-level `actor` already owns it.
-
-## Card action
-
-A card action is a hand-oriented interaction. It is tied to a `cardType` and a
-`playFrom` zone, and the runtime adds `cardId` to reducer params.
-
-```ts
-import { defineCardAction, pipe } from "@dreamboard/app-sdk/reducer";
-import {
-  playerTurnPhaseStateSchema,
-  type GameContract,
-} from "../../game-contract";
-import { cardTypes, zones } from "../../../shared/manifest-contract";
-
-export const playActionCard = defineCardAction<
-  GameContract,
-  typeof playerTurnPhaseStateSchema
->()({
-  cardType: cardTypes.bonus,
-  playFrom: zones.playerHand,
-  label: "Play action card",
-  step: "main",
-  reduce({ state, input, accept, ops }) {
-    return accept(
-      pipe(
-        state,
-        ops.moveCardFromPlayerZoneToSharedZone({
-          playerId: input.playerId,
-          fromZoneId: zones.playerHand,
-          toZoneId: zones.playedCards,
-          cardId: input.params.cardId,
-          playedBy: input.playerId,
-        }),
-        ops.patchPhaseState({ actionCardPlayedThisTurn: true }),
-      ),
-    );
-  },
-});
-```
-
-Use `defineCardAction` for "play this card from hand" mechanics. Use
-`defineInteraction` for actions that are not fundamentally card-instance plays.
-
-## Input collector
-
-An input collector describes one parameter for an interaction. Collectors are
-the source of reducer parameter types and client-facing metadata.
-
-```ts
-import { boardInput, formInput } from "@dreamboard/app-sdk/reducer";
-import type { GameState } from "../../game-contract";
-import {
-  literals,
-  type ResourceId,
-  type SpaceId,
-} from "../../../shared/manifest-contract";
-import { tokenSpaceTarget } from "../../eligibility";
-
-const moveTokenInputs = {
-  spaceId: boardInput.space<GameState, SpaceId>({
-    target: tokenSpaceTarget,
-  }),
-  receiveResource: formInput.choice<ResourceId>({
-    choices: literals.resourceIds.map((resourceId) => ({
-      value: resourceId,
-      label: resourceId,
-    })),
-  }),
-};
-```
-
-Engine-sampled collectors such as `rngInput.*` appear in reducer params but are
-omitted from client-submitted params.
-
-## Target rule
-
-A target rule is a finite eligibility rule built with `boardTarget`,
-`cardTarget`, or `choiceTarget`.
-
-```ts
-import { boardTarget } from "@dreamboard/app-sdk/reducer";
-import type { GameState } from "./game-contract";
-import type { EdgeId } from "../shared/manifest-contract";
-import { markerAt } from "./reducer-support";
-
-export const buildMarkerTarget = boardTarget
-  .edge<GameState, EdgeId>("sector")
-  .where({
-    id: "empty",
-    errorCode: "EDGE_OCCUPIED",
-    message: "That edge already has a marker.",
-    test: ({ state, q, targetId }) => !markerAt(state, q, targetId),
-  })
-  .where({
-    id: "connected",
-    errorCode: "NOT_CONNECTED",
-    message: "Marker must connect to your network.",
-    // Local domain helpers can use the same state/q/playerId inputs as targets.
-    test: ({ state, q, targetId, playerId }) =>
-      isConnectedMarkerTarget(state, q, targetId, playerId),
-  })
-  .build();
-```
-
-The same rule should drive UI hints, submit validation, and tests. That keeps
-"which space/card/choice is legal?" out of duplicated UI code.
-
-## View
-
-A dynamic view is the player-facing projection authored with `defineView`. UI
-code should read views and generated hooks, not raw reducer state.
-
-```ts
-import { defineView } from "@dreamboard/app-sdk/reducer";
-import type { GameContract, PlayerTurnPhaseState } from "./game-contract";
-import { scoreLeader } from "./derived";
-
-export const playerView = defineView<GameContract>()({
-  project({ state, playerId, q, derived }) {
-    const turn: PlayerTurnPhaseState | null =
-      state.flow.currentPhase === "playerTurn"
-        ? (state.phase as PlayerTurnPhaseState)
-        : null;
-
-    return {
-      diceRolled: turn?.diceRolled ?? false,
-      diceValues: turn?.diceValues ?? null,
-      myResources: q.player.resources(playerId),
-      leader: derived(scoreLeader),
-    };
-  },
-});
-```
-
-Views receive state, `playerId`, runtime helpers, table queries, and derived
-value access.
-
-## Static view
-
-A static view is session-scoped immutable data derived from the manifest and
-static queries.
-
-```ts
-import { defineStaticView } from "@dreamboard/app-sdk/reducer";
-import type { GameContract } from "./game-contract";
-
-export const boardStatic = defineStaticView<GameContract>()({
-  project: ({ q }) => {
-    // Board topology does not change during play, so the UI can cache it.
-    return q.board.hex("sector");
-  },
-});
-```
-
-Use static views for board topology, labels, and precomputed decoration derived
-from the manifest.
-
-## Derived value
-
-A derived value is a pure reusable computation authored with `defineDerived`.
-It is memoized for one state snapshot.
-
-```ts
-import { defineDerived } from "@dreamboard/app-sdk/reducer";
-import type { GameContract } from "./game-contract";
-import type { PlayerId } from "../shared/manifest-contract";
-
-// Finds the current leader from stored per-player progress for this state.
-export const scoreLeader = defineDerived<GameContract>()({
-  name: "scoreLeader",
-  compute: ({ state, q }): { playerId: PlayerId | null; score: number } => {
-    let playerId: PlayerId | null = null;
-    let score = 0;
-
-    for (const pid of q.player.order()) {
-      const playerScore = state.publicState.progressByPlayer[pid] ?? 0;
-      if (playerScore > score) {
-        playerId = pid;
-        score = playerScore;
-      }
-    }
-
-    return { playerId, score };
-  },
-});
-```
-
-Keep source facts in state and compute aggregates from them.
-
-## UI primitive
-
-Generated UI primitives are typed React wrappers for the reducer contract. They
-let UI code submit interactions, answer prompts, render zones, and target board
-spaces without stringly typed input names.
-
-```tsx
-import {
-  Interaction,
-  PromptInbox,
-  Zone,
-  useInteractionByKey,
-} from "@dreamboard/ui-contract";
-
-export function PlayerTurnPanel() {
-  const rollDice = useInteractionByKey("playerTurn.rollDice");
-
-  return (
-    <section>
-      <PromptInbox.Root>
-        <PromptInbox.Empty>No prompts.</PromptInbox.Empty>
-        <PromptInbox.Items />
-      </PromptInbox.Root>
-
-      <Interaction.Root interaction="playerTurn.rollDice">
-        <Interaction.Submit disabled={!rollDice?.canSubmit}>
-          Roll dice
-        </Interaction.Submit>
-      </Interaction.Root>
-
-      <Zone.Root zone="playerHand">
-        <Zone.List />
-      </Zone.Root>
-    </section>
-  );
-}
-```
-
-Use `@dreamboard/ui-contract` for game-specific typing and `@dreamboard/ui-sdk`
-for generic components such as cards, boards, resources, dice, and player
-chrome.
-
-## Scenario
-
-A scenario is a reducer-native test authored with `defineScenario`.
-
-```ts
-import { defineScenario } from "../testing-types";
-
-export default defineScenario({
-  id: "player-turn-roll",
-  description: "Seat 0 rolls dice on their first turn after setup",
-  from: "after-setup",
-  when: async ({ game, seat }) => {
-    // rollDice uses rngInput.d6(2), so the client submits no params.
-    await game.submit(seat(0), "rollDice", {});
-  },
-  then: ({ expect, state, view, seat }) => {
-    expect(state()).toBe("playerTurn");
-
-    const p1View = view(seat(0));
-    expect(p1View.diceRolled).toBe(true);
-    expect(p1View.diceValues).not.toBeNull();
-  },
-});
-```
-
-Scenarios verify the same reducer bundle that `dreamboard dev` runs. They are
-the fastest way to prove reducer behavior without a browser.

package/skills/dreamboard/references/custom-renderers.md

@@ -1,26 +0,0 @@
-# Custom renderers
-
-Use hooks as local escape hatches while keeping reducer behavior authoritative.
-
-Most UI should be built from `Interaction`, `Prompt`, `PromptInbox`, and `Zone`
-components. Use hooks when component composition cannot express the UI.
-
-Good hook escape hatches:
-
-- SVG or canvas board geometry
-- gesture-heavy interaction layers
-- styling a card based on draft state
-- integrating a complex third-party renderer
-
-```tsx
-const buildRoute = useInteractionByKey("playerTurn.buildRoute");
-const board = useBoardInteractions();
-```
-
-Do not use hooks to recreate a generic action panel or prompt inbox. Prefer
-primitives and defaults for ordinary actions, prompts, card selection, and
-zones.
-
-When a custom renderer needs a descriptor, bind it through
-`useInteractionByKey` or `useInteractionHandle`; do not call runtime transport
-methods directly.

package/skills/dreamboard/references/derived-values.md

@@ -1,55 +0,0 @@
-# Derived values
-
-Use defineDerived for reusable, memoized pure computations over reducer state and table queries.
-
-Derived values are pure computations over one state snapshot. They are useful for expensive or repeated calculations: longest route, area majority, winner selection, eligible scoring sets, or aggregate card/resource summaries.
-
-```ts
-export const winnerOf = defineDerived<GameContract>()({
-  name: "winnerOf",
-  compute: ({ state, q }) => {
-    const players = q.player.order();
-    const scores = players.map((playerId) => ({
-      playerId,
-      score: state.publicState.scores[playerId] ?? 0,
-    }));
-    return scores.toSorted((a, b) => b.score - a.score)[0]?.playerId ?? null;
-  },
-});
-```
-
-Read it from reducer callbacks or views through injected `derived`:
-
-```ts
-reduce({ state, derived, accept, ops }) {
-  const winnerPlayerId = derived(winnerOf);
-  return accept(pipe(state, ops.patchPublicState({ winnerPlayerId })));
-}
-```
-
-## Cache lifetime
-
-Derived values are memoized by definition identity for one state snapshot. Each engine tick and each view projection gets a fresh resolver.
-
-That means:
-
-- repeated reads of the same derived value in one callback are cheap
-- derived values should be pure
-- cache lifetime does not cross reducer steps
-- derived values can depend on other derived values through `derived(...)`
-
-Cyclic derived dependencies throw a readable error.
-
-## Do not cache mirrors in publicState
-
-Avoid this pattern:
-
-```ts
-publicState: {
-  scoreByPlayerId: ...
-}
-```
-
-if the value can be recomputed from board occupancy, card locations, resources, or other source facts. Store the source facts and derive the aggregate.
-
-Use state for mutable facts. Use `defineDerived` for computed meaning.

package/skills/dreamboard/references/effects.md

@@ -1,111 +0,0 @@
-# Effects
-
-Use defineEffect and fx.effect for engine-side dice rolls and zone shuffles.
-
-Effects are engine-side cues. They are for runtime work the pure reducer should not perform itself, such as rolling a die or shuffling a shared or player zone.
-
-Effects are authored with `defineEffect`, registered on a phase, and dispatched with `fx.effect`.
-
-## Shuffle a shared zone
-
-```ts
-const shuffleDeck = defineEffect<GameContract>()({
-  type: "shuffleSharedZone",
-  id: "shuffle-deck",
-});
-
-export const shufflePhase = definePhase<GameContract>()({
-  kind: "auto",
-  state: z.object({}),
-  initialState: () => ({}),
-  effects: {
-    shuffleDeck,
-  },
-  stages: {
-    shuffle: definePhaseStage<GameContract, typeof phaseState>()({
-      allow: [],
-      onEnter({ state, accept, fx }) {
-        return accept(state, [
-          fx.effect(shuffleDeck, { zoneId: "draw" }),
-          fx.transition("deal"),
-        ]);
-      },
-    }),
-  },
-});
-```
-
-After the runtime shuffles the zone, later reducer code can deal deterministically from the top with `ops.dealCardsToPlayerZone`.
-
-Use `shufflePlayerZone` when the runtime should shuffle a single player's zone:
-
-```ts
-const shuffleHand = defineEffect<GameContract>()({
-  type: "shufflePlayerZone",
-  id: "shuffle-hand",
-});
-
-fx.effect(shuffleHand, {
-  zoneId: "hand",
-  playerId: input.playerId,
-});
-```
-
-## Roll a die with a continuation
-
-Use `reduce` on an effect when the reducer needs the engine result.
-
-```ts
-const rollProduction = defineEffect<GameContract>()({
-  type: "rollDie",
-  id: "roll-production",
-  context: z.object({
-    reason: z.string(),
-  }),
-  reduce({ state, input, accept, ops }) {
-    return accept(
-      pipe(
-        state,
-        ops.patchPublicState({
-          lastRoll: input.response.value,
-          lastRollReason: input.data.reason,
-        }),
-      ),
-    );
-  },
-});
-```
-
-Dispatch it from a reducer callback:
-
-```ts
-return accept(state, [
-  fx.effect(rollProduction, {
-    dieId: "production-die",
-    context: { reason: "turn-start" },
-  }),
-]);
-```
-
-The `context` is author data captured when the effect is queued. `input.response` is the engine result.
-
-## Effects are not prompts
-
-Use effects for engine work:
-
-- `rollDie`
-- `shuffleSharedZone`
-- `shufflePlayerZone`
-
-Use [Interactions](./interactions.md) with `promptInput` for addressed player requests. Prompts are player submissions; effects are runtime instructions.
-
-## Effects and rngInput
-
-`rngInput.d6(2)` is different from `defineEffect({ type: "rollDie" })`.
-
-| Primitive | Use when |
-| --- | --- |
-| `rngInput.*` | Randomness is sampled as part of one player interaction submit. |
-| `defineEffect` + `fx.effect` | Randomness or shuffling should be queued as a runtime instruction, often from an auto phase or with a continuation. |
-
-Prefer the simpler `rngInput.*` when the random value is only needed inside the same interaction's `reduce`.