dreamboard 0.1.7 → 0.1.8

package/skills/dreamboard/references/testing-ui-tests.md

@@ -0,0 +1,174 @@
+# UI tests
+
+Test workspace UI with reducer-native runtime providers.
+
+Use `createTestRuntime` for reducer-backed, backend-free React tests that need real
+Dreamboard runtime context. It creates an in-memory runtime from a generated
+base state, drives the same reducer bundle as scenarios, and feeds snapshots
+through the UI host runtime store.
+
+This is for UI logic tests, not browser end-to-end tests.
+
+## Generate first
+
+UI tests depend on generated base states:
+
+```bash
+dreamboard test generate
+```
+
+If the base state is missing or stale, regenerate before debugging React.
+
+## Basic harness
+
+```tsx
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  PluginStateProvider,
+  RuntimeProvider,
+  useGameView,
+  useIsMyTurn,
+} from "@dreamboard/ui-sdk";
+import { useInteractionByKey } from "../shared/generated/ui-contract";
+import { createTestRuntime } from "../test/testing-types";
+
+function Probe() {
+  const view = useGameView();
+  const placeThing = useInteractionByKey("placeThing.placeThingCard");
+  const isMyTurn = useIsMyTurn();
+
+  return (
+    <div
+      data-is-my-turn={isMyTurn ? "true" : "false"}
+      data-surface={placeThing?.descriptor.surface ?? "missing"}
+      data-hand-size={view.handCards.length}
+    />
+  );
+}
+
+function renderTree(runtime: ReturnType<typeof createTestRuntime>) {
+  return renderToStaticMarkup(
+    <RuntimeProvider runtime={runtime.runtime}>
+      <PluginStateProvider>
+        <Probe />
+      </PluginStateProvider>
+    </RuntimeProvider>,
+  );
+}
+
+test("renders the initial playable hand", () => {
+  const runtime = createTestRuntime({
+    baseId: "initial-turn",
+    phase: "placeThing",
+    controllingPlayerId: "player-2",
+  });
+
+  const markup = renderTree(runtime);
+
+  assert.match(markup, /data-is-my-turn="true"/);
+  assert.match(markup, /data-surface="hand"/);
+  assert.match(markup, /data-hand-size="5"/);
+});
+```
+
+The important providers are:
+
+| Provider | Purpose |
+| --- | --- |
+| `RuntimeProvider` | Supplies the in-memory `RuntimeAPI`. |
+| `PluginStateProvider` | Supplies reducer-projected plugin state to UI hooks. |
+
+## Runtime options
+
+```ts
+const runtime = createTestRuntime({
+  baseId: "initial-turn",
+  phase: "placeThing",
+  controllingPlayerId: "player-2",
+  userId: "test-user",
+});
+```
+
+Options:
+
+| Option | Meaning |
+| --- | --- |
+| `baseId` | Generated base state id. Required. |
+| `phase` | Optional expected phase for the initial snapshot. |
+| `controllingPlayerId` | Seat controlled by the rendered UI. |
+| `userId` | Test user id; defaults to `"test-user"`. |
+
+`baseId` is typed to generated `BASE_STATES`, so misspelled bases fail at
+compile time.
+
+## Submitting interactions
+
+`createTestRuntime` returns helpers for driving state:
+
+```tsx
+const runtime = createTestRuntime({
+  baseId: "initial-turn",
+  phase: "placeThing",
+  controllingPlayerId: "player-2",
+});
+
+await runtime.submit(runtime.seat(1), "placeThingCard", {
+  cardId: "a-diamond",
+  ringId: "ring-1",
+});
+
+const after = renderTree(runtime);
+assert.match(after, /data-hand-size="4"/);
+```
+
+Submission validates input, dispatches through the reducer bundle, applies a
+fresh gameplay snapshot, and notifies UI subscribers.
+
+## Switching seats
+
+Use `setControllingPlayer` to test player-specific views:
+
+```tsx
+runtime.setControllingPlayer("player-3");
+
+const markup = renderTree(runtime);
+assert.match(markup, /data-is-my-turn="false"/);
+```
+
+This exercises the same session-store path used by host player switching.
+
+## What to test here
+
+Good UI runtime tests:
+
+- hooks see the expected phase, view, and available interactions
+- `useIsMyTurn` and controlling-player changes behave correctly
+- custom primitive renderers receive descriptors
+- card hands update after reducer submissions
+- prompt or blocker UI appears for the addressed seat only
+
+Avoid testing browser-only layout here. Use the local dev host or browser runner
+for screenshots, pointer events, and CSS layout issues.
+
+## Projection fixture tests
+
+For lighter UI probes, read generated base projection JSON and provide a small
+mock `RuntimeAPI`. This is useful when the test only needs hooks and render
+behavior, not reducer dispatch.
+
+Star Settlers uses this pattern in `test/ui/app.test.tsx`: it loads
+`test/generated/bases/<base>/player-*.projection.json`, wraps probes in
+`RuntimeProvider` and `PluginStateProvider`, then asserts that typed hooks such
+as `useGameView`, `useInteractionByKey`, and `useBoardInteractions` see the
+expected projected state.
+
+## TSX runtime config
+
+Reducer-native UI tests that import React components from workspace or SDK
+sources may need a TSX-specific test tsconfig that enables the React JSX
+transform for those sources. Keep that config separate from the normal
+`test/tsconfig.json`; broadening the normal typecheck include can pull SDK
+fixtures into `tsc --noEmit`.

package/skills/dreamboard/references/testing.md

@@ -0,0 +1,161 @@
+# 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

@@ -0,0 +1,137 @@
+# 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

@@ -0,0 +1,34 @@
+# 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

@@ -0,0 +1,72 @@
+# 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.