dreamboard 0.1.0

package/skills/dreamboard/references/api-reference.md

@@ -0,0 +1,193 @@
+# State & API Reference
+
+## Read APIs (`ctx.state.*`)
+
+### `state.player`
+
+| Method                                 | Returns       | Description                           |
+| -------------------------------------- | ------------- | ------------------------------------- |
+| `.getOrder()`                          | `PlayerId[]`  | All players in turn order             |
+| `.getCurrentIds()`                     | `PlayerId[]`  | Currently active player IDs           |
+| `.get(playerId)`                       | `Player`      | Player data: `{ id, name, score }`    |
+| `.getState(playerId)`                  | `PlayerState` | Player variables from manifest schema |
+| `.getHand(playerId, handId)`           | `CardId[]`    | Cards in a specific hand              |
+| `.getAllHands(playerId)`               | `CardId[]`    | All cards across all hands            |
+| `.isInHand(playerId, cardId, handId?)` | `boolean`     | Check if card is in hand              |
+| `.isActive(playerId)`                  | `boolean`     | Is player currently active            |
+
+### `state.deck`
+
+| Method                | Returns          | Description            |
+| --------------------- | ---------------- | ---------------------- |
+| `.getCards(deckId)`   | `CardId[]`       | Cards in a shared deck |
+| `.getTopCard(deckId)` | `CardId \| null` | Top card of deck       |
+
+### `state.card`
+
+| Method                           | Returns            | Description                                          |
+| -------------------------------- | ------------------ | ---------------------------------------------------- |
+| `.get(cardId)`                   | `Card`             | Full card data                                       |
+| `.getProperties(cardId)`         | Typed properties   | Card-specific props (rank, suit, etc.)               |
+| `.getLocation(cardId)`           | `Location`         | Where the card is (InHand, InDeck, InZone, Detached) |
+| `.getPlayedBy(cardId)`           | `PlayerId \| null` | Who played this card to a deck/zone                  |
+| `.getOwner(cardId)`              | `PlayerId \| null` | Card owner                                           |
+| `.isVisibleTo(cardId, playerId)` | `boolean`          | Visibility check                                     |
+| `.getOwnedBy(playerId)`          | `CardId[]`         | All cards owned by player                            |
+
+### `state.game`
+
+| Method               | Returns       | Description                           |
+| -------------------- | ------------- | ------------------------------------- |
+| `.getGlobalState()`  | `GlobalState` | Global variables from manifest schema |
+| `.getCurrentState()` | `StateName`   | Current state machine state           |
+
+## Mutation APIs (`ctx.apis.*`)
+
+### `apis.cardApi`
+
+| Method                                                                      | Description                    |
+| --------------------------------------------------------------------------- | ------------------------------ |
+| `.moveCardsFromHandToDeck(playerId, handId, cardIds, deckId)`               | Hand → Deck                    |
+| `.moveCardsFromHandToHand(fromPlayer, fromHand, toPlayer, toHand, cardIds)` | Hand → Hand                    |
+| `.moveCardsToPlayer(cardIds, toPlayerId, handId)`                           | Any → Hand                     |
+| `.flip(deckId, cardId)`                                                     | Flip card face up/down         |
+| `.detachCard(cardId)`                                                       | Remove card from all locations |
+| `.transferOwnership(cardId, toPlayer)`                                      | Change card owner              |
+
+#### Card movement semantics
+
+- `moveCardsFromHandToHand(fromPlayer, fromHand, toPlayer, toHand, cardIds)` is **additive** at destination.
+- Destination cards are preserved; moved cards are added to the destination hand.
+- This API does **not** replace/overwrite the destination hand.
+- For pass/rotate mechanics where each player should receive exactly one other player's hand, avoid in-place cyclic moves. Snapshot source hands first, then move via a temporary location (or other two-phase transfer pattern).
+
+### `apis.deckApi`
+
+| Method                                                        | Description               |
+| ------------------------------------------------------------- | ------------------------- |
+| `.moveCardsFromDeckToPlayer(deckId, playerId, handId, count)` | Deck → Hand (deal)        |
+| `.moveCardsFromDeckToDeck(fromDeckId, toDeckId)`              | Deck → Deck               |
+| `.shuffle(deckId)`                                            | Shuffle a deck            |
+| `.addCards(deckId, cardIds)`                                  | Add cards to a deck       |
+| `.removeCard(deckId, cardId)`                                 | Remove a card from a deck |
+
+### `apis.gameApi`
+
+| Method                             | Description                                    |
+| ---------------------------------- | ---------------------------------------------- |
+| `.setActivePlayers(playerIds)`     | Set who can act (use in ALL_PLAYERS `onEnter`) |
+| `.setNextPlayer(playerId)`         | Set single active player                       |
+| `.advanceTurn()`                   | Move to next player in order                   |
+| `.declareWinner(playerId, reason)` | Declare game winner                            |
+| `.endGame()`                       | End the game                                   |
+
+### `apis.globalStateApi`
+
+| Method                                | Description                  |
+| ------------------------------------- | ---------------------------- |
+| `.setGlobalState(newState)`           | Replace all global variables |
+| `.setPlayerState(playerId, newState)` | Replace a player's variables |
+
+### `apis.kvApi`
+
+Internal-only key-value store. **UI cannot access these values.**
+
+| Method             | Returns          | Description                         |
+| ------------------ | ---------------- | ----------------------------------- |
+| `.set(key, value)` | `KvSetResult`    | Store a JSON value                  |
+| `.get(key)`        | `KvGetResult`    | Read a value (`.success`, `.value`) |
+| `.delete(key)`     | `KvDeleteResult` | Remove a key                        |
+| `.has(key)`        | `boolean`        | Check existence                     |
+| `.keys()`          | `string[]`       | List all keys                       |
+
+### `apis.resourceApi`
+
+| Method                    | Description                |
+| ------------------------- | -------------------------- |
+| `.add(playerId, cost)`    | Give resources to player   |
+| `.deduct(playerId, cost)` | Take resources from player |
+
+### `apis.dieApi`
+
+| Method                     | Description               |
+| -------------------------- | ------------------------- |
+| `.roll(dieId)`             | Roll a die                |
+| `.setValue(dieId, value?)` | Set die to specific value |
+
+## Typed KV Store
+
+Use `createTypedKv` from `sdk/stateApi.js` for type-safe KV access:
+
+```typescript
+import { createTypedKv } from "../sdk/stateApi.js";
+
+interface MyKv {
+  playersActed: PlayerId[];
+  roundData: { scores: number[] };
+}
+
+const kv = createTypedKv<MyKv>(apis.kvApi);
+kv.set("playersActed", ["player-1"]); // Type-checked key and value
+const acted = kv.get("playersActed"); // PlayerId[] | null
+kv.has("playersActed"); // boolean
+kv.delete("playersActed"); // boolean (existed)
+```
+
+## Card `playedBy` Tracking
+
+When cards move from a Hand to a Deck via `moveCardsFromHandToDeck()`, the engine automatically records `playedBy` on each card:
+
+```typescript
+// Move card from player's hand to a shared deck
+apis.cardApi.moveCardsFromHandToDeck(
+  playerId,
+  "main-hand",
+  [cardId],
+  "play-area",
+);
+
+// Later, check who played a specific card
+const whoPlayed = state.card.getPlayedBy(cardId); // PlayerId | null
+```
+
+## Location Type
+
+Cards have a location discriminated union:
+
+```typescript
+type Location =
+  | { type: "Detached" }
+  | {
+      type: "InDeck";
+      deckId: DeckId;
+      playedBy: PlayerId | null;
+      position: number | null;
+    }
+  | {
+      type: "InHand";
+      handId: HandId;
+      playerId: PlayerId;
+      position: number | null;
+    }
+  | {
+      type: "InZone";
+      zoneId: string;
+      playedBy: PlayerId | null;
+      position: number | null;
+    };
+```
+
+## Validation Helpers
+
+```typescript
+import { validationSuccess, validationError } from "../sdk/validation.js";
+
+// Valid action
+return validationSuccess();
+
+// Invalid action — errorCode should be kebab-case
+return validationError(
+  "must-play-valid-combination",
+  "You must play a valid card combination",
+);
+```

package/skills/dreamboard/references/app-best-practices.md

@@ -0,0 +1,86 @@
+# App Best Practices
+
+Best practices for working on `app/phases/*.ts` — the server-side game logic.
+
+## Before writing any code
+
+1. **Read the manifest** — understand all decks, hands, zones, resources, state machine states, and card types from `shared/manifest.d.ts`.
+2. **Read all existing phases** — read every file in `app/phases/` to understand the current flow.
+3. **Read the types** — review `app/sdk/types.d.ts`, `app/sdk/phaseHandlers.ts`, and `app/sdk/state.d.ts` for the full API surface.
+
+## Core principles
+
+1. **Authoritative script** — the app script is the source of truth for a multiplayer game. All mutations must go through APIs; never assume the UI tracks state.
+2. **Optimistic results** — use the data returned by mutation APIs within the same transaction. `state.*` reads may be stale until the next call.
+3. **Active vs next players** — use `setActivePlayers()` for simultaneous phases (ALL_PLAYERS); use `setNextPlayer()` for turn-based phases (SINGLE_PLAYER).
+4. **Card movement guardrail** — every card location change must use a move API. Never assume the UI or staging moved cards.
+5. **Manifest alignment** — use deck/hand/zone IDs exactly as defined in `shared/manifest.d.ts`. Do not invent new identifiers.
+6. **KV is internal** — `kvApi` is invisible to the UI. Pass data to UI via `getUIArgs()`, `globalStateApi`, or `playerStateApi`.
+7. **Preserve player-visible outcomes** — if an AUTO phase resolves a round or a reveal, keep the round-result information in state long enough for the next player-visible phase to render it.
+
+## Validation
+
+- Always implement `validateAction` for SINGLE_PLAYER and ALL_PLAYERS phases.
+- Return `validationSuccess()` for valid actions.
+- Return `validationError(code, message)` for invalid actions. Codes should be kebab-case (e.g., `'must-play-valid-combination'`).
+
+## UIArgs contract
+
+- Define UIArgs interfaces in `shared/ui-args.ts` to specify what data flows from app to UI.
+- Implement `getUIArgs(ctx, playerId)` in each player-facing phase to return the data the UI needs.
+- UIArgs should be minimal — only pass what the UI actually uses.
+- Avoid passing raw card IDs when you can pass computed values (e.g., `canPlayCard: boolean` instead of making the UI recompute).
+
+## Array and type safety
+
+- Check array length before indexing. Never assume arrays are non-empty.
+- Use guards from `app/generated/guards.ts` via `../generated/guards` for ID type assertions.
+- Never cast to `any` — always work with the generated types.
+
+## Logging
+
+- Log key actions with concise payloads (IDs and counts), not full arrays.
+- Use `ctx.logger` for structured logging.
+
+## Common patterns
+
+### Typed KV store
+
+```typescript
+import { createTypedKv } from "../sdk/stateApi.js";
+
+interface PhaseKv {
+  playersActed: PlayerId[];
+  roundNumber: number;
+}
+
+const kv = createTypedKv<PhaseKv>(apis.kvApi);
+kv.set("playersActed", []);
+const acted = kv.get("playersActed"); // PlayerId[] | null
+```
+
+### Card playedBy tracking
+
+```typescript
+// Cards moved via moveCardsFromHandToDeck automatically track playedBy
+apis.cardApi.moveCardsFromHandToDeck(
+  playerId,
+  "main-hand",
+  [cardId],
+  "play-area",
+);
+const whoPlayed = state.card.getPlayedBy(cardId); // PlayerId | null
+```
+
+### Turn advancement
+
+```typescript
+// In onAfterAction for SINGLE_PLAYER phases
+onAfterAction(ctx, playerId, actionType) {
+  ctx.apis.gameApi.advanceTurn();
+},
+```
+
+### ALL_PLAYERS tracking
+
+See [all-players-tracking.md](all-players-tracking.md) for the recommended `ctx.phase` tracking pattern.

package/skills/dreamboard/references/hands-vs-decks.md

@@ -0,0 +1,86 @@
+# Hands vs Decks
+
+The framework distinguishes between **Hands** and **Decks**. Confusing them causes silent bugs.
+
+## Definitions
+
+| Concept  | Manifest key                  | Type ID  | Access API                               | Description                                                  |
+| -------- | ----------------------------- | -------- | ---------------------------------------- | ------------------------------------------------------------ |
+| **Hand** | `playerHandDefinitions`       | `HandId` | `state.player.getHand(playerId, handId)` | Cards owned by a specific player. Per-player.                |
+| **Deck** | `components` (type: `"deck"`) | `DeckId` | `state.deck.getCards(deckId)`            | Shared card piles (draw pile, discard, battle zone). Global. |
+
+## Key rule
+
+A player's collection of cards is always a **Hand** (`HandId`), even if the real-world game calls it a "deck."
+
+For example, in the War card game, each player's face-down pile is called a "deck" in real life, but in the framework it's defined as a **Hand** with id `"player-deck"` under `playerHandDefinitions`.
+
+## Manifest Example (War card game)
+
+```json
+{
+  "components": [
+    { "type": "deck", "id": "main-deck", "name": "Main Deck" },
+    { "type": "deck", "id": "battle-zone", "name": "Battle Zone" },
+    { "type": "deck", "id": "war-pile", "name": "War Pile" }
+  ],
+  "playerHandDefinitions": [
+    {
+      "id": "player-deck",
+      "displayName": "Your Deck",
+      "visibility": "ownerOnly"
+    },
+    { "id": "won-pile", "displayName": "Won Cards", "visibility": "ownerOnly" }
+  ]
+}
+```
+
+- `"player-deck"` → **HandId** (per-player) → `state.player.getHand(playerId, "player-deck")`
+- `"battle-zone"` → **DeckId** (shared) → `state.deck.getCards("battle-zone")`
+- `"war-pile"` → **DeckId** (shared) → `state.deck.getCards("war-pile")`
+
+## Moving Cards
+
+```typescript
+// Hand → Deck (player plays card to shared area)
+apis.cardApi.moveCardsFromHandToDeck(playerId, handId, cardIds, deckId);
+
+// Deck → Hand (deal from shared pile to player)
+apis.deckApi.moveCardsFromDeckToPlayer(deckId, playerId, handId, count);
+
+// Hand → Hand (pass cards between players)
+apis.cardApi.moveCardsFromHandToHand(
+  fromPlayer,
+  fromHand,
+  toPlayer,
+  toHand,
+  cardIds,
+);
+
+// Deck → Deck (move all cards between shared piles)
+apis.deckApi.moveCardsFromDeckToDeck(fromDeckId, toDeckId);
+
+// Any card → Hand (move specific cards to a player)
+apis.cardApi.moveCardsToPlayer(cardIds, toPlayerId, handId);
+```
+
+## Hand Passing: Anti-Pattern vs Safe Pattern
+
+`moveCardsFromHandToHand` appends to destination. That makes in-place cyclic passing unsafe.
+
+### Anti-pattern (in-place cyclic pass)
+
+```typescript
+for (let i = 0; i < order.length; i++) {
+  const fromPlayer = order[i];
+  const toPlayer = order[(i + 1) % order.length];
+  const cardIds = state.player.getHand(fromPlayer, "hand");
+  apis.cardApi.moveCardsFromHandToHand(
+    fromPlayer,
+    "hand",
+    toPlayer,
+    "hand",
+    cardIds,
+  );
+}
+```