dreamboard 0.1.21 → 0.1.23

package/skills/dreamboard/references/interactions.md

@@ -1,158 +0,0 @@
-# Interactions
-
-Use defineInteraction to author player commands, prompts, inputs, validation, and reducer logic.
-
-Interactions are the canonical player-facing reducer primitive. They define what
-a player can submit and how the reducer responds.
-
-```ts
-const placeThingCard = defineInteraction<
-  GameContract,
-  typeof placeThingPhaseStateSchema
->()({
-  step: "placing",
-  inputs: {
-    cardId: cardInput<GameState, ThingsDeckCardId>({
-      target: placeableThingCardTarget,
-    }),
-    ringId: formInput(zoneIdSchema),
-  },
-  rules: [
-    {
-      id: "knower-cannot-place",
-      errorCode: "KNOWER_CANNOT_PLACE",
-      message: "The Knower cannot place Things.",
-      validate: ({ state, input }) =>
-        input.playerId === state.publicState.knowerPlayerId
-          ? {
-              errorCode: "KNOWER_CANNOT_PLACE",
-              message: "The Knower cannot place Things.",
-            }
-          : null,
-    },
-  ],
-  reduce({ state, input, accept, fx, ops }) {
-    return accept(
-      pipe(
-        state,
-        ops.moveCardFromPlayerZoneToSharedZone({
-          playerId: input.playerId,
-          fromZoneId: "things-hand",
-          toZoneId: input.params.ringId,
-          cardId: input.params.cardId,
-          playedBy: input.playerId,
-        }),
-      ),
-      [fx.transition("judgeRings")],
-    );
-  },
-});
-```
-
-## Required shape
-
-| Field | Purpose |
-| --- | --- |
-| `inputs` | Collector map that defines params, target metadata, defaults, and client schemas. |
-| `rules` | Shared availability and validation rules that can disable descriptors before params exist and reject parsed submissions. |
-| `paramsSchema` | Optional cross-field Zod schema layered on top of collector params. |
-| `cost` | Optional resource cost descriptor for UI-visible affordability. |
-| `commit` | Optional draft submit policy such as `{ mode: "manual" }` or `{ mode: "autoWhenReady" }`. |
-| `reduce` | Pure reducer callback that accepts or rejects a state transition. |
-
-Optional reducer fields such as `step`, `steps`, `actor`, `to`, `visibility`,
-`rules`, `paramsSchema`, `cost`, and `commit` are still reducer authority:
-they control who can act, when the descriptor exists, which targets are legal,
-which params are accepted, and how the UI can present affordability.
-
-Reducers do not own visual placement, labels, salience, icons, grouping, dialog
-chrome, or presentation policy. Put those choices in React, CSS, or default UI
-wrappers built on the generated primitives.
-
-## Authorization
-
-Actor authorization is handled by the trusted bundle before `reduce` runs.
-
-Use phase-level `actor` for ordinary turns:
-
-```ts
-actor: ({ state }) => state.flow.activePlayers
-```
-
-Use interaction-level `actor` when one interaction has a different actor. Use
-`to` for addressed prompt interactions.
-
-Do not duplicate the same turn check in every `validate` callback unless the
-interaction has a business rule that differs from actor authorization.
-
-## Availability and validation
-
-Use `rules` to share descriptor availability and submit validation. Each rule
-can expose `available` for pre-param UI state, `validate` for parsed params, or
-both. Extract repeated rules with `defineInteractionRule`.
-
-```ts
-const canAffordBuild = defineInteractionRule<GameContract, typeof phaseState>()({
-  id: "can-afford-build",
-  errorCode: "INSUFFICIENT_RESOURCES",
-  message: "You need more resources.",
-  available: ({ input, q }) => q.player.canAfford(input.playerId, BUILD_COST),
-  validate: ({ input, q }) =>
-    q.player.canAfford(input.playerId, BUILD_COST)
-      ? null
-      : { errorCode: "INSUFFICIENT_RESOURCES" },
-});
-
-const build = defineInteraction<GameContract, typeof phaseState>()({
-  inputs: {},
-  cost: BUILD_COST,
-  rules: [canAffordBuild],
-  reduce({ state, accept }) {
-    return accept(state);
-  },
-});
-```
-
-Target collectors run their own validation before authored rules. Use
-`paramsSchema` when a rule spans multiple fields. For example, Star Settlers
-uses collector domains for trade controls and a `paramsSchema` to require at
-least one offered and requested resource.
-
-## Prompts
-
-Prompt-kind interactions are ordinary `defineInteraction` entries with a
-`promptInput` collector. The runtime projects them as prompt descriptors and
-addresses them with `to`.
-
-```ts
-const respondToTrade = defineInteraction<GameContract, typeof phaseState>()({
-  inputs: {
-    response: promptInput({
-      schema: z.enum(["accept", "reject"]),
-      target: choiceTarget
-        .options<GameState, "accept" | "reject">([
-          { id: "accept", label: "Accept" },
-          { id: "reject", label: "Reject" },
-        ])
-        .build(),
-    }),
-  },
-  to: ({ state }) => state.phase.pendingTrade?.targetPlayerIds ?? null,
-  reduce({ state, input, accept }) {
-    // input.params.response is "accept" | "reject"
-    return accept(state);
-  },
-});
-```
-
-Render prompt descriptors with `PromptInbox`, `Prompt`, and `Prompt.Option`
-from `@dreamboard/ui-contract`; the reducer only declares the response domain.
-
-## Client params vs reducer params
-
-Generated UI/test params omit engine-sampled collectors such as
-`rngInput.d6(2)`. Reducer params include them because the trusted bundle samples
-them before calling `reduce`.
-
-See [Inputs and targets](./inputs-and-targets.md) for collector
-details.

package/skills/dreamboard/references/manifest-fields.md

@@ -1,137 +0,0 @@
-# Manifest fields
-
-Reference manifest schemas, component homes, visibility, slot hosts, and setup fields.
-
-Manifest fields let you attach typed static data to cards, pieces, dice, boards, spaces, edges, vertices, relations, and containers.
-
-## Field schemas
-
-Schemas use Dreamboard's manifest property schema format, not Zod. The generated manifest contract turns these into typed values.
-
-```ts
-cardSets: [
-  {
-    type: "manual",
-    id: "contracts",
-    name: "Contracts",
-    cardSchema: {
-      properties: {
-        rewardCoins: { type: "integer" },
-        route: { type: "enum", enums: ["market", "river", "trail"] },
-        targetBoard: { type: "boardId" },
-        targetSpace: { type: "spaceId" },
-        bonusResource: { type: "resourceId", optional: true },
-      },
-    },
-    cards: [
-      {
-        type: "ferry-charter",
-        name: "Ferry Charter",
-        count: 2,
-        properties: {
-          rewardCoins: 2,
-          route: "river",
-          targetBoard: "frontier-map",
-          targetSpace: "ford",
-          bonusResource: "provisions",
-        },
-      },
-    ],
-  },
-];
-```
-
-Reference fields by their manifest ids instead of plain strings. `defineTopologyManifest` rejects values that do not match the current manifest.
-
-## Component homes
-
-Cards, pieces, and dice can start in zones, board spaces, board containers, tiled edges, tiled vertices, or slots.
-
-```ts
-pieceSeeds: [
-  {
-    id: "worker-1",
-    typeId: "worker",
-    ownerId: "player-1",
-    home: {
-      type: "slot",
-      host: { kind: "piece", id: "mat-player-1" },
-      slotId: "farm",
-    },
-  },
-];
-```
-
-Use `ownerId` for player-owned seeds. For per-player board or zone homes, include enough ownership data for the runtime to resolve the actual player-scoped container.
-
-## Visibility
-
-Visibility belongs in the manifest when it is a static property of a component or zone.
-
-Common patterns:
-
-| Visibility | Use for |
-| --- | --- |
-| `public` | Shared face-up information. |
-| `hidden` | Decks or piles where contents/order are not public. |
-| `ownerOnly` | Per-player hands or private player areas. |
-| `{ faceUp: false }` | Manual cards that should start face down. |
-
-Runtime secrecy still belongs in state and projections. A card being in an owner-only zone does not mean every view should expose all secret data about that card.
-
-## Slots
-
-Slots model fixed attachment points on pieces or dice. They are useful for worker mats, die trays, upgrade sockets, or other component-hosted positions.
-
-```ts
-pieceTypes: [
-  {
-    id: "player-mat",
-    name: "Player Mat",
-    slots: [
-      { id: "farm", name: "Farm" },
-      { id: "market", name: "Market" },
-    ],
-  },
-];
-```
-
-Slots are static topology. Runtime occupancy is read through `q.slot.*` and moved through table operations.
-
-## Setup options and profiles
-
-Use `setupOptions` for knobs that change game setup. Use `setupProfiles` for named presets.
-
-```ts
-setupOptions: [
-  {
-    id: "map-size",
-    name: "Map size",
-    choices: [
-      { id: "small", name: "Small" },
-      { id: "wide", name: "Wide" },
-    ],
-  },
-],
-setupProfiles: [
-  {
-    id: "default",
-    name: "Default",
-    optionValues: { "map-size": "small" },
-  },
-],
-```
-
-The generated setup profile helper keeps authored `optionValues` aligned with the available setup option and choice ids.
-
-## When not to use fields
-
-Do not use manifest fields to mirror mutable state. Examples that should be reducer state or table state:
-
-- current resource balances
-- whether a card has been played this turn
-- which player owns a temporary claim
-- current turn step
-- pending selected target
-
-The manifest should describe what can exist. The reducer state and table describe what is currently true.

package/skills/dreamboard/references/manifest.md

@@ -1,81 +0,0 @@
-# Manifest
-
-Use defineTopologyManifest to declare the static table model for a Dreamboard game.
-
-The manifest is the static source of truth for a game. It names the objects that the reducer, UI, tests, and setup code should agree on: players, card sets, zones, boards, pieces, dice, resources, setup options, and setup profiles.
-
-Author it in `manifest.ts`:
-
-```ts
-import { defineTopologyManifest } from "@dreamboard/sdk-types";
-
-export default defineTopologyManifest({
-  players: {
-    minPlayers: 2,
-    maxPlayers: 4,
-    optimalPlayers: 3,
-  },
-  cardSets: [],
-  zones: [],
-  boards: [],
-});
-```
-
-`defineTopologyManifest` returns the manifest unchanged at runtime, but it gives TypeScript enough information to reject invalid IDs and incompatible component locations while you author.
-
-## What belongs in the manifest
-
-Put static, setup-time structure in the manifest:
-
-| Manifest section | Use for |
-| --- | --- |
-| `players` | Player count bounds and generated player ids. |
-| `cardSets` | Manual or preset card sets, card schemas, card counts, starting homes. |
-| `zones` | Shared piles and per-player hands. |
-| `boardTemplates` | Reusable board definitions. |
-| `boards` | Shared or per-player board instances. |
-| `pieceTypes` and `pieceSeeds` | Piece schemas, slots, starting pieces, ownership, starting homes. |
-| `dieTypes` and `dieSeeds` | Dice, dice fields, starting dice, ownership, starting homes. |
-| `resources` | Player resource ids and labels. |
-| `setupOptions` | User-selectable setup knobs. |
-| `setupProfiles` | Named setup presets that choose setup-option values. |
-
-Do not put runtime facts in the manifest. Current scores, active turn, pending prompts, drawn card ids, resource balances, and temporary decisions belong in reducer state or the runtime table.
-
-## Generated contract
-
-After changing the manifest, run:
-
-```bash
-dreamboard sync
-```
-
-The generated `shared/manifest-contract.ts` exposes:
-
-- `literals`, including ids such as `playerIds`, `cardIds`, `zoneIds`, and `setupProfileIds`
-- `ids`, a Zod schema namespace for manifest-backed ids
-- `manifestContract`, the object passed into `defineGameContract`
-- runtime table types such as `TableState`
-- setup profile helpers
-- typed helper constructors for setup bootstrap steps
-
-Use generated exports instead of duplicating string unions:
-
-```ts
-import { ids, literals, manifestContract } from "../shared/manifest-contract";
-
-const playerIdSchema = ids.playerId;
-const knownZones = literals.zoneIds;
-```
-
-## Canonical authoring rule
-
-If a thing has an identity that the reducer, UI, or tests need to agree on, define that identity in the manifest. Let generated types carry that identity forward.
-
-Avoid local parallel lists such as `const ZONES = [...]` unless they are derived from, or intentionally narrower than, manifest-generated ids.
-
-## Related pages
-
-- [Manifest fields](./manifest-fields.md) for schemas, homes, visibility, and strict slots.
-- [Boards and topology](./boards-and-topology.md) for board layouts and tiled IDs.
-- [Game contract](./game-contract.md) for binding the manifest into reducer state.

package/skills/dreamboard/references/package-surfaces.md

@@ -1,69 +0,0 @@
-# Public package imports
-
-Which Dreamboard packages game authors should import.
-
-Dreamboard keeps the author-facing package surface narrow. Prefer generated
-workspace contracts for game-specific typing and package primitives for generic
-runtime or visuals.
-
-## Package roles
-
-| Surface | Role |
-| --- | --- |
-| `@dreamboard/app-sdk/reducer` | Public reducer authoring API. |
-| `@dreamboard/ui-sdk` | Public React runtime hooks, primitives, themes, and generic components. |
-| `@dreamboard/ui-sdk/defaults` | Default UI wrappers exported from `ui-sdk`; `@dreamboard/ui-defaults` is retired. |
-| `@dreamboard/ui-contract` | Generated per-workspace alias backed by `shared/generated/ui-contract.ts`, not an npm package. |
-| `@dreamboard/testing` | Public reducer-native testing helpers used by generated `test/testing-types.ts`. |
-| `@dreamboard/api-client` | Generated public API client used by tooling and integrations. |
-| `@dreamboard/sdk-types` | Manifest and authoring types shared by generated code. |
-| `@dreamboard/workspace-codegen` | Internal generator package used by the CLI. |
-
-## Authored reducer code
-
-```ts
-import {
-  defineGame,
-  defineInteraction,
-  definePhase,
-  formInput,
-} from "@dreamboard/app-sdk/reducer";
-```
-
-## Authored UI code
-
-```tsx
-import {
-  Interaction,
-  PromptInbox,
-  Zone,
-  useBoardInteractions,
-  useGameView,
-  useInteractionByKey,
-} from "@dreamboard/ui-contract";
-```
-
-Use `@dreamboard/ui-sdk` for generic components and runtime helpers:
-
-```tsx
-import { Card, HexGrid, ResourceCounter, ToastProvider } from "@dreamboard/ui-sdk";
-```
-
-Use `@dreamboard/ui-sdk/defaults` when you want styled package-owned wrappers:
-
-```tsx
-import { DefaultPromptInbox, GameLayout } from "@dreamboard/ui-sdk/defaults";
-```
-
-Do not import generated files by relative path from authored UI unless you are
-inside generated test support. `@dreamboard/ui-contract` is the stable alias.
-
-## Testing code
-
-Use the generated testing contract:
-
-```ts
-import { defineScenario } from "../testing-types";
-```
-
-Generated contracts keep test params aligned with reducer inputs.

package/skills/dreamboard/references/phases.md

@@ -1,145 +0,0 @@
-# Phases
-
-Use definePhase to model game-flow states, actors, interactions, effects, stages, zones, and card actions.
-
-A phase is a named state in the game flow. Phases are where reducers expose player interactions, automatic resolution, prompts, effects, zones, and card actions.
-
-```ts
-export const playerTurn = definePhase<GameContract>()({
-  kind: "player",
-  state: playerTurnPhaseStateSchema,
-  initialState: () => ({ step: "roll", diceRolled: false }),
-  enter({ state, accept, ops, q }) {
-    const activePlayer = state.flow.activePlayers[0] ?? q.player.order()[0]!;
-    return accept(pipe(state, ops.setActivePlayers([activePlayer])));
-  },
-  actor: ({ state }) => state.flow.activePlayers,
-  interactions: {
-    rollDice,
-    endTurn,
-  },
-});
-```
-
-## Organize large phases
-
-A single `app/phases/player-turn.ts` file is fine while the phase is small.
-Once it has several action families, shared input/presentation helpers, card
-actions, or grows past roughly 250-300 lines, move it into a phase folder and
-split by game concept:
-
-```txt
-app/phases/player-turn/
-  index.ts        # definePhase assembly only
-  state.ts        # phase-local constants and types
-  inputs.ts       # shared form inputs, targets, and presentation helpers
-  build.ts        # build interactions
-  trade.ts        # trade interactions and prompt lifecycle
-  dev-cards.ts    # card actions
-  end-turn.ts     # end-turn interaction
-```
-
-Keep `index.ts` as the table of contents. It should import interactions and
-card actions, register them in `definePhase`, and export only the phase plus
-any stable test-facing schemas. Put reducer bodies in neighboring concept
-files.
-
-Do not split by reducer callback shape. Files named `validate.ts`,
-`reduce.ts`, or `schemas.ts` usually force readers to jump across files to
-understand one move. Prefer domain concepts such as build, trade, scoring,
-discard, or dev cards.
-
-## Phase fields
-
-| Field          | Purpose                                                                                       |
-| -------------- | --------------------------------------------------------------------------------------------- |
-| `kind`         | `"player"` waits for player input; `"simultaneousPlayer"` waits for sealed player submissions; `"auto"` resolves through reducer logic. |
-| `state`        | Zod schema for phase-local state.                                                             |
-| `initialState` | Optional initializer for phase-local state.                                                    |
-| `enter`        | Optional hook that runs when the phase is entered.                                             |
-| `actor`        | Default actor selector for interactions in this phase.                                         |
-| `actors`       | Actor selector for simultaneous-player submissions.                                            |
-| `submit`       | Canonical sealed submission interaction for `kind: "simultaneousPlayer"`.                     |
-| `resolve`      | Batch resolver for a simultaneous phase after all actors submit.                               |
-| `effects`      | Registered engine-side effects dispatched through `fx.effect`.                                 |
-| `interactions` | Player commands and prompts authored with `defineInteraction`.                                 |
-| `stages`       | First-match sub-phase selectors and allow lists.                                               |
-| `zones`        | Declarative cardholder projections for generated `Zone` primitives.                            |
-| `cardActions`  | Card-instance actions authored with `defineCardAction`.                                        |
-
-## Player phases
-
-Use `kind: "player"` when the runtime should wait for a player or prompt recipient to submit an interaction.
-
-Actor selection is explicit. A phase-level `actor` is usually enough for ordinary turn-taking:
-
-```ts
-actor: ({ state }) => state.flow.activePlayers;
-```
-
-Specific interactions can override `actor`. Prompt-style interactions can use `to` to address one or more players.
-
-## Simultaneous player phases
-
-Use `kind: "simultaneousPlayer"` when multiple players should choose at the same time, such as card passing in Sushi Go, choosing cards in Hearts, or any other hidden commitment step.
-
-The runtime stores each player's `submit` params as sealed SDK-owned state. Individual submissions do not mutate game state. Once every actor has submitted, the phase-level `resolve` callback receives the full submission batch and applies one deterministic state change.
-
-```ts
-export const chooseCards = definePhase<GameContract>()({
-  kind: "simultaneousPlayer",
-  state: chooseCardsPhaseStateSchema,
-  actors: ({ q }) => q.player.order(),
-  submit: {
-    inputs: {
-      cardId: formInput.choice({
-        choices: [
-          { value: "card-a", label: "Card A" },
-          { value: "card-b", label: "Card B" },
-        ],
-      }),
-    },
-  },
-  resolve({ state, submissions, accept, ops }) {
-    // Runs once, after every actor has submitted.
-    const revealed = Object.values(submissions).map((submission) => ({
-      playerId: submission.playerId,
-      cardId: submission.params.cardId,
-    }));
-
-    return accept(
-      pipe(state, ops.patchPublicState({ revealedChoices: revealed })),
-    );
-  },
-});
-```
-
-By default each actor can submit once. Set `canResubmit: true` when players may replace their sealed choice before the final actor submits.
-
-Use normal `interactions` for side actions that should mutate immediately, and use `to` prompts for addressed interrupts. The `submit` interaction is the barrier: the SDK validates it, hides it from players who already submitted, keeps choices hidden from other seats, and calls `resolve` only when the batch is complete.
-
-## Auto phases
-
-Use `kind: "auto"` for deterministic resolution steps: shuffle startup, deal cards, score cleanup, or final winner calculation.
-
-Auto phases often do their work in a stage `onEnter` hook and immediately transition:
-
-```ts
-stages: {
-  shuffle: definePhaseStage<GameContract, typeof phaseState>()({
-    allow: [],
-    onEnter({ state, accept, fx }) {
-      return accept(state, [
-        fx.effect(shuffleDeck, { zoneId: "draw" }),
-        fx.transition("deal"),
-      ]);
-    },
-  }),
-}
-```
-
-## Keep phase state narrow
-
-Put temporary, phase-specific facts in `state.phase`: current step, pending discard list, selected trade partner, or "has rolled this turn".
-
-Put persistent cross-phase facts in `publicState`, `privateState`, `hiddenState`, or the table. If a value is recomputable from table state, prefer a [Derived value](./derived-values.md) instead of storing a mirror.

package/skills/dreamboard/references/prompts-and-choices.md

@@ -1,55 +0,0 @@
-# Prompts and choices
-
-Render addressed prompt interactions with generated Prompt primitives.
-
-Prompts are ordinary interactions with a `promptInput` collector and `to`
-addressees. Render them with generated prompt primitives.
-
-```tsx
-import { PromptInbox } from "@dreamboard/ui-contract";
-
-<PromptInbox.Root>
-  <PromptInbox.Empty>No prompts</PromptInbox.Empty>
-  <PromptInbox.Items />
-</PromptInbox.Root>
-```
-
-For custom prompt chrome:
-
-```tsx
-import { Prompt } from "@dreamboard/ui-contract";
-
-<Prompt.Root interaction="playerTurn.respondToTrade">
-  <Prompt.Title />
-  <Prompt.Message />
-  <Prompt.Options />
-</Prompt.Root>
-```
-
-`Prompt.Option` submits the prompt response through the typed input from the
-descriptor. The reducer controls recipients, options, availability, and
-validation. React controls copy layout, dialog shells, and visual treatment.
-
-Use `useInteractionByKey` only when the prompt is part of a bespoke local
-component that needs draft state or a custom submit sequence.
-
-## Dialog prompts
-
-Use generated `PromptDialogHost` when you want package behavior with local
-dialog chrome:
-
-```tsx
-import { PromptDialogHost } from "@dreamboard/ui-contract";
-
-<PromptDialogHost
-  className="trade-dialog"
-  onSubmitError={showToast}
-  renderBody={({ prompt }) => (
-    <TradeOfferSummary prompt={prompt} />
-  )}
-/>;
-```
-
-Star Settlers uses this pattern for trade prompts: the reducer still owns
-recipients and accepted options, while React owns the modal body and error
-presentation.