dreamboard 0.1.21 → 0.1.22

package/skills/dreamboard/references/testing-generated-contracts.md

@@ -1,142 +0,0 @@
-# Generated testing contracts
-
-Understand generated testing files, regeneration, and stale contract failures.
-
-Dreamboard testing has a small authored surface and a larger generated surface.
-The generated surface keeps tests typed to the current manifest, reducer, view,
-interaction, and UI contract shape.
-
-Run generation with:
-
-```bash
-dreamboard test generate
-```
-
-## Generated files
-
-| Path | Generated by | Purpose |
-| --- | --- | --- |
-| `test/testing-types.ts` | `dreamboard test generate` | Workspace-narrowed `defineBase`, `defineScenario`, `createTestRuntime`, and re-exports. |
-| `test/generated/testing-contract.ts` | `dreamboard test generate` | Player ids, base ids, interaction ids, typed scenario context, phase/stage/view types, known rejection codes. |
-| `test/generated/base-states.generated.ts` | `dreamboard test generate` | Deterministic base snapshots and fingerprints. |
-| `test/generated/base-states.generated.d.ts` | `dreamboard test generate` | Type declaration for generated base states. |
-| `test/generated/scenario-manifest.generated.ts` | `dreamboard test generate` | Scenario id, file path, base id, and runner list. |
-| `test/generated/.generation-meta.json` | `dreamboard test generate` | Generation timestamp and artifact counts. |
-| `test/generated/bases/**/player-*.projection.json` | `dreamboard test generate` | Per-player projection snapshots for generated bases. |
-| `test/generated/snapshots/*.snapshot.json` | `dreamboard test run --update-snapshots` or first snapshot assertion | Scenario snapshot matcher output. |
-
-Files with a `Generated by` header should not be edited manually.
-
-## testing-types.ts
-
-`test/testing-types.ts` is the only testing import surface base and scenario
-files should use:
-
-```ts
-import {
-  defineBase,
-  defineScenario,
-  createTestRuntime,
-  type InteractionId,
-  type PlayerId,
-} from "../testing-types";
-```
-
-It wraps generated types so:
-
-- `defineBase` receives a workspace `BaseDefinition`
-- `defineScenario` narrows `phase`, `stage`, view, and interaction params
-- `createTestRuntime` accepts generated base ids and player ids
-
-UI tests may also import `@dreamboard/ui-sdk` and the generated UI contract
-because they render React against projected runtime state.
-
-If the wrapper is stale, regenerate it. Do not patch it by hand.
-
-## testing-contract.ts
-
-The generated testing contract is derived from the workspace game and
-`shared/generated/ui-contract.ts`. It includes:
-
-- `PlayerId`
-- `BaseId`
-- `InteractionId`
-- `InteractionParamsOf`
-- `PhaseName`
-- `WorkspaceStageName`
-- `GameView`
-- `ScenarioContext`
-- `KnownRejectionCode`
-- `BrowserRunnerDriver` types for internal browser lanes
-
-Scenario `game.submit` is typed from `InteractionId` to the matching param
-shape, so invalid params should fail before runtime.
-
-## Base fingerprints
-
-Generated base artifacts include fingerprints for the files and runtime inputs
-that affect replay:
-
-- base module
-- manifest
-- reducer bundle
-- UI contract
-- compiled result and game id when relevant
-- seed and player count
-- setup profile
-- parent base id and parent fingerprint for inherited bases
-
-When any of these change, `dreamboard test run` fails with a message such as:
-
-```text
-base module changed; game reducer bundle changed; ui contract changed. Run 'dreamboard test generate' to refresh reducer-native base artifacts.
-```
-
-That is expected. Regenerate first, then debug scenario behavior.
-
-## Scenario manifest
-
-`scenario-manifest.generated.ts` records which scenario files exist, which base
-each uses, and which runners they request:
-
-```ts
-export const SCENARIO_MANIFEST = [
-  {
-    id: "smoke-initial-turn",
-    filePath: "../scenarios/smoke-initial-turn.scenario.ts",
-    base: "initial-turn",
-    runners: ["reducer"],
-  },
-] as const;
-```
-
-The CLI uses this to run the right scenario set and to report scenario ids
-consistently.
-
-## Missing generated files
-
-Fresh or partially regenerated workspaces may have placeholder generated files
-before the first real generation pass. Run:
-
-```bash
-dreamboard test generate
-```
-
-Then run:
-
-```bash
-dreamboard test run
-```
-
-If `test run` still fails with missing base artifacts, check that:
-
-- at least one `test/bases/*.base.ts` file exists
-- at least one `test/scenarios/*.scenario.ts` file exists
-- every scenario `from` references a base id
-- inherited parent bases have been generated
-
-## Regeneration rule
-
-Regenerate after changing any authored source that changes runtime behavior or
-generated types. It is cheaper and more accurate to regenerate than to debug a
-scenario against stale base snapshots.

package/skills/dreamboard/references/testing-runtime-assertions.md

@@ -1,124 +0,0 @@
-# Runtime assertions
-
-Use generated scenario context helpers and matchers.
-
-`defineScenario` callbacks receive a typed context. Use that context to submit
-interactions, read projected views, inspect interaction descriptors, and assert
-behavior.
-
-## Context helpers
-
-| Helper | Available in | Meaning |
-| --- | --- | --- |
-| `game.start()` | Base setup, `when`, `then` | Starts the game. Usually handled by the harness before scenario setup. |
-| `game.submit(playerId, interactionId, params?)` | Base setup, `when`, `then` | Validates and dispatches an interaction. |
-| `players()` | Base setup, `when`, `then` | Ordered player ids for the current base. |
-| `seat(index)` | Base setup, `when`, `then` | Player id at a seat index; throws when out of range. |
-| `state()` | `when`, `then` | Current phase name. |
-| `view(playerId)` | `when`, `then` | Reducer-projected `GameView` for a player. |
-| `interactions(playerId)` | `when`, `then` | Current interaction descriptors for a player. |
-| `expect(value)` | `when`, `then` | Built-in assertion API. |
-
-`state()` is the phase name, not the raw reducer state. Assert game-specific
-state through `view(playerId)` or through projected descriptors.
-
-## View assertions
-
-Use `view(playerId)` for player-facing state:
-
-```ts
-then: ({ view, expect, seat }) => {
-  const p1View = view(seat(0));
-  expect(p1View.resources.brick).toBe(2);
-  expect(p1View.pathsByEdgeId["edge-a"]).toBeDefined();
-};
-```
-
-When a scenario declares `phase`, generated types narrow `view` in `then` when
-the workspace view has phase-tagged variants.
-
-## Interaction assertions
-
-Use `interactions(playerId)` to check what the UI would be allowed to render:
-
-```ts
-then: ({ interactions, expect, seat }) => {
-  expect(interactions(seat(0))).toHaveInteraction("judgePlacement", {
-    kind: "prompt",
-  });
-
-  expect(interactions(seat(1))).not.toHaveInteraction("judgePlacement");
-};
-```
-
-Descriptor matchers are better than ad hoc descriptor shape checks because they
-state the rule being tested: present, absent, active, or gated.
-
-## Matchers
-
-Value matchers:
-
-| Matcher | Purpose |
-| --- | --- |
-| `toBe(expected)` | Strict equality. |
-| `toEqual(expected)` | Deep equality. |
-| `toMatchObject(partial)` | Deep partial object match. |
-| `toBeDefined()` | Value is not `undefined`. |
-| `toBeUndefined()` | Value is `undefined`. |
-| `toBeNull()` | Value is `null`. |
-| `toContain(expected)` | Array or string contains value. |
-| `toContainEqual(expected)` | Array contains a deeply equal value. |
-| `toHaveLength(n)` | Value has exact `length`. |
-| `toBeGreaterThanOrEqual(n)` | Numeric lower-bound check. |
-| `toThrow(predicate?)` | Synchronous throw assertion. |
-| `toMatchSnapshot(filename?)` | Scenario snapshot assertion. |
-
-Async rejection matcher:
-
-```ts
-await expect(() =>
-  game.submit(seat(1), "judgePlacement", { decision: "ring-1" }),
-).toRejectWith({
-  errorCode: "prompt-not-owned",
-  message: /prompt/i,
-});
-```
-
-Descriptor matchers:
-
-| Matcher | Purpose |
-| --- | --- |
-| `toHaveInteraction(id, opts?)` | Descriptor array contains an interaction. |
-| `not.toHaveInteraction(id)` | Descriptor array does not contain an interaction. |
-| `toBeGatedBy(reason, opts?)` | Descriptor is unavailable with the expected reason. |
-| `toBeActiveFor(playerId, opts?)` | Descriptor targets the player and is available. |
-
-`toBeGatedBy` and `toBeActiveFor` can operate on a descriptor array when you pass
-`opts.interactionId`, or on a single descriptor.
-
-## Snapshot assertions
-
-Use snapshots for large projected objects that are intentionally stable:
-
-```ts
-then: ({ view, expect, seat }) => {
-  expect(view(seat(0)).market).toMatchSnapshot("market");
-};
-```
-
-Snapshots are written under `test/generated/snapshots/`. When an existing
-snapshot differs, the runner fails and tells you to rerun with
-`--update-snapshots`.
-
-Do not snapshot noisy values unless the noise is the point of the test. Prefer
-targeted matchers for a specific rule.
-
-## Assertion guidelines
-
-- Assert public behavior: phase, view, available interactions, and rejection
-  codes.
-- Do not assert raw reducer internals unless the view intentionally exposes the
-  same fact.
-- Use descriptor matchers for actor, prompt, and availability rules.
-- Use `toRejectWith` for validation and reducer rejection paths.
-- Keep the assertion close to the rule the scenario name promises.

package/skills/dreamboard/references/testing-scenarios.md

@@ -1,148 +0,0 @@
-# Scenarios
-
-Define reducer-native test scenarios with actions, prompts, effects, and assertions.
-
-A scenario starts from a generated base, submits reducer interactions, and
-asserts the resulting phase, view, and interaction descriptors.
-
-Scenarios live under `test/scenarios/*.scenario.ts`.
-
-## Basic scenario
-
-```ts
-import { defineScenario } from "../testing-types";
-
-export default defineScenario({
-  id: "setup-place",
-  description: "Seat 0 places a marker and path during setup",
-  from: "initial-turn",
-  phase: "setup",
-  when: async ({ game, seat }) => {
-    await game.submit(seat(0), "placeSetupMarker", {
-      vertexId: "hex-vertex:-1,-1,2",
-    });
-    await game.submit(seat(0), "placeSetupPath", {
-      edgeId: "hex-edge:-1,-1,2::-2,-2,4",
-    });
-  },
-  then: ({ expect, state, view, seat }) => {
-    expect(state()).toBe("setup");
-    expect(view(seat(0)).markersByVertexId["hex-vertex:-1,-1,2"]).toBeDefined();
-  },
-});
-```
-
-Fields:
-
-| Field | Required | Meaning |
-| --- | --- | --- |
-| `id` | Yes | Unique scenario id. |
-| `description` | No | Short human-readable summary. |
-| `from` | Yes | Base id to start from. |
-| `runners` | No | Defaults to `["reducer"]`. Public tests normally omit it. |
-| `phase` | No | Expected phase after `when`. Also narrows `view` in `then` when possible. |
-| `stage` | No | Expected stage after `when`, constrained by phase. |
-| `when` | Yes | Async action flow. |
-| `then` | Yes | Assertions. |
-
-## Submit interactions
-
-Use `game.submit(playerId, interactionId, params)`:
-
-```ts
-await game.submit(seat(1), "placeThingCard", {
-  cardId: "a-diamond",
-  ringId: "ring-1",
-});
-```
-
-The `interactionId` is the generated interaction id, not the phase-qualified UI
-key. Params are typed from the generated UI contract.
-
-Prompts use the same submit path:
-
-```ts
-await game.submit(seat(0), "judgePlacement", {
-  decision: "ring-1",
-});
-```
-
-There is no separate prompt-response API in the current reducer-native test
-contract. If a player can submit it, model it as an interaction.
-
-## Phase and stage checks
-
-Use `phase` when the scenario should end in a known phase:
-
-```ts
-export default defineScenario({
-  id: "reject-non-knower-cannot-judge",
-  from: "after-first-placement",
-  phase: "judgeRings",
-  when: async ({ game, seat, expect }) => {
-    await expect(() =>
-      game.submit(seat(1), "judgePlacement", { decision: "ring-1" }),
-    ).toRejectWith({ errorCode: "prompt-not-owned" });
-  },
-  then: ({ state, expect }) => {
-    expect(state()).toBe("judgeRings");
-  },
-});
-```
-
-The runner checks `phase` after `when` and before `then`. If the reducer reached
-a different phase, the scenario fails before assertions run.
-
-Use `stage` the same way for phase stages:
-
-```ts
-export default defineScenario({
-  id: "main-stage-after-roll",
-  from: "after-setup",
-  phase: "playerTurn",
-  stage: "main",
-  when: async ({ game, seat }) => {
-    await game.submit(seat(0), "rollDice");
-  },
-  then: ({ state, expect }) => {
-    expect(state()).toBe("playerTurn");
-  },
-});
-```
-
-## Rejection scenarios
-
-Illegal submissions should be tested directly:
-
-```ts
-await expect(() =>
-  game.submit(seat(1), "placeThingCard", {
-    cardId: "a-diamond",
-    ringId: "ring-1",
-  }),
-).toRejectWith({ errorCode: "NOT_YOUR_TURN" });
-```
-
-Then assert the game remained in the expected state:
-
-```ts
-then: ({ state, interactions, expect, seat }) => {
-  expect(state()).toBe("placeThing");
-  expect(interactions(seat(1))).not.toHaveInteraction("judgePlacement");
-};
-```
-
-## Scenario shape
-
-Keep `when` focused on the action being exercised. Keep assertions in `then`.
-If a setup flow is required by many scenarios, move it into a base.
-
-Good scenario ids are stable and behavior-oriented:
-
-- `smoke-initial-turn`
-- `setup-place`
-- `trade-full-lifecycle`
-- `reject-out-of-turn-placement`
-- `reject-non-knower-cannot-judge`
-
-Avoid ids that describe implementation details or temporary bugs.

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

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