dreamboard 0.1.7 → 0.1.8

package/skills/dreamboard/references/board-topology.md

@@ -0,0 +1,443 @@
+# Board topology
+
+Author hex and square boards with shared reducer and UI topology primitives.
+
+Use tiled boards when your game has stable spaces plus meaningful borders or
+corners.
+
+Dreamboard currently supports two fixed-topology tiled layouts:
+
+- `layout: "hex"` for axial hex maps
+- `layout: "square"` for row and column grids
+
+Keep `layout: "generic"` for authored graphs that are not tile-based, such as
+tracks, networks, or map nodes.
+
+It is normal for one manifest to mix these layouts. For example, a game can use
+one shared generic market board, one shared hex frontier map, and one
+per-player square mat without splitting that coverage across multiple
+workspaces.
+
+The generated manifest contract now preserves that mixed topology directly with
+template-level literals plus board-scoped edge and vertex helpers:
+
+{/* Generated from examples/board-contract-lab/app/authoring-benchmark-typing-smoke.ts (tiled-board-helpers) */}
+
+```ts
+const playerMatId = boardHelpers.boardIdForPlayer("player-mat", "player-1");
+const hexBoardIds = boardHelpers.boardIdsForLayout("hex");
+const frontierRouteId = boardHelpers.edgeIds("frontier-map", "ferry-route")[0]!;
+const frontierCheckpointId = boardHelpers.vertexIds(
+  "frontier-map",
+  "checkpoint",
+)[0]!;
+const marketTemplateBoards =
+  boardHelpers.boardBaseIdsForTemplate("market-template");
+const playerMatTemplateLayout = boardHelpers.boardTemplateLayout(
+  "player-mat-template",
+);
+//
+```
+
+## What lives where
+
+Put immutable topology in the manifest:
+
+- spaces and their coordinates
+- optional authored edge and vertex metadata
+- authored containers and extra relations
+
+Put mutable gameplay state in reducer state:
+
+- ownership keyed by `spaceId`, `edgeId`, or `vertexId`
+- placed tiles, markers, units, or hazards
+- highlights, legal targets, and temporary UI state
+
+That split keeps the board reusable across different games and avoids treating
+manifest topology as a mutable gameplay store.
+
+## Fixed-topology constraint
+
+Hex and square boards in this release are fixed once the session starts.
+
+- Terraforming Mars fits this model: spaces stay fixed while ownership and tile
+  state change.
+- Gloomhaven fits this model: spaces stay fixed while units move and range is
+  recalculated.
+- Cascadia fits this model when the habitat map is pre-authored and scoring
+  reads adjacency from the fixed board.
+
+Carcassonne-style board growth is not part of this release. Treat that as a
+future topology adapter rather than part of the current `square` layout.
+
+## Shared topology vocabulary
+
+Reducer helpers and UI hooks use the same terms:
+
+| Term        | Meaning                                               |
+| ----------- | ----------------------------------------------------- |
+| `space`     | One tile or cell on the board                         |
+| `edge`      | One border shared by one or two spaces                |
+| `vertex`    | One corner touched by one to four spaces              |
+| `adjacent`  | The default movement or scoring graph for a layout    |
+| `incident`  | Edges touching a vertex, or vertices touching an edge |
+| `occupancy` | Components currently on a space, edge, or vertex      |
+
+Reducer-side board helpers are covered in [Table queries and ops](./table-queries-and-ops.md).
+UI-side board rendering is covered in [Board targets](./board-surfaces.md)
+and [UI components](./ui-components.md).
+
+## Choosing a layout
+
+| Layout    | Use it for                                            | Default adjacency                  |
+| --------- | ----------------------------------------------------- | ---------------------------------- |
+| `generic` | Tracks, networks, arbitrary relation graphs           | Whatever you author in `relations` |
+| `hex`     | Terraforming Mars, Gloomhaven, Cascadia, wargame maps | Derived hex adjacency              |
+| `square`  | Chess, Checkers, Onitama, fixed tile grids            | Orthogonal 4-way adjacency         |
+
+Square boards can still use diagonal logic. The reducer and UI helpers expose
+square-specific variants for diagonal neighbors and Chebyshev distance.
+
+## Reducer state pattern
+
+Store dynamic tiled state in plain overlay maps keyed by stable location IDs.
+
+```ts
+import { z } from "zod";
+import type {
+  TiledEdgeMap,
+  TiledSpaceMap,
+  TiledVertexMap,
+} from "@dreamboard/app-sdk/reducer";
+import { ids } from "../shared/manifest-contract";
+
+const publicState = z.object({
+  ownershipBySpaceId: z.partialRecord(ids.spaceId, ids.playerId).default({}),
+  effectByEdgeId: z.partialRecord(ids.edgeId, z.string()).default({}),
+  markerByVertexId: z
+    .partialRecord(
+      ids.vertexId,
+      z.object({
+        ownerId: ids.playerId,
+        kind: z.string(),
+      }),
+    )
+    .default({}),
+});
+
+type OwnershipBySpaceId = TiledSpaceMap<
+  typeof manifestContract.table,
+  "mars",
+  string
+>;
+type EffectByEdgeId = TiledEdgeMap<
+  typeof manifestContract.table,
+  "arena",
+  string
+>;
+type MarkerByVertexId = TiledVertexMap<
+  typeof manifestContract.table,
+  "arena",
+  { ownerId: string; kind: string }
+>;
+```
+
+Use `z.partialRecord(...)` for mutable tiled overlays. Runtime gameplay state is
+usually sparse, so empty-object initialization should compile and missing keys
+should mean "nothing placed here yet".
+
+Use this pattern for:
+
+- Terraforming Mars: `ownershipBySpaceId`, placed tile type, adjacency-bonus flags
+- Gloomhaven: movement blockers by edge, trap markers by vertex, units keyed by
+  space
+- Cascadia: adjacency-driven scoring keyed by placed habitat or wildlife tiles
+
+## Projecting UI-ready boards
+
+Reducer views should join immutable topology with mutable overlay state before
+rendering. Destructure the injected `q` inside `project({ state, playerId, q })`
+instead of constructing a fresh query from state.
+
+```ts
+import { defineView } from "@dreamboard/app-sdk/reducer";
+import type { GameContract } from "./game-contract";
+
+export const playerView = defineView<GameContract>()({
+  project({ state, q }) {
+    const board = q.board.tiled("arena");
+
+    return {
+      boardId: board.id,
+      layout: board.layout,
+      spaces: Object.values(board.spaces).map((space) => ({
+        ...space,
+        ownerId: state.publicState.ownershipBySpaceId[space.id] ?? null,
+        edgeIds: q.board.spaceEdges(board.id, space.id),
+        vertexIds: q.board.spaceVertices(board.id, space.id),
+      })),
+      legalEdgeIds: state.publicState.legalEdgeIds,
+      legalVertexIds: state.publicState.legalVertexIds,
+    };
+  },
+});
+```
+
+Keep canonical legality and scoring in reducer code. The UI should consume a
+projected board view plus simple highlight or legal-target sets.
+
+## Board shape and traversal
+
+- `board.spaces` is an ID-keyed record.
+- `board.edges` is an array of edge records.
+- `board.vertices` is an array of vertex records.
+
+<Warning>
+  Do not use `Object.keys(board.edges)` or `Object.keys(board.vertices)` to
+  discover runtime IDs. Those expressions return array indexes, not edge or
+  vertex IDs.
+</Warning>
+
+Use reducer-native query helpers when you need topology traversal:
+
+- `q.board.spaceEdges(boardId, spaceId)`
+- `q.board.spaceVertices(boardId, spaceId)`
+- `q.board.incidentEdges(boardId, vertexId)`
+- `q.board.incidentVertices(boardId, edgeId)`
+
+`incidentEdges(...)` and `incidentVertices(...)` are geometry helpers. They
+return all tiled edges or vertices that share the same incident spaces as the
+input location. They do not apply gameplay-specific filters such as road
+ownership or blocked-path rules.
+
+## Wiring the UI
+
+Use one of the layout-specific renderers:
+
+- `HexGrid` for hex spaces, edges, and vertices
+- `SquareGrid` for square cells, edges, and vertices
+
+Use the headless topology hooks when the UI needs geometry-aware logic:
+
+- `useBoardTopology(...)` for shared tiled queries
+- `useHexBoard(...)` for hex-specific coordinate helpers
+- `useSquareBoard(...)` for square-specific neighbor and distance variants
+
+```tsx
+import { HexGrid, SquareGrid, useBoardTopology, useSquareBoard } from "@dreamboard/ui-sdk";
+
+function ArenaBoard({ board, onEdgeClick, onVertexClick }) {
+  const topology = useSquareBoard(board);
+
+  return (
+    <SquareGrid
+      board={board}
+      interactiveEdges={{ selectTargetId: onEdgeClick }}
+      interactiveVertices={{ selectTargetId: onVertexClick }}
+      renderCell={(row, col) => {
+        const cell = topology.getCellAt(row, col);
+        return <Cell ownerId={cell?.owner ?? null} />;
+      }}
+      renderPiece={(piece) => <Piece piece={piece} />}
+    />
+  );
+}
+```
+
+This keeps interactivity consistent across layouts. Authors do not need to
+re-derive borders, corners, or adjacency in UI code.
+
+Project the whole tiled board record into the reducer view. Then keep
+game-specific legality beside it:
+
+```ts
+project({ state, q }) {
+  return {
+    board: q.board.tiled("arena"),
+    legalEdgeIds: state.publicState.legalEdgeIds,
+    legalVertexIds: state.publicState.legalVertexIds,
+  };
+}
+```
+
+Use this rule when deciding what to expose:
+
+- `spaces` are enough for tile or cell rendering only
+- `edges` are required when the UI should render or interact with borders
+- `vertices` are required when the UI should render or interact with corners
+
+For example, a route-building board view should project all three so the UI can
+render paths and markers and also expose placement targets.
+
+The important reducer-native detail is that target-layer IDs keep the board's
+exact runtime types. If the reducer view projects typed `edge.id` and
+`vertex.id` values, `board={board}` preserves those same ids through
+`selectTargetId` instead of forcing the UI to remap topology ids by hand.
+
+## Runtime IDs
+
+Hex and square edge and vertex IDs are derived runtime IDs based on authored
+space topology.
+
+- author spaces in the manifest
+- optionally attach authored edge and vertex metadata by `ref.spaces`
+- read the runtime `edgeId` and `vertexId` values from reducer helpers,
+  `boardHelpers.edgeIds(...)`, `boardHelpers.vertexIds(...)`,
+  `boardHelpers.boardIdForPlayer(...)`, or the projected board view
+- use those IDs as keys in reducer state and as click targets in the UI
+
+<Warning>
+  Do not hardcode the derived string format in app code. Read the runtime
+  `edgeId` and `vertexId` values from the helpers and projected board view
+  above instead.
+</Warning>
+
+## Valid and invalid tiled refs
+
+Author edge and vertex refs with real shared geometry, not just “nearby”
+spaces. These examples show the difference.
+
+### Square edge refs
+
+Valid square edge ref: the two cells share one border.
+
+```ts
+{
+  layout: "square",
+  spaces: [
+    { id: "a1", row: 0, col: 0 },
+    { id: "a2", row: 0, col: 1 },
+  ],
+  edges: [
+    { ref: { spaces: ["a1", "a2"] }, typeId: "road" },
+  ],
+}
+```
+
+Invalid square edge ref: diagonal cells do not share an edge.
+
+```ts
+{
+  layout: "square",
+  spaces: [
+    { id: "a1", row: 0, col: 0 },
+    { id: "b2", row: 1, col: 1 },
+  ],
+  edges: [
+    { ref: { spaces: ["a1", "b2"] }, typeId: "road" },
+  ],
+}
+```
+
+Why invalid: `a1` and `b2` only meet at a corner, so this must be a vertex ref
+instead of an edge ref.
+
+### Square vertex refs
+
+Valid square vertex ref: the cells resolve to one shared corner.
+
+```ts
+{
+  layout: "square",
+  spaces: [
+    { id: "a1", row: 0, col: 0 },
+    { id: "a2", row: 0, col: 1 },
+    { id: "b1", row: 1, col: 0 },
+    { id: "b2", row: 1, col: 1 },
+  ],
+  vertices: [
+    { ref: { spaces: ["a1", "a2", "b1", "b2"] }, typeId: "tower" },
+  ],
+}
+```
+
+Invalid square vertex ref: the cells do not collapse to exactly one corner.
+
+```ts
+{
+  layout: "square",
+  spaces: [
+    { id: "a1", row: 0, col: 0 },
+    { id: "a2", row: 0, col: 1 },
+    { id: "c1", row: 2, col: 0 },
+  ],
+  vertices: [
+    { ref: { spaces: ["a1", "a2", "c1"] }, typeId: "tower" },
+  ],
+}
+```
+
+Why invalid: those three cells do not touch the same corner, so the ref cannot
+resolve to one runtime vertex ID.
+
+### Hex edge refs
+
+Valid hex edge ref: the two hexes share one border.
+
+```ts
+{
+  layout: "hex",
+  spaces: [
+    { id: "hex-a", q: 0, r: 0 },
+    { id: "hex-b", q: 1, r: 0 },
+  ],
+  edges: [
+    { ref: { spaces: ["hex-a", "hex-b"] }, typeId: "road" },
+  ],
+}
+```
+
+Invalid hex edge ref: non-adjacent hexes do not form an edge.
+
+```ts
+{
+  layout: "hex",
+  spaces: [
+    { id: "hex-a", q: 0, r: 0 },
+    { id: "hex-c", q: 2, r: 0 },
+  ],
+  edges: [
+    { ref: { spaces: ["hex-a", "hex-c"] }, typeId: "road" },
+  ],
+}
+```
+
+Why invalid: `hex-a` and `hex-c` are separated by another hex, so there is no
+shared border to attach an edge to.
+
+### Hex vertex refs
+
+Valid hex vertex ref: the three hexes meet at one corner.
+
+```ts
+{
+  layout: "hex",
+  spaces: [
+    { id: "hex-a", q: 0, r: 0 },
+    { id: "hex-b", q: 1, r: 0 },
+    { id: "hex-c", q: 0, r: 1 },
+  ],
+  vertices: [
+    { ref: { spaces: ["hex-a", "hex-b", "hex-c"] }, typeId: "settlement" },
+  ],
+}
+```
+
+Invalid hex vertex ref: collinear hexes do not share a single corner.
+
+```ts
+{
+  layout: "hex",
+  spaces: [
+    { id: "hex-a", q: 0, r: 0 },
+    { id: "hex-b", q: 1, r: 0 },
+    { id: "hex-c", q: 2, r: 0 },
+  ],
+  vertices: [
+    { ref: { spaces: ["hex-a", "hex-b", "hex-c"] }, typeId: "settlement" },
+  ],
+}
+```
+
+Why invalid: those three hexes never meet at one point, so the ref fails
+validation instead of producing an ambiguous runtime vertex.

package/skills/dreamboard/references/boards-and-topology.md

@@ -0,0 +1,100 @@
+# Boards and topology
+
+Model generic, hex, and square boards with typed spaces, edges, vertices, containers, and board refs.
+
+Boards are manifest-defined topology. They can be generic, hex, or square, shared or per-player, inline or based on a template.
+
+## Board layouts
+
+| Layout | Use for |
+| --- | --- |
+| `generic` | Free-form spaces and relations, tracks, maps, abstract zones. |
+| `hex` | Hex grids with spaces, edges, and vertices. |
+| `square` | Square grids with rows, columns, spaces, edges, and vertices. |
+
+All layouts can have spaces and containers. Tiled layouts also expose typed edge and vertex ids.
+
+## Inline board
+
+```ts
+boards: [
+  {
+    id: "action-board",
+    name: "Action Board",
+    layout: "square",
+    scope: "shared",
+    spaces: [
+      { id: "plaza", row: 0, col: 0, typeId: "action" },
+    ],
+  },
+];
+```
+
+Use inline boards when a board appears once. Use templates when several board instances share topology.
+
+## Templates
+
+```ts
+boardTemplates: [
+  {
+    id: "market-template",
+    name: "Market Template",
+    layout: "generic",
+    spaces: [
+      { id: "auction", typeId: "action" },
+      { id: "harvest", typeId: "action" },
+    ],
+  },
+],
+boards: [
+  {
+    id: "market-board",
+    name: "Market Board",
+    templateId: "market-template",
+    layout: "generic",
+    scope: "shared",
+  },
+];
+```
+
+Template-backed boards still get their own board id. Reducer and UI code should address runtime board data by board id, not by template id.
+
+## Shared and per-player boards
+
+`scope: "shared"` creates one board instance for the session. `scope: "perPlayer"` creates one board per player.
+
+Use shared boards for central maps and markets. Use per-player boards for player mats, personal tracks, and private layouts.
+
+## Runtime board queries
+
+Inside reducer callbacks, views, derived values, and target rules, read board data through injected `q`:
+
+```ts
+const board = q.board.hex("island");
+const edge = q.board.edge("island", edgeId);
+const adjacent = q.board.incidentVertices("island", edgeId);
+```
+
+Use `q.board.get` for layout-agnostic access, `q.board.hex` / `q.board.square` for layout-specific topology, and traversal helpers such as `incidentEdges`, `incidentVertices`, `spaceEdges`, `spaceVertices`, and `squareNeighbors` for rules.
+
+## Static board projection
+
+Static board topology belongs in [Static views](./static-views.md), not in dynamic player views.
+
+```ts
+export const boardStatic = defineStaticView<GameContract>()({
+  project: ({ q }) => {
+    const board = q.board.hex("island");
+    return {
+      ...board,
+      portsByVertexId: computePorts(board),
+    };
+  },
+});
+```
+
+Keep game-specific decoration local, but use SDK static board queries for reusable topology access.
+
+## Deep topology reference
+
+For exact square/hex edge and vertex id rules, see [Board topology](./board-topology.md).

package/skills/dreamboard/references/card-actions.md

@@ -0,0 +1,107 @@
+# Card actions
+
+Use defineCardAction for first-class actions that play a card from a hand zone.
+
+Use `defineCardAction` when the player action starts from a concrete card in a hand or card zone: play an action card, reveal a tactic, discard a reaction, trigger a card ability.
+
+```ts
+import { cardTypes, zones } from "../shared/manifest-contract";
+
+const playBoost = defineCardAction<
+  GameContract,
+  typeof playerTurnPhaseStateSchema
+>()({
+  cardType: cardTypes.boost,
+  playFrom: zones.actionHand,
+  label: "Play boost",
+  step: "main",
+  inputs: {
+    selectedSpaceId: boardInput.space<GameState, SpaceId>({
+      target: selectableSpaceTarget,
+    }),
+    stealFromPlayerId: formInput(ids.playerId.nullable()),
+  },
+  rules: [
+    {
+      id: "can-play-action-card",
+      errorCode: "CARD_NOT_PLAYABLE",
+      validate: ({ state }) => validateCanPlayActionCard(state),
+    },
+  ],
+  reduce({ state, input, accept, ops }) {
+    return accept(
+      pipe(
+        state,
+        ops.moveCardFromPlayerZoneToSharedZone({
+          playerId: input.playerId,
+          fromZoneId: zones.actionHand,
+          toZoneId: zones.playedCards,
+          cardId: input.params.cardId,
+          playedBy: input.playerId,
+        }),
+        ops.patchPublicState({ selectedSpaceId: input.params.selectedSpaceId }),
+      ),
+    );
+  },
+});
+```
+
+## How it differs from defineInteraction
+
+`defineCardAction` supplies the card-specific contract:
+
+| Field | Meaning |
+| --- | --- |
+| `cardType` | Manifest card type that can trigger this action. |
+| `playFrom` | Manifest player zone id the card must be playable from. |
+| `inputs` | Additional params besides the selected card. |
+| `step` / `steps` | Optional phase-step gates, typed from `state.phase.step` when your phase state schema declares a string literal union. |
+| `rules` | Card-specific availability and validation, often shared across a family of cards. |
+| `cost` / `paramsSchema` / `commit` | Same interaction metadata as `defineInteraction`, when the card action needs affordability, cross-field params, or manual draft control. |
+| `reduce` | Receives `input.params.cardId` automatically. |
+
+The generated interaction contract treats card actions as card-anchored
+interactions. `Zone` plus `Interaction.CardInput` can show a playable card and
+collect additional inputs without each workspace inventing local card-action
+plumbing.
+
+Card actions are always card-anchored interactions. Use `defineInteraction` for
+non-card commands and group them visually in React.
+
+## Zone-backed rendering
+
+Declare the hand zone once in the phase:
+
+```ts
+zones: [zones.actionHand],
+cardActions: {
+  playBoost,
+  playDrawCards,
+  playBuildPath,
+},
+```
+
+The reducer projection is keyed by the manifest zone id, such as `action-hand`.
+Import `zones` and `cardTypes` from the generated manifest contract so authoring
+code uses typed handles instead of raw string ids. Cards come from the listed
+manifest player zone; playable descriptors are derived from `cardActions` whose
+`playFrom` matches that zone.
+
+## Validation
+
+Target validation still runs before authored rules. Use `rules` for
+card-specific business checks: once per turn, bought this turn, enough
+resources, correct phase step, or no pending trade.
+
+Move the card in `reduce`. `defineCardAction` makes the card id available; it does not decide whether the card should be discarded, trashed, returned, tucked, or left in play.
+
+## When to use defineInteraction instead
+
+Use `defineInteraction` when:
+
+- the action is not tied to a card instance
+- the player chooses from a board target, form, or panel button first
+- a prompt asks for a response
+- the card is only one optional input among several unrelated choices
+
+Use `defineCardAction` when the card is the object being played.