dreamboard 0.1.21 → 0.1.23

package/skills/dreamboard/references/testing.md

@@ -1,161 +0,0 @@
-# Testing overview
-
-Generate and run Dreamboard reducer-native tests.
-
-Dreamboard tests run authored scenarios against the
-same reducer contract that powers the game, using generated workspace types for
-player ids, interaction ids, params, phases, views, and assertion helpers.
-
-Use tests for repeatable gameplay coverage:
-
-- opening-state invariants
-- setup checkpoints reused by many scenarios
-- happy paths across a turn, round, or full game
-- rejection paths for illegal actors or params
-- prompt recipient and availability checks
-- UI component probes against reducer-projected plugin state
-
-## Workspace layout
-
-| Path | Ownership | Purpose |
-| --- | --- | --- |
-| `test/bases/*.base.ts` | Authored | Reusable seeded starting states via `defineBase`. |
-| `test/scenarios/*.scenario.ts` | Authored | Reducer-native scenario files via `defineScenario`. |
-| `test/ui/*.test.tsx` | Authored | Optional UI tests using `createTestRuntime`. |
-| `test/testing-types.ts` | Generated | Workspace-narrowed test import surface. |
-| `test/generated/*` | Generated | Base snapshots, testing contract, scenario manifest, projections, snapshots, and metadata. |
-
-Import test helpers from `../testing-types`. Do not import directly from
-`test/generated/*` and do not edit generated files by hand.
-
-## Command flow
-
-Generate or refresh reducer-native artifacts:
-
-```bash
-dreamboard test generate
-```
-
-Run all reducer scenarios:
-
-```bash
-dreamboard test run
-```
-
-Run one scenario file:
-
-```bash
-dreamboard test run --scenario test/scenarios/trade-full-lifecycle.scenario.ts
-```
-
-Refresh scenario snapshots while running:
-
-```bash
-dreamboard test run --update-snapshots
-```
-
-Public workspaces should normally omit `--runner`. The default runner is the
-reducer runner. Internal source-checkout lanes may also use `embedded` or
-`browser`, but those are parity lanes rather than the public authoring loop.
-
-Example workspaces may also expose package-local checks. Star Settlers, for
-example, uses `pnpm typecheck:test` for test TypeScript and `pnpm test:ui` for
-React UI probes under `test/ui`.
-
-## What generate does
-
-`dreamboard test generate`:
-
-1. Ensures `test/testing-types.ts` and `test/generated/testing-contract.ts`
-   exist and match the current workspace contract.
-2. Loads `test/bases/*.base.ts` and `test/scenarios/*.scenario.ts`.
-3. Validates that every scenario references an existing base.
-4. Executes base setup against the reducer to produce deterministic base
-   snapshots.
-5. Writes generated artifacts under `test/generated/`.
-
-Regenerate after changes that affect runtime or type shape:
-
-- `manifest.ts`
-- `app/game.ts`
-- phase files, interactions, card actions, targets, or views
-- setup profiles
-- generated `shared/generated/ui-contract.ts`
-- stale base fingerprints reported by `dreamboard test run`
-
-## What run does
-
-`dreamboard test run`:
-
-1. Ensures generated testing files exist.
-2. Loads bases, scenarios, generated base states, manifest, and game reducer.
-3. Checks generated base fingerprints against the current workspace.
-4. Starts each scenario from its base.
-5. Runs `when`.
-6. Checks optional `phase` and `stage`.
-7. Runs `then`.
-8. Prints one pass or fail line per scenario plus a summary.
-
-If the base artifact is stale, the runner fails before pretending the scenario
-is meaningful. Regenerate instead of debugging against an old snapshot.
-
-## Minimal base and scenario
-
-```ts
-// test/bases/initial-turn.base.ts
-import { defineBase } from "../testing-types";
-
-export default defineBase({
-  id: "initial-turn",
-  seed: 1337,
-  players: 4,
-  setup: async () => undefined,
-});
-```
-
-```ts
-// test/scenarios/smoke-initial-turn.scenario.ts
-import { defineScenario } from "../testing-types";
-
-export default defineScenario({
-  id: "smoke-initial-turn",
-  from: "initial-turn",
-  phase: "setup",
-  when: async () => undefined,
-  then: ({ state, interactions, expect, seat }) => {
-    expect(state()).toBe("setup");
-    expect(interactions(seat(0))).toHaveInteraction("placeSetupMarker");
-  },
-});
-```
-
-Use `seat(0)`, `seat(1)`, and `players()` instead of hard-coded `"player-1"`
-strings. This keeps tests portable across player counts and generated player id
-unions.
-
-## Recommended coverage
-
-Every game should have:
-
-- one opening-state scenario
-- one normal turn or round scenario
-- one scenario that crosses a phase boundary
-- one rejection scenario for out-of-turn or invalid params
-- one prompt recipient scenario if the game uses prompts
-- one setup-profile or setup-completion scenario when setup is non-trivial
-
-For larger games, create bases for expensive checkpoints such as post-setup,
-mid-game economy, pending trade, pending combat, or near-endgame. Do not make
-one scenario replay a full game just to test a late rule.
-
-## Split pages
-
-- [Bases](./testing-bases.md) explains seeded checkpoints and inheritance.
-- [Scenarios](./testing-scenarios.md) explains `defineScenario` and scenario
-  flow.
-- [Runtime assertions](./testing-runtime-assertions.md) lists context helpers
-  and matchers.
-- [UI tests](./testing-ui-tests.md) shows `createTestRuntime` with React
-  providers.
-- [Generated testing contracts](./testing-generated-contracts.md) explains
-  generated files and stale-artifact failures.

package/skills/dreamboard/references/ui-architecture.md

@@ -1,137 +0,0 @@
-# UI architecture
-
-Understand the generated UI contract, UI SDK, and host runtime boundaries.
-
-Dreamboard UI is reducer-driven and component-first. The reducer projects the
-current player's view and available interactions; React composes generated
-primitives, package defaults, and local visuals around those authoritative
-descriptors.
-
-Do not reimplement legality in React. UI code may choose layout, copy,
-highlights, and controls, but availability, eligible targets, prompt options,
-and submitted param shapes should come from authored reducer contracts and
-generated types.
-
-## Layers
-
-| Layer | Import path | Owns |
-| --- | --- | --- |
-| Workspace UI contract | `@dreamboard/ui-contract` | Typed `Interaction`, `Prompt`, `PromptInbox`, `Zone`, `Board`, generated hooks, interaction keys, input keys, zone ids, card ids, phase names, and board targets. |
-| UI SDK | `@dreamboard/ui-sdk` | Runtime providers, generic hooks, visual primitives such as `Card`, `HexGrid`, `ResourceCounter`, and advanced escape-hatch hooks. |
-| UI defaults | `@dreamboard/ui-sdk/defaults` | Styled wrappers over primitives such as `DefaultPromptInbox`, `DefaultInteractionList`, `DefaultZone`, and `GameLayout`. |
-| Host runtime | Provided by the dev/play host | Session state, state-sync snapshots, interaction submission, validation RPCs, player switching, history restore, and host-only feedback. |
-
-Most authored UI imports the generated contract first:
-
-```tsx
-import {
-  Interaction,
-  PromptInbox,
-  Zone,
-  useBoardInteractions,
-  useGameView,
-  useInteractionByKey,
-} from "@dreamboard/ui-contract";
-```
-
-Use `@dreamboard/ui-sdk` for framework primitives that are not
-workspace-specific:
-
-```tsx
-import { Card, HexGrid, ResourceCounter, ToastProvider } from "@dreamboard/ui-sdk";
-```
-
-`@dreamboard/ui-contract` is a generated workspace alias backed by
-`shared/generated/ui-contract.ts`, not a standalone npm package. The generated
-file augments `@dreamboard/ui-sdk`'s `DreamboardUIRegister`, calls
-`createDreamboardUI(uiContract)`, and exports typed primitives such as
-`Interaction`, `Prompt`, `PromptInbox`, `PromptDialogHost`, `PlayerRoster`,
-`Phase`, `Zone`, and `Board`.
-
-## Data flow
-
-1. Authoring files declare manifest objects, phases, interactions, inputs,
-   targets, card actions, and views.
-2. `dreamboard sync` generates workspace contracts, including
-   `@dreamboard/ui-contract`.
-3. The trusted bundle evaluates the current seat and projects descriptors into
-   plugin state.
-4. UI primitives read those descriptors and expose state through props,
-   contexts, `data-*` attributes, and typed handles.
-5. UI submits through `Interaction.Submit`, `Prompt.Option`,
-   `InteractionHandle`, or generated board target helpers.
-
-The descriptor is a behavior contract, not a presentation DSL. It carries ids,
-availability, unavailable reasons, input domains, target eligibility, prompt
-options, zone metadata, and phase metadata. Visual policy belongs in React/CSS
-or default wrappers.
-
-## Primitive scaffold
-
-```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>
-  );
-}
-```
-
-Use the same pattern for actions and zones:
-
-```tsx
-<Interaction.Root interaction="playerTurn.buyCard">
-  <Interaction.Label />
-  <Interaction.Submit>Buy</Interaction.Submit>
-</Interaction.Root>
-
-<Zone.Root zone="hand">
-  <Zone.List>
-    {view.hand.map((card) => (
-      <Zone.Item key={card.id} card={card.id}>
-        <Interaction.CardInput input="cardId" card={card.id}>
-          <Card card={card} />
-        </Interaction.CardInput>
-      </Zone.Item>
-    ))}
-  </Zone.List>
-</Zone.Root>
-```
-
-## Custom board escape hatch
-
-SVG or canvas-heavy boards can use generated `useBoardInteractions()` while the
-reducer still owns eligibility:
-
-```tsx
-const board = useBoardInteractions();
-
-<HexGrid
-  board={view.board}
-  interactiveVertices={board.targetLayers.vertex()}
-  interactiveEdges={board.targetLayers.edge()}
-  renderTile={(tile, geometry) => <polygon points={geometry.points()} />}
-  renderEdge={(edge) => <line />}
-  renderVertex={(vertex) => <circle /> /* sketch only */}
-/>;
-```
-
-## Boundaries
-
-| Put it here | Examples |
-| --- | --- |
-| Reducer authoring | Turn order, actor rules, prompt recipients, target eligibility, costs, validation, state transitions. |
-| Generated UI contract | Interaction keys, input names, prompt options, phase-qualified param types, zones, card ids, board target ids. |
-| Authored React UI | Layout, styling, board geometry, card faces, component composition, selected draft inputs. |
-| Host runtime | Player switching, session chrome, state-sync, submission transport, host-only notifications. |
-
-Do not mirror host-only concepts into authored reducer state just to make UI
-chrome easier. Do not copy target predicates into React just to enable or
-disable a board element. If React needs a highlight, expose it through a target
-collector or derived view.

package/skills/dreamboard/references/ui-components.md

@@ -1,34 +0,0 @@
-# UI components
-
-Generic presentational components available from @dreamboard/ui-sdk.
-
-Dreamboard ships generic presentational components in `@dreamboard/ui-sdk`.
-They are not game-specific; pair them with generated primitives from
-`@dreamboard/ui-contract` when behavior needs typed interactions.
-
-| Component | Use |
-| --- | --- |
-| `Card` | Render a card face from projected view data. |
-| `Hand` | Presentational card row/fan helper. |
-| `HexGrid` / `SquareGrid` | Board geometry renderers. |
-| `ResourceCounter` / `CostDisplay` | Resource and cost display. |
-| `DiceRoller` | Dice display plus optional roll action handle. |
-| `PlayerRoster` | Generated player roster primitive for player chrome. |
-| `GameEndDisplay` | End-of-game summary. |
-| `ToastProvider` | Local toast context for UI feedback. |
-
-Behavior comes from generated primitives:
-
-```tsx
-import { Interaction, Zone } from "@dreamboard/ui-contract";
-import { Card } from "@dreamboard/ui-sdk";
-
-<Zone.Item card={card.id}>
-  <Interaction.CardInput input="cardId" card={card.id}>
-    <Card card={card} />
-  </Interaction.CardInput>
-</Zone.Item>
-```
-
-Presentational components should render projected view data or interaction
-handles. They should not inspect reducer internals or recompute legality.

package/skills/dreamboard/references/views.md

@@ -1,72 +0,0 @@
-# Views
-
-Use defineView to project dynamic player-facing state for UI and clients.
-
-Views are the dynamic player-facing projection boundary. The UI reads a view; it should not inspect raw reducer state.
-
-```ts
-export const playerView = defineView<GameContract>()({
-  project({ state, playerId, q }) {
-    const scores = state.publicState.scores;
-    const handCards = q.zone.playerCards(playerId, "things-hand").map((cardId) => {
-      const card = q.card.get(cardId);
-      return {
-        id: cardId,
-        label: card.name ?? cardId,
-      };
-    });
-
-    return {
-      phase: state.flow.currentPhase,
-      myScore: scores[playerId] ?? 0,
-      scores,
-      handCards,
-      winnerPlayerId: state.publicState.winnerPlayerId,
-    };
-  },
-});
-```
-
-Register views in `defineGame`:
-
-```ts
-export default defineGame({
-  contract: gameContract,
-  phases,
-  views: {
-    player: playerView,
-  },
-});
-```
-
-The generated UI contract exposes the projected type as `GameView` and `InferView<"player">`.
-
-## What a view can read
-
-`project` receives:
-
-- `state`, including public/private/hidden/phase/table data as appropriate for the runtime projection
-- `playerId`
-- `q`, the typed table query namespace
-- `derived`, for memoized derived values
-- runtime context such as current phase, player order, active players, and setup
-
-Use `q` for table facts such as cards in a hand, board occupants, resource balances, and component locations.
-
-## What belongs in a view
-
-Views should shape data for UI consumption:
-
-- labels for cards or pieces
-- counts and summaries
-- player-specific hand information
-- current phase and step display data
-- safe public slices of score and winner state
-
-Views should not run rule validation or decide legal moves. The runtime projects interactions and eligible targets from reducer definitions.
-
-## Static vs dynamic
-
-Use `defineView` for data that can change during a session. Use [Static views](./static-views.md) for manifest-derived payloads that do not change after session initialization.
-
-Avoid putting large static topology in every dynamic view update.

package/skills/dreamboard/references/workspace-layout.md

@@ -1,136 +0,0 @@
-# Workspace layout
-
-Understand which Dreamboard workspace files are authored, generated, scaffold-owned, and runtime-facing.
-
-A Dreamboard workspace is split by ownership. Keep that split intact: edit authored source, regenerate generated contracts, and avoid patching files that say they are generated.
-
-## Main files
-
-| Path                     | Ownership            | Purpose                                                                                          |
-| ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------ |
-| `rule.md`                | Authored             | Human-readable rules, setup, turn flow, scoring, and edge cases.                                 |
-| `manifest.ts`            | Authored             | Static game topology: players, cards, zones, boards, pieces, dice, resources, setup options.     |
-| `app/game-contract.ts`   | Authored             | State schemas, phase-name tuple, and generated manifest contract binding.                        |
-| `app/game.ts`            | Authored             | Assembles the game with `defineGame`: initial state, phases, views, setup profiles, static view. |
-| `app/phases/`            | Authored             | Phase definitions, interactions, card actions, effects, stages, zones.                           |
-| `app/player-view.ts`     | Authored             | Dynamic player-facing projection with `defineView`.                                              |
-| `app/board-static.ts`    | Authored when needed | Session-scoped immutable projection with `defineStaticView`.                                     |
-| `app/derived.ts`         | Authored when needed | Pure reusable computations with `defineDerived`.                                                 |
-| `app/reducer-support.ts` | Authored             | Game-specific helper functions that accept injected `q` and `ops`.                               |
-| `ui/`                    | Authored             | React UI built from generated `@dreamboard/ui-contract` primitives and generic SDK visuals.      |
-| `test/bases/`            | Authored             | Reusable scenario starting states via `defineBase`.                                              |
-| `test/scenarios/`        | Authored             | Reducer-native scenarios via `defineScenario`.                                                   |
-
-## Recommended app structure
-
-Small games can stay flat:
-
-```txt
-app/
-  game-contract.ts
-  game.ts
-  derived.ts
-  reducer-support.ts
-  phases/
-    setup.ts
-    player-turn.ts
-```
-
-As the game grows, split by game concept instead of letting one phase file
-collect every rule:
-
-```txt
-app/
-  game-contract.ts       # schemas, phase names, exported state types
-  game.ts                # defineGame assembly
-  derived.ts             # defineDerived values
-  player-view.ts         # player-facing projection
-  reducer-support.ts     # small shared reducer plumbing
-  rules/                 # domain helpers once reducer-support grows
-    board.ts
-    resources.ts
-    scoring.ts
-  phases/
-    player-turn/
-      index.ts           # definePhase assembly only
-      turn-state.ts      # phase-local constants and types
-      action-rules.ts    # shared availability and validation rules
-      inputs.ts          # shared typed input helpers
-      build.ts           # build interactions
-      player-trade.ts    # trade interactions
-      tech-cards.ts      # card actions
-      end-turn.ts        # end-turn interaction
-```
-
-Use a phase folder when a phase has multiple action families, shared typed input
-helpers, card actions, or is roughly 250-300 lines. Keep
-`index.ts` as the table of contents: import interactions, card actions, and
-phase state, then register them with `definePhase`.
-
-## Generated files
-
-Generated files are there to make the authored surface strongly typed. Do not edit them directly.
-
-| Path                                 | Generated by               | Contains                                                                                          |
-| ------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------- |
-| `shared/manifest-contract.ts`        | `dreamboard sync`          | Literal ID unions, Zod ID schemas, runtime table types, setup profile helpers, manifest defaults. |
-| `shared/generated/ui-contract.ts`    | `dreamboard sync`          | Typed primitives, interaction keys, input keys, prompt options, zones, board targets, view types, typed hooks. |
-| `test/testing-types.ts`              | `dreamboard test generate` | Workspace-narrowed `defineBase`, `defineScenario`, and `createTestRuntime`.                       |
-| `test/generated/testing-contract.ts` | `dreamboard test generate` | Scenario context, generated assertions, interaction parameter types.                              |
-
-If a generated file is stale, regenerate it instead of patching it:
-
-```bash
-dreamboard sync
-dreamboard test generate
-```
-
-## Imports
-
-Use the public reducer surface for app code:
-
-```ts
-import {
-  defineGame,
-  defineGameContract,
-  definePhase,
-  defineInteraction,
-  pipe,
-} from "@dreamboard/app-sdk/reducer";
-```
-
-Use generated workspace contracts for IDs and typed UI:
-
-```ts
-import { ids, literals, manifestContract } from "../shared/manifest-contract";
-import {
-  Interaction,
-  PromptInbox,
-  Zone,
-  useInteractionByKey,
-} from "../shared/generated/ui-contract";
-```
-
-Generated aliases may expose these as package-level imports inside scaffolded workspaces, but the ownership rule is the same: app code depends on the generated workspace contract, not on hand-written copies of IDs.
-
-## Where helpers belong
-
-Put small reusable reducer helpers in `app/reducer-support.ts` when they are
-game-specific and SDK-shaped. Helpers should accept injected `q` and `ops`
-instead of constructing their own table readers or state writers.
-
-```ts
-export function incrementScore(ops: Ops, playerId: PlayerId): Op<GameState> {
-  return ops.patchPublicState((prev) => ({
-    ...prev,
-    scores: {
-      ...prev.scores,
-      [playerId]: (prev.scores[playerId] ?? 0) + 1,
-    },
-  }));
-}
-```
-
-When helpers become domain rules, split them into `app/rules/*` modules such as
-`board.ts`, `resources.ts`, or `scoring.ts`. If the helper is broadly useful
-across games, it probably belongs in the SDK rather than in a local example.