dreamboard 0.1.21 → 0.1.23

package/skills/dreamboard/references/game-contract.md

@@ -1,89 +0,0 @@
-# Game contract
-
-Use defineGameContract to bind generated manifest types to reducer state and phase names.
-
-`defineGameContract` is the reducer's type root. It connects the generated manifest contract to state schemas and the legal phase-name tuple.
-
-```ts
-import { z } from "zod";
-import { ids, manifestContract } from "../shared/manifest-contract";
-import {
-  defineGameContract,
-  sparseCounts,
-  type GameStateOf,
-} from "@dreamboard/app-sdk/reducer";
-
-export const gameContract = defineGameContract({
-  manifest: manifestContract,
-  phaseNames: ["setup", "playerTurn", "endGame"] as const,
-  state: {
-    public: z.object({
-      scores: sparseCounts(ids.playerId),
-      winnerPlayerId: ids.playerId.nullable(),
-    }),
-    private: z.object({}),
-    hidden: z.object({}),
-  },
-});
-
-export type GameContract = typeof gameContract;
-export type GameState = GameStateOf<GameContract>;
-```
-
-## Contract inputs
-
-| Field | Purpose |
-| --- | --- |
-| `manifest` | The generated `manifestContract` from `shared/manifest-contract`. |
-| `phaseNames` | A readonly tuple of every phase name the game can enter. |
-| `state.public` | State visible to all players and generally safe to project. |
-| `state.private` | Per-player secret state. |
-| `state.hidden` | Game-owned secret state. |
-
-`phaseNames` must match the keys registered in `defineGame({ phases })`. `defineGame` checks this at runtime, and TypeScript narrows phase names for `fx.transition(...)`, generated UI contracts, and generated tests.
-
-## Use manifest-backed schemas
-
-Prefer manifest-backed id schemas over plain strings:
-
-```ts
-const playerId = gameContract.schemas.playerId;
-const cardId = gameContract.schemas.cardId;
-```
-
-or import the generated `ids` namespace:
-
-```ts
-import { ids } from "../shared/manifest-contract";
-```
-
-This keeps state and interaction params anchored to the manifest. A raw `z.string()` for `playerId`, `cardId`, `zoneId`, or board ids removes the type signal the SDK is trying to preserve.
-
-## Sparse records
-
-For records keyed by manifest ids, prefer sparse helpers:
-
-```ts
-scores: sparseCounts(ids.playerId)
-roadsByEdgeId: sparseMap(ids.edgeId, roadSchema)
-```
-
-Sparse records model "some ids have entries" without forcing every possible generated id to exist in state. They also preserve the manifest id type.
-
-## What belongs in state
-
-State should contain mutable facts the reducer owns:
-
-- scores
-- pending decisions
-- current turn flags
-- player-specific secrets
-- derived-source data that changes over time
-
-State should not mirror table facts that are already represented by component location, zone contents, resource balances, or board occupancy. Read those through `q` and mutate them through `ops`.
-
-## Related pages
-
-- [Game definition](./game-definition.md) for assembling the contract into a runnable game.
-- [Table queries and ops](./table-queries-and-ops.md) for reading and writing table state.
-- [Derived values](./derived-values.md) for computed aggregates.

package/skills/dreamboard/references/game-definition.md

@@ -1,89 +0,0 @@
-# Game definition
-
-Use defineGame to assemble initial state, setup profiles, phases, views, and static views.
-
-`defineGame` is the assembly point for a reducer-native game. It registers the contract, initial state callbacks, setup profiles, phases, dynamic views, and optional static view.
-
-```ts
-import { defineGame } from "@dreamboard/app-sdk/reducer";
-import { gameContract } from "./game-contract";
-import { phases } from "./phases";
-import { playerView } from "./player-view";
-import { boardStatic } from "./board-static";
-import setupProfiles from "./setup-profiles";
-
-export default defineGame({
-  contract: gameContract,
-  initial: {
-    public: ({ playerIds }) => ({
-      scores: Object.fromEntries(playerIds.map((id) => [id, 0])),
-      winnerPlayerId: null,
-    }),
-    private: () => ({}),
-    hidden: () => ({}),
-  },
-  initialPhase: "setup",
-  setupProfiles,
-  phases,
-  views: {
-    player: playerView,
-  },
-  staticView: boardStatic,
-});
-```
-
-## Fields
-
-| Field | Purpose |
-| --- | --- |
-| `contract` | The `defineGameContract` result. |
-| `initial` | Optional callbacks for initial `public`, `private`, and `hidden` state. |
-| `initialPhase` | Phase to enter when setup does not override it. |
-| `setupProfiles` | Runtime setup presets, usually generated through `shared/manifest-contract`. |
-| `phases` | Phase registry keyed by phase name. |
-| `views` | Dynamic projections, commonly `{ player: playerView }`. |
-| `staticView` | Optional session-scoped immutable projection. |
-
-## Initial state
-
-Initial callbacks receive runtime context, including player ids, setup selection,
-and `rngSeed`. Use this when state depends on the actual player count or needs
-deterministic setup shuffles:
-
-```ts
-public: ({ playerIds, rngSeed, setup }) => ({
-  scores: Object.fromEntries(playerIds.map((playerId) => [playerId, 0])),
-  setupProfileId: setup.profileId,
-  terrainSeed: rngSeed,
-  winnerPlayerId: null,
-})
-```
-
-Do not hard-code the manifest-wide maximum player list when the session may use fewer players.
-
-## Phase registry
-
-Keep phase registry keys aligned with `gameContract.phaseNames`:
-
-```ts
-export const phases = {
-  setup,
-  playerTurn,
-  endGame,
-} satisfies PhaseMapOf<GameContract>;
-```
-
-`defineGame` validates the runtime shape as well, which catches dynamic phase registries that TypeScript cannot fully prove.
-
-## Generated consumers
-
-The generated UI and testing contracts inspect the `defineGame` result. Registered phases, interactions, card actions, stages, zones, and views become:
-
-- `PhaseName`
-- `InteractionId`
-- phase-qualified `InteractionKey`
-- surface-specific interaction unions
-- `GameView`
-- generated scenario interaction params
-
-If a generated UI or test type is stale, rerun `dreamboard sync` or `dreamboard test generate` before patching authored code.

package/skills/dreamboard/references/game-shell.md

@@ -1,80 +0,0 @@
-# UI primitives
-
-Compose generated Dreamboard UI primitives instead of using the old shell/surface API.
-
-Dreamboard UI now starts from generated, Radix-style primitives. The previous
-shell/render-map workflow has been replaced by component composition.
-
-## Scaffold default
-
-```tsx
-import { PromptInbox } from "@dreamboard/ui-contract";
-
-export default function App() {
-  return (
-    <main>
-      <PromptInbox.Root>
-        <PromptInbox.Empty>No available prompts.</PromptInbox.Empty>
-        <PromptInbox.Items />
-      </PromptInbox.Root>
-    </main>
-  );
-}
-```
-
-## Common primitives
-
-```tsx
-import { Interaction, PromptInbox, Zone } from "@dreamboard/ui-contract";
-```
-
-- `Interaction.Root` binds a descriptor by typed interaction key.
-- `Interaction.Submit` submits the current draft when required inputs are ready.
-- `Interaction.Input` and `Interaction.CardInput` mutate typed draft params.
-- `PromptInbox.Root`, `PromptInbox.Empty`, and `PromptInbox.Items` render
-  addressed prompt descriptors.
-- `Zone.Root`, `Zone.List`, and `Zone.Item` render card or collection zones.
-
-## Defaults
-
-If you want package-owned layout wrappers, import defaults explicitly:
-
-```tsx
-import { DefaultPromptInbox, GameLayout } from "@dreamboard/ui-sdk/defaults";
-
-export default function App() {
-  return (
-    <GameLayout.Root>
-      <GameLayout.Sidebar>
-        <DefaultPromptInbox />
-      </GameLayout.Sidebar>
-    </GameLayout.Root>
-  );
-}
-```
-
-Defaults are wrappers over primitives. You can replace any default with local
-React without changing reducer code.
-
-## Custom layouts
-
-Custom game UIs should own layout in React and CSS:
-
-```tsx
-<main className="game">
-  <section>
-    <Board />
-  </section>
-  <aside>
-    <Interaction.Root interaction="playerTurn.endTurn">
-      <Interaction.Submit>End turn</Interaction.Submit>
-    </Interaction.Root>
-    <PromptInbox.Root>
-      <PromptInbox.Items />
-    </PromptInbox.Root>
-  </aside>
-</main>
-```
-
-Reducers own availability, input shape, prompt recipients, target eligibility,
-and validation. React owns visual grouping, labels, layout, dialogs, and style.

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

@@ -1,33 +0,0 @@
-# Card zones
-
-Render card hands and card actions with generated Zone and Interaction primitives.
-
-Card hands and piles are just zones plus interactions. Use generated `Zone`
-primitives to provide card context and `Interaction.CardInput` to mutate the
-typed draft.
-
-```tsx
-import { Interaction, Zone } from "@dreamboard/ui-contract";
-import { Card } from "@dreamboard/ui-sdk";
-
-<Zone.Root zone="hand">
-  <Zone.List>
-    {view.hand.map((card) => (
-      <Zone.Item key={card.id} card={card.id}>
-        <Interaction.Root interaction="playerTurn.playCard">
-          <Interaction.CardInput input="cardId" card={card.id}>
-            <Card card={card} />
-          </Interaction.CardInput>
-        </Interaction.Root>
-      </Zone.Item>
-    ))}
-  </Zone.List>
-</Zone.Root>
-```
-
-For multi-card selection, `Interaction.CardInput` reads the reducer-projected
-selection metadata. It updates the draft until the count is ready, then
-`Interaction.Submit` can submit the interaction.
-
-Keep card faces local to the game. Keep card legality in reducer target
-collectors and card actions.

package/skills/dreamboard/references/index.md

@@ -1,112 +0,0 @@
-# Dreamboard
-
-An agent-native framework for prototyping board games.
-
-Dreamboard is a local-first authoring framework for building rule-enforced multiplayer board games. It is great for early-stage board game prototyping where rules are changing fast and components need to be added or removed from the game for quick iteration.
-You regenerate contracts with `dreamboard sync`, compile the authored head with `dreamboard compile`, and then run `dreamboard dev` to play locally while you iterate. The same compiled game can be opened from desktop browser or mobile phone.
-
-It achieves this by providing strong defaults, templates and components for common types for board games, but it is flexible enough for user to customize the game when needed.
-And because of the opinionated choice, it works very well with coding agents (Claude Code, Codex, Cursor and etc) when pair with the skill.
-
-## The authoring loop
-
-Most work happens in five files or folders:
-
-| Layer | File or folder | Owns |
-| --- | --- | --- |
-| Intent | `rule.md` | Human-readable game rules and design decisions. |
-| Topology | `manifest.ts` | Game components (e.g. boards, cards, zones, pieces, dice, resources) and player setup. |
-| Game | `app/` | Core logic for the game. |
-| Interface | `ui/` | React UI built from generated view and interaction contracts. |
-| Verification | `test/` | Game logic and UI tests by simulating real runs. |
-
-The CLI ties those files together:
-
-```bash
-dreamboard sync
-dreamboard compile
-dreamboard dev
-dreamboard test generate
-dreamboard test run
-```
-
-`sync` regenerates workspace contracts, `compile` builds the reducer bundle, `dev` runs a playable local session, and `test` replays scenarios against the same reducer definition.
-
-## A small example
-
-In `manifest.ts`, define the static table shape:
-
-```ts
-import { defineTopologyManifest } from "@dreamboard/sdk-types";
-
-export default defineTopologyManifest({
-  players: { minPlayers: 2, maxPlayers: 4, optimalPlayers: 3 },
-  cardSets: [
-    {
-      type: "manual",
-      id: "things",
-      name: "Things",
-      cardSchema: { properties: { label: { type: "string" } } },
-      cards: [
-        { type: "moon", name: "Moon", count: 1, properties: { label: "Moon" } },
-      ],
-    },
-  ],
-  zones: [
-    { id: "draw", name: "Draw", scope: "shared", allowedCardSetIds: ["things"] },
-    { id: "hand", name: "Hand", scope: "perPlayer", allowedCardSetIds: ["things"] },
-  ],
-  boards: [],
-});
-```
-
-In `app/game-contract.ts`, bind generated manifest types to reducer state:
-
-```ts
-import { z } from "zod";
-import { ids, manifestContract } from "../shared/manifest-contract";
-import { defineGameContract } from "@dreamboard/app-sdk/reducer";
-
-export const gameContract = defineGameContract({
-  manifest: manifestContract,
-  phaseNames: ["play"] as const,
-  state: {
-    public: z.object({ winnerPlayerId: ids.playerId.nullable() }) // state visible to all players,
-    private: z.object({}) // player state for each player,
-    hidden: z.object({}) // internal state for game - not visible,
-  },
-});
-```
-
-In a phase, declare typed interactions. The reducer stays authoritative; the UI receives typed descriptors and eligible targets from the same definition.
-
-```ts
-import { z } from "zod";
-import {
-  defineInteraction,
-  definePhase,
-  pipe,
-} from "@dreamboard/app-sdk/reducer";
-
-const play = definePhase<GameContract>()({
-  kind: "player",
-  state: z.object({}),
-  initialState: () => ({}),
-  actor: ({ state }) => state.flow.activePlayers,
-  interactions: {
-    endTurn: defineInteraction<GameContract>()({
-      inputs: {},
-      reduce({ state, accept, fx, ops }) {
-        return accept(pipe(state, ops.advanceActivePlayer())) // keep same state, advance to next player;
-      },
-    }),
-  },
-});
-```
-
-## What to read next
-
-- [Quickstart](./quickstart.md) gets a fresh workspace running.
-- [Workspace layout](./workspace-layout.md) explains generated and authored files.
-- [Core concepts](./core-concepts.md) defines the vocabulary used across the docs.
-- [Manifest](./manifest.md) and [Game contract](./game-contract.md) are the first two authoring references.

package/skills/dreamboard/references/inputs-and-targets.md

@@ -1,160 +0,0 @@
-# Inputs and targets
-
-Use collectors and target rules to type interaction params, project eligible targets, and validate submissions.
-
-Inputs define interaction params. Targets define finite eligibility. Together they are the canonical path for player choices.
-
-## Target rules
-
-A target rule starts from a candidate set and filters it through predicates.
-
-```ts
-export const buildPathTarget = boardTarget
-  .edge<GameState, EdgeId>("main-board")
-  .where({
-    id: "empty",
-    errorCode: "EDGE_OCCUPIED",
-    message: "That edge already has a path.",
-    test: ({ state, targetId }) => !state.publicState.pathsByEdgeId[targetId],
-  })
-  .where({
-    id: "connected",
-    errorCode: "NOT_CONNECTED",
-    message: "Path must connect to your network.",
-    test: ({ state, q, targetId, playerId }) =>
-      isConnectedPathTarget(state, q, targetId, playerId),
-  })
-  .build();
-```
-
-The built rule exposes:
-
-- `eligible(ctx)`
-- `validate(ctx, id)`
-- `isEligible(ctx, id)`
-- `bind(ctx)` for a state/player/query-scoped rule
-
-Use the same rule in collectors and any reducer code that needs to re-check a second optional target.
-
-## Board inputs
-
-```ts
-inputs: {
-  edgeId: boardInput.edge<GameState, EdgeId>({
-    target: buildPathTarget,
-  }),
-}
-```
-
-Board inputs support `vertex`, `edge`, `space`, and `tile`. They carry target
-metadata such as board id and target kind so generated board helpers can
-highlight eligible board elements.
-
-## Card inputs
-
-```ts
-const playableCardTarget = cardTarget
-  .zones<GameState, ThingsDeckCardId>(["things-hand"])
-  .build();
-
-inputs: {
-  cardId: cardInput<GameState, ThingsDeckCardId>({
-    target: playableCardTarget,
-  }),
-}
-```
-
-Card targets enumerate cards from a shared or per-player zone, then apply predicates.
-
-## Choice targets and prompts
-
-Finite prompt choices should use `choiceTarget` with `promptInput`.
-
-```ts
-const responseTarget = choiceTarget
-  .options<GameState, "accept" | "reject">([
-    { id: "accept", label: "Accept" },
-    { id: "reject", label: "Reject" },
-  ])
-  .build();
-
-inputs: {
-  response: promptInput({
-    schema: z.enum(["accept", "reject"]),
-    target: responseTarget,
-  }),
-}
-```
-
-The target provides labeled options for UI and server-side validation for submit.
-
-## Form inputs
-
-Use `formInput(schema)` for free-form Zod-backed params. Prefer domain-specific helpers when the UI or agents can benefit from constraints:
-
-```ts
-formInput.choice<ResourceId>({ choices: RESOURCE_CHOICES })
-formInput.choiceList<PlayerId>({ choices: PLAYER_CHOICES, min: 1 })
-formInput.number({ min: 0, max: ({ q, playerId }) => q.player.resource(playerId, "coin") })
-formInput.resourceMap({ resources: [{ resourceId: "coin", max: 3 }] })
-formInput.resourceChoices({ decorate: ({ resourceId }) => ({ badge: resourceId }) })
-```
-
-Free-form schemas are valid, but they are opaque to automated UI and bot flows.
-
-Use `defaultValue` when a form control should start with a real selection or value:
-
-```ts
-inputs: {
-  giveResource: formInput.choice<ResourceId>({
-    choices: RESOURCE_CHOICES,
-    defaultValue: resources.lumber,
-  }),
-}
-```
-
-Defaults are not requiredness flags. `formInput.choice(...)` is already required unless its schema is optional or nullable. Defaults are projected to UI descriptors, applied by generated client schemas, and exposed through `handle.values` so custom renderers can read the effective draft without local fallback casts. `handle.draft` remains partial because it is still the raw in-progress draft.
-
-## Multi-select collectors
-
-Wrap a target collector with `many(...)` when one interaction needs several
-values from the same target domain:
-
-```ts
-inputs: {
-  cardIds: many(cardInput<GameState, CardId>({ target: playableCardTarget }), {
-    min: 1,
-    max: 3,
-    distinct: true,
-  }),
-},
-commit: { mode: "manual" },
-```
-
-`many(...)` supports `{ count }` or `{ min, max, distinct }`. It cannot wrap
-`rngInput` collectors, and it always represents a manual draft selection: the
-player picks a set, then submits explicitly.
-
-## Engine-sampled inputs
-
-`rngInput.*` collectors are sampled by the trusted engine on submit. Clients do not supply these fields.
-
-```ts
-inputs: {
-  dice: rngInput.d6(2),
-},
-reduce({ input }) {
-  const values = input.params.dice.values;
-}
-```
-
-Use `rngInput` when the random result belongs to one interaction. Use [Effects](./effects.md) when randomness should be queued as an engine instruction.
-
-## One source of truth
-
-Do not duplicate eligibility in the UI. The target rule should be the shared source for:
-
-- projected eligible targets
-- submit validation
-- reducer business logic that needs the same predicate
-- tests