dreamboard 0.1.21 → 0.1.22

package/skills/dreamboard/references/quickstart.md

@@ -1,71 +0,0 @@
-# Quickstart
-
-Install Dreamboard, create a workspace, sync generated contracts, compile, and run locally.
-
-## Requirements
-
-- Node 20 or newer
-
-## Install
-
-```bash
-npm install -g dreamboard
-dreamboard login
-```
-
-`dreamboard login` opens a browser for authentication.
-
-## Create a workspace
-
-```bash
-dreamboard new my-deck-builder --description "An exciting deck builder for 4 players"
-cd my-deck-builder
-```
-
-The generated workspace contains generated contracts, a React UI, and reducer-native tests. Read [Workspace layout](./workspace-layout.md) before changing generated files.
-
-## Sync generated files
-
-Run sync after changing `manifest.ts`, reducer definitions, testing contracts, or scaffold-owned files:
-
-```bash
-dreamboard sync
-```
-
-`sync` regenerates local contracts from authored source and upload the source files to Dreamboard server for compilation. 
-
-```bash
-pnpm install
-```
-
-## Compile
-
-```bash
-dreamboard compile
-```
-
-Compile runs local checks, builds the reducer bundle, and uploads the compiled artifact to Dreamboard server.
-
-## Run locally
-
-```bash
-dreamboard dev
-```
-
-Starts a local Vite server for playtesting the game. It runs the UI locally but connects to Dreamboard server for streaming game state. Open the printed URL to play the current compiled game.
-
-## Add test coverage
-
-```bash
-dreamboard test generate
-dreamboard test run
-```
-
-`test generate` writes workspace-specific testing wrappers and generated contracts. `test run` replays scenario files under `test/scenarios`.
-
-## Next steps
-
-- [Manifest](./manifest.md) explains the static table model.
-- [Game contract](./game-contract.md) explains state and phase names.
-- [Interactions](./interactions.md) explains player commands and prompts.
-- [CLI](./cli.md) is the command reference.

package/skills/dreamboard/references/rule-authoring.md

@@ -1,144 +0,0 @@
-# Rule authoring
-
-Reference for authoring Dreamboard rule.md files.
-
-`rule.md` is the game-design source of intent for a Dreamboard project. Use it
-to describe the rules in plain language before you commit to reducer state,
-manifest, or UI details.
-
-## What `rule.md` is for
-
-Use `rule.md` for:
-
-- the game objective and match shape
-- setup, turn flow, scoring, and victory rules
-- player actions and their legality constraints
-- visibility rules and information flow
-- edge cases and deterministic tie-break rules
-
-## Recommended structure
-
-Use the same section order for every `rule.md`.
-
-### `Overview`
-
-State the core promise of the game in one short section.
-
-- supported player count
-- objective
-- expected match length
-- one-paragraph summary of how a turn feels
-
-### `Components`
-
-List the components the rules assume exist.
-
-- cards, zones, boards, pieces, dice, and resources
-- public versus hidden information
-- per-player versus shared components
-- hard limits such as hand size, stock limits, or caps
-
-### `Setup`
-
-Describe the initial state in ordered steps.
-
-- how players are seated
-- which player acts first
-- which components start in which locations
-- any setup options or setup-profile differences
-
-### `Gameplay`
-
-Describe the game loop in the order the reducer should implement it.
-
-For each phase, name:
-
-- who is allowed to act
-- which actions are legal
-- what input each action requires
-- what ends the phase
-- which phase follows next
-
-When a game has repeated rounds, document the round loop explicitly instead of
-implying it.
-
-### `Scoring and progression`
-
-Describe how players gain or lose progress.
-
-- points, tracks, resources, or thresholds
-- when scoring happens
-- round-end or trick-end resolution
-- tie-breakers for intermediate rankings
-
-### `Winning conditions`
-
-State the exact end trigger and winner resolution rule.
-
-- when the game ends
-- how the winner is chosen
-- how ties are broken
-- what happens if multiple end conditions become true at once
-
-### `Special rules and edge cases`
-
-List rules that are easy to miss during implementation.
-
-- simultaneous actions
-- empty-deck or empty-pool behavior
-- no-op or invalid actions
-- forced actions versus optional actions
-- what happens when a player cannot act
-
-## Example template
-
-```markdown
-# <Game name>
-
-## Overview
-
-- Players: <min-max> (optimal: <n>)
-- Objective: <how a player wins>
-- Duration: <target minutes>
-
-## Components
-
-- Shared components:
-- Per-player components:
-- Public information:
-- Hidden information:
-
-## Setup
-
-1. ...
-2. ...
-3. ...
-
-## Gameplay
-
-### Phase 1: <name>
-
-- Acting player(s):
-- Allowed actions:
-- Validation:
-- Completion:
-- Next phase:
-
-### Phase 2: <name>
-
-- ...
-
-## Scoring and progression
-
-- ...
-
-## Winning conditions
-
-- End trigger:
-- Winner determination:
-- Tie-breaker:
-
-## Special rules and edge cases
-
-- ...
-```

package/skills/dreamboard/references/setup-bootstrap.md

@@ -1,78 +0,0 @@
-# Setup bootstrap
-
-Seed initial table state from setup profiles with typed shuffle, deal, and move steps.
-
-Setup bootstrap steps move components into their starting runtime locations before normal phases run. Use them for deterministic setup work that belongs to a setup profile rather than to turn logic.
-
-Setup profiles are usually authored through the generated `setupProfiles` helper:
-
-```ts
-import {
-  dealToPlayerZone,
-  setupProfiles,
-  shuffle,
-} from "../shared/manifest-contract";
-
-export default setupProfiles({
-  "default-setup": {
-    initialPhase: "playerTurn",
-    bootstrap: [
-      shuffle({ type: "sharedZone", zoneId: "draw" }),
-      dealToPlayerZone({
-        from: { type: "sharedZone", zoneId: "draw" },
-        zoneId: "hand",
-        count: 5,
-      }),
-    ],
-  },
-});
-```
-
-## Step types
-
-| Step | Use for |
-| --- | --- |
-| `shuffle` | Shuffle a shared zone or board container during setup. |
-| `deal` | Deal from a shared zone/container to a per-player zone/container. |
-| `move` | Move specific or counted components into zones, board spaces, or board containers. |
-
-Generated helpers include:
-
-- `shuffle`
-- `dealToPlayerZone`
-- `dealToPlayerBoardContainer`
-- `seedSharedBoardContainer`
-- `seedSharedBoardSpace`
-
-These helpers are typed against the manifest, so invalid zone, board, space, container, card, piece, or die ids fail at author time.
-
-## Bootstrap vs phase enter
-
-Use bootstrap for static setup:
-
-- shuffle starting decks
-- deal opening hands
-- place fixed pieces
-- seed shared board spaces or containers
-
-Use phase `enter` for dynamic setup:
-
-- choose first player from runtime state
-- branch by setup selection
-- compute state fields from player count
-- run setup that depends on reducer logic
-
-It is normal to combine both: bootstrap seeds the table, then the first phase initializes active players or public state.
-
-## Initial phase
-
-A setup profile may override the game definition's `initialPhase`:
-
-```ts
-"short-game": {
-  initialPhase: "playerTurn",
-  bootstrap: [...],
-}
-```
-
-Keep `initialPhase` values aligned with `gameContract.phaseNames`.

package/skills/dreamboard/references/stages-and-zones.md

@@ -1,59 +0,0 @@
-# Stages and zones
-
-Use stages for phase sub-states and zones for declarative hand rendering.
-
-Stages and zones are optional phase-level primitives. Use them when they simplify a phase without creating extra phase names.
-
-## Stages
-
-Stages are first-match sub-state selectors inside a phase. Declaration order is priority: the first `when` predicate that returns `true` becomes the current stage.
-
-```ts
-stages: {
-  discard: definePhaseStage<GameContract, typeof phaseState>()({
-    when: ({ state }) => state.phase.step === "discard",
-    allow: ["discardCards"],
-  }),
-  main: definePhaseStage<GameContract, typeof phaseState>()({
-    when: ({ state }) => state.phase.step === "main",
-    allow: ["buildPath", "tradeWithBank", "endTurn"],
-  }),
-}
-```
-
-`allow` gates which interaction ids are available in that stage.
-
-Stages can also use `onEnter` and `onExit` hooks:
-
-```ts
-onEnter({ state, accept, ops }) {
-  return accept(pipe(state, ops.patchPhaseState({ enteredMain: true })));
-}
-```
-
-Use stages when one phase has clear internal steps but the surrounding flow is still one conceptual phase.
-
-## Zones
-
-Zones declare which manifest player card zones are projected for generated
-`Zone` primitives.
-
-```ts
-zones: [zones.actionHand],
-cardActions: {
-  playBoost,
-  playDrawCards,
-  playBuildPath,
-},
-```
-
-Each entry is a manifest player zone id that stores cards. Import `zones` from the generated manifest contract and use handles such as `zones.actionHand` instead of raw string ids. The runtime reads cards from listed zones and derives playable actions from phase `cardActions` whose `playFrom` matches the zone id.
-
-The runtime dry-runs each derived card action's validation to determine per-card
-playability for UI primitives.
-
-## Zone keys
-
-Manifest zone ids often use kebab case, such as `action-hand`. Generated UI contracts expose JS-friendly zone keys such as `actionHand` for surface configuration while preserving the manifest zone id at runtime.
-
-Keep the manifest zone id as the source of truth. Do not maintain a parallel UI-only zone id list.

package/skills/dreamboard/references/static-views.md

@@ -1,67 +0,0 @@
-# Static views
-
-Use defineStaticView for immutable session-scoped projection such as decorated board topology.
-
-Static views project immutable data once per reducer session. They receive only the manifest and static queries, so they cannot accidentally include per-player or per-turn state.
-
-```ts
-export const boardStatic = defineStaticView<GameContract>()({
-  project: ({ q }) => {
-    const board = q.board.hex("island");
-    return {
-      ...board,
-      portsByVertexId: computePorts(board),
-    };
-  },
-});
-```
-
-Register it in `defineGame`:
-
-```ts
-export default defineGame({
-  contract: gameContract,
-  phases,
-  views: { player: playerView },
-  staticView: boardStatic,
-});
-```
-
-## What belongs in static views
-
-Good static-view data:
-
-- board topology
-- precomputed board decoration
-- labels and ids derived from manifest literals
-- fixed layout data for UI components
-- static adjacency lookup tables
-
-Bad static-view data:
-
-- current pieces on spaces
-- active player
-- card locations
-- resource balances
-- prompts or available actions
-- anything dependent on `state`, `playerId`, or `runtime`
-
-Those belong in [Views](./views.md), interactions, or table queries.
-
-## Static query surface
-
-Static views use manifest-backed static queries:
-
-```ts
-const board = q.board.get("map");
-const hex = q.board.hex("island");
-const square = q.board.square("grid");
-```
-
-Use this instead of rebuilding board topology manually in the workspace.
-
-## Why static views matter
-
-Large board topology can dominate runtime update payloads if it is projected on every action. Static views move that data into a once-per-session payload and let dynamic views focus on changing state.
-
-Keep game-specific decoration local. If the access pattern is broadly reusable, it should become an SDK query instead of repeated workspace code.

package/skills/dreamboard/references/table-queries-and-ops.md

@@ -1,103 +0,0 @@
-# Table queries and ops
-
-Read runtime table state with q, write with ops, and compose deterministic state transitions with pipe.
-
-Reducer callbacks receive two canonical table helpers:
-
-- `q` for reads
-- `ops` for writes
-
-Use them instead of reading or mutating `state.table` directly.
-
-## Read with q
-
-`q` is a typed query namespace over the runtime table:
-
-```ts
-const playerIds = q.player.order();
-const hand = q.zone.playerCards(playerId, "things-hand");
-const card = q.card.get(cardId);
-const board = q.board.hex("island");
-const vertices = q.board.incidentVertices("island", edgeId);
-const resources = q.player.resources(playerId);
-```
-
-Common groups:
-
-| Namespace | Reads |
-| --- | --- |
-| `q.board.*` | Boards, spaces, containers, edges, vertices, adjacency, occupants. |
-| `q.zone.*` | Shared zones, per-player zones, card collections. |
-| `q.card.*` | Runtime card data, owner, visibility. |
-| `q.component.*` | Component locations. |
-| `q.slot.*` | Slot occupants and slot occupants by host. |
-| `q.player.*` | Player order, next player, resources, affordability. |
-
-Prefer `q.card.get(cardId)` over parsing card ids. Runtime card data already includes `cardType`, name, text, and properties.
-
-## Write with ops
-
-`ops` is a typed namespace of curried state writers. Compose ops with `pipe`:
-
-```ts
-return accept(
-  pipe(
-    state,
-    ops.spendResources({ playerId, amounts: { coin: 2 } }),
-    ops.dealCardsToPlayerZone({
-      fromZoneId: "market",
-      playerId,
-      toZoneId: "hand",
-      count: 1,
-    }),
-    ops.patchPhaseState({ step: "main" }),
-  ),
-);
-```
-
-Common groups:
-
-| Operation family | Examples |
-| --- | --- |
-| Flow | `setActivePlayers`, `advanceActivePlayer`. |
-| Authored state | `patchPublicState`, `patchHiddenState`, `patchPlayerPrivateState`, `patchPhaseState`. |
-| Zones/cards | `addCardToSharedZone`, `moveCardBetweenSharedZones`, `moveCardFromPlayerZoneToSharedZone`, `dealCardsToPlayerZone`. |
-| Board/components | `moveComponentToSpace`, `moveComponentToContainer`, `moveComponentToEdge`, `moveComponentToVertex`. |
-| Resources | `addResources`, `spendResources`, `transferResources`, `setResource`. |
-
-Ops preserve the narrowed phase-state type through `pipe`.
-
-## Author helper pattern
-
-Game-specific helpers should accept `ops` or `q` as arguments:
-
-```ts
-export function incrementScore(ops: Ops, playerId: PlayerId): Op<GameState> {
-  return ops.patchPublicState((prev) => ({
-    ...prev,
-    scores: {
-      ...prev.scores,
-      [playerId]: (prev.scores[playerId] ?? 0) + 1,
-    },
-  }));
-}
-```
-
-This keeps helper code testable and tied to the same injected runtime surface as reducer callbacks.
-
-## Validation before writes
-
-Some ops throw if the write is invalid. For example, `ops.spendResources` requires the player to afford the full cost.
-
-Check business rules in `validate`:
-
-```ts
-validate({ input, q }) {
-  if (!q.player.canAfford(input.playerId, COST)) {
-    return { errorCode: "INSUFFICIENT_RESOURCES" };
-  }
-  return null;
-}
-```
-
-Then apply the write in `reduce`.

package/skills/dreamboard/references/testing-bases.md

@@ -1,147 +0,0 @@
-# Bases
-
-Define reusable starting states for scenario tests.
-
-A base is a deterministic starting state for scenarios. It chooses the seed,
-player count, optional setup profile, and setup actions that produce a reusable
-checkpoint.
-
-Bases live under `test/bases/*.base.ts` and are generated into
-`test/generated/base-states.generated.ts` by `dreamboard test generate`.
-
-## Basic base
-
-```ts
-import { defineBase } from "../testing-types";
-
-export default defineBase({
-  id: "initial-turn",
-  seed: 1337,
-  players: 4,
-  setup: async () => undefined,
-});
-```
-
-Fields:
-
-| Field | Required | Meaning |
-| --- | --- | --- |
-| `id` | Yes | Stable base id used by scenarios. |
-| `seed` | Yes unless inherited | Reducer seed for deterministic randomness. |
-| `players` | Yes unless inherited | Number of seats in the generated base. |
-| `setupProfileId` | No | Manifest setup profile to use before setup actions. |
-| `extends` | No | Parent base id to hydrate before this setup runs. |
-| `setup` | Yes | Async function that prepares the checkpoint. |
-
-A base without `extends` must declare both `seed` and `players`.
-
-## Setup actions
-
-Use `game.submit` with generated interaction ids and typed params:
-
-```ts
-export default defineBase({
-  id: "after-first-placement",
-  extends: "initial-turn",
-  setup: async ({ game, seat }) => {
-    await game.submit(seat(1), "placeThingCard", {
-      cardId: "a-diamond",
-      ringId: "ring-1",
-    });
-  },
-});
-```
-
-`game.submit` runs the same validation and reducer dispatch path as a scenario
-action. If setup fails, generation fails.
-
-## Seat helpers
-
-Use `seat(index)` for stable player references:
-
-```ts
-const firstPlayer = seat(0);
-const secondPlayer = seat(1);
-```
-
-`seat(index)` throws if the base has fewer players than requested. Prefer it to
-literal ids because player id literals are generated from the workspace
-manifest and player count.
-
-## Setup profiles
-
-Use `setupProfileId` when the manifest has named setup profiles:
-
-```ts
-export default defineBase({
-  id: "standard-opening",
-  seed: 2026,
-  players: 4,
-  setupProfileId: "standard",
-  setup: async () => undefined,
-});
-```
-
-When a base extends another base, the setup profile is inherited unless the
-child declares one. A child base cannot change the effective seed, player count,
-or setup profile from its generated parent artifact. If it does, the fingerprint
-check fails and you should model that as a separate root base.
-
-## Inherited bases
-
-Use `extends` to avoid rebuilding expensive checkpoints in every scenario:
-
-```ts
-export default defineBase({
-  id: "after-setup",
-  seed: 1337,
-  players: 4,
-  setup: async ({ game, seat }) => {
-    for (const step of SETUP_ORDER) {
-      await game.submit(seat(step.seat), "placeSetupMarker", {
-        vertexId: step.vertex,
-      });
-      await game.submit(seat(step.seat), "placeSetupPath", {
-        edgeId: step.edge,
-      });
-    }
-  },
-});
-```
-
-```ts
-export default defineBase({
-  id: "pending-trade",
-  extends: "after-setup",
-  setup: async ({ game, seat }) => {
-    await game.submit(seat(0), "rollDice");
-    await game.submit(seat(0), "offerTrade", {
-      targetPlayerId: seat(1),
-      give: { brick: 1 },
-      receive: { wool: 1 },
-    });
-  },
-});
-```
-
-Generation hydrates the parent snapshot, runs the child setup, and fingerprints
-the parent. If the parent changes, children become stale and must be
-regenerated.
-
-## What belongs in a base
-
-Good base setup:
-
-- opening state
-- post-setup state
-- pending prompt state shared by several scenarios
-- late-game state that would be noisy to replay inline
-
-Poor base setup:
-
-- a one-off action used by only one scenario
-- assertions
-- full playthroughs that hide the rule being tested
-- local mutation of generated state files
-
-Assertions belong in scenarios. Bases create state; scenarios prove behavior.