@dreamboard-games/sdk 0.5.0-alpha.1 → 0.5.0-alpha.3

package/README.md

@@ -1,5 +1,7 @@
 # @dreamboard-games/sdk
 
+[Guides and API reference](../../docs/index.md) · [Registry](../../registry/README.md) · [Examples](../../examples/reference-games/README.md)
+
 The public TypeScript SDK for authoring, testing, and rendering Dreamboard
 games. Install this package rather than any of the repository's unpublished
 workspace inputs.
@@ -8,33 +10,15 @@ workspace inputs.
 pnpm add @dreamboard-games/sdk
 ```
 
-The package's declarations and export map are the API authority. Supported
-imports include the root module and explicit subpaths for authoring, runtime,
-reducer contracts, testing, browser interaction, UI, and reference-game
-metadata. Import only subpaths present in the installed package's `exports`
-field.
+The package declarations and export map are the API authority. There are four entry points:
 
-```ts
-import { DREAMBOARD_SDK_VERSION } from "@dreamboard-games/sdk";
-import type { ReducerWire } from "@dreamboard-games/sdk/reducer-contract";
-import {
-  REFERENCE_GAME_MANIFEST_SCHEMA_VERSION,
-  parseReferenceGameManifest,
-  type ReferenceGameManifest,
-} from "@dreamboard-games/sdk/reference-games";
-
-const manifest: ReferenceGameManifest = parseReferenceGameManifest(input);
-console.log(REFERENCE_GAME_MANIFEST_SCHEMA_VERSION, manifest.id);
-```
+- `@dreamboard-games/sdk`: framework-free instances, sources, features and canonical host protocol schemas.
+- `@dreamboard-games/sdk/react`: typed React provider, selector hook and subscription component.
+- `@dreamboard-games/sdk/reducer`: game authoring, manifest compilation, execution and trusted worker admission.
+- `@dreamboard-games/sdk/testing`: browser-safe local/scenario sources, replay, inspection and bounded exploration.
 
-Reference-game manifests use schema V5. They describe the game workspace,
-teaching purpose, mechanics, UI patterns, and substantive rights metadata.
-
-Include the packaged stylesheet when using SDK UI components:
-
-```ts
-import "@dreamboard-games/sdk/ui/plugin-styles.css";
-```
+UI components are source-owned registry items installed into your application.
+The SDK contains no styled components or stylesheet.
 
 ## Game authoring
 
@@ -45,20 +29,27 @@ codes. The returned value is three things at once:
 - the **type leaf**: `typeof game.types.State`, `.ErrorCode`, `.PlayerId`,
   `.Queries`, `.Tx` (phantom carriers; reading them at runtime throws),
 - the **factory namespace**: `game.phase(name)`, `phase.define`,
-  `phase.interaction`, `phase.inputs.*`, `game.views.*`,
-- the **assembler**: `game.assemble({ initial, initialPhase, phases, views })`.
+  `phase.interaction`, `phase.inputs.*`, `game.view`,
+- the **assembler**: `game.assemble({ initial, initialPhase, phases, view })`.
 
 Mutation callbacks (`enter`, `reduce`, `resolve`) receive an open transaction
 `tx`. Mutate through it and finish with a bare `return` (accept), or with
 `tx.transition(name)`, `tx.endGame(outcome)`, or `tx.reject(code)`. Events go
 through `tx.emit(...)`. `state` is the read-only snapshot the callback started
-from; `tx.state` is the current draft.
+from; `tx.state` is the current draft. The transaction clones its table once;
+all card, component, resource, and state-slice updates use that draft. Use
+`tx.q` when a query must observe an earlier mutation in the same callback.
+State patch callbacks return a replacement slice without mutating their input.
+The former `ops`, `pipe`, flat `setActivePlayers`, and `tx.apply` APIs are removed;
+call the named transaction methods directly.
 
 ```ts
 // app/game-model.ts — the model, bound once
 import { z } from "zod";
-import { createGame } from "@dreamboard-games/sdk/reducer";
-import { ids, manifestContract } from "../shared/manifest-contract";
+import { compileManifest, createGame } from "@dreamboard-games/sdk/reducer";
+import manifest from "../manifest";
+const manifestContract = compileManifest(manifest);
+const { ids } = manifestContract;
 
 export const game = createGame({
   manifest: manifestContract,
@@ -112,8 +103,11 @@ export default play.define({
         });
         tx.patchPhaseState({ leadCardId: input.params.cardId });
         const next = q.player.nextInOrder(input.playerId);
-        if (next) tx.setActivePlayers([next]);
-        if (q.zone.playerCards(input.playerId, "hand").length === 0) {
+        if (next) {
+          tx.patchPublicState({ currentPlayerId: next });
+          tx.setActivePlayers([next]);
+        }
+        if (tx.q.zone.playerCards(input.playerId, "hand").length === 0) {
           return tx.transition("setup");
         }
       },
@@ -122,6 +116,42 @@ export default play.define({
 });
 ```
 
+Dependent choices use `phase.steps()` instead of `inputs`. Each accepted command
+commits exactly one current value. Factories receive only earlier parsed
+`selected` values; descriptors expose only the current input. The final commit
+runs complete-parameter validation and the reducer once. Use explicit `null`
+for a no-target choice, and `many(...)` for one atomic multi-selection.
+
+```ts
+const choose = play.interaction({
+  steps: play
+    .steps()
+    .input(
+      "kind",
+      play.inputs.form.choice({
+        choices: [{ value: "single", label: "Single" }],
+        defaultValue: () => undefined,
+      }),
+    )
+    .input("count", ({ selected }) =>
+      play.inputs.form.number({
+        min: 1,
+        max: selected.kind === "single" ? 1 : 3,
+        defaultValue: 1,
+      }),
+    ),
+  reduce({ input }) {
+    // input.params contains both kind and count here.
+  },
+});
+```
+
+`rules.available` controls action eligibility; `rules.validate` checks a final
+submission. Accepted state changes reconcile pending prefixes, while phase
+entry clears them. A rejected final submission keeps the prior prefix. The
+actor can cancel an unsealed prefix with `interaction.cancel`, using the same
+transport basis and action identity as submission.
+
 ```ts
 // app/game.ts — assembly
 import { game } from "./game-model";
@@ -136,16 +166,11 @@ export default game.assemble({
   },
   initialPhase: "setup",
   phases: { setup, play },
-  views: {
-    shared: game.views.empty(),
-    player: game.views.player({
-      project: ({ state, playerId, q }) => ({
-        me: playerId,
-        hand: q.zone.playerCards(playerId, "hand"),
-        current: state.publicState.currentPlayerId,
-      }),
-    }),
-  },
+  view: game.view(({ state, playerId, q }) => ({
+    me: playerId,
+    hand: q.zone.playerCards(playerId, "hand"),
+    current: state.publicState.currentPlayerId,
+  })),
 });
 ```
 
@@ -155,17 +180,30 @@ or at `game.phase(name)`. Rules, views, and tests import `GameState` and
 imports the assembled game, so there is no import cycle.
 
 New workspaces keep authored starter code in `app/game.ts` and `ui/App.tsx`.
-Run the package-local `pnpm generate` command to refresh framework-owned
-manifest and UI contracts; generated files are not authoring surfaces.
+Import the manifest directly. `compileManifest(manifest)` provides inferred ID schemas,
+table schemas, fresh initial tables, and board metadata in memory. `createGame`
+also accepts the authored manifest directly. Bind a typed React hook with
+`createGameHook<Game>()({ features, coverage })` from `@dreamboard-games/sdk/react`,
+and pass a source to its `GameProvider`. The hosted UI imports `Game` only as a type;
+`iframeSource()` supplies authoritative frames and handles commands.
+No authoring generation step or shared workspace files are needed.
 
 ## Reducer runner contract
 
 `createReducerBundle(game)` returns exactly the contract version and four
 operations: `boardStatic()`, `initialize(input)`, `dispatch({ state, input })`,
-and `project({ state, playerIds })`. The runner contract is `0.5.0`; hosts must
-require that exact version. Dispatch includes validation and effect execution. Initialization returns
+and `project({ state, playerIds })`. The runner contract is `0.6.0`; hosts must
+require that exact version. Dispatch includes validation, direct transaction mutations, and phase entry.
+Initialization returns
 `{ state, terminal?, events? }`, preserving outcomes and events from initial
-phase entry and automatic continuations.
+phase entry and returned transitions.
+
+Mutation callbacks use `tx.roll(dieId)`, `tx.shuffle({ zoneId, playerId? })`, and
+`tx.deal({ fromZoneId, toZoneId, playerId, count })` directly. Return
+`tx.transition(phaseName)` to enter a phase, including reentering the current
+phase. An unreturned outcome schedules no work. Entry chains are bounded to
+1,000 entries per dispatch. `tx.endGame(outcome, { transition })` enters the
+final phase once; that entry must not return another transition.
 
 The authoritative state is explicit on every dispatch and projection. A host
 may retain a warm worker and SDK caches, but replaying the same state and input
@@ -177,3 +215,61 @@ owns the monotonically increasing version, perspective, and action-set identity.
 The plugin frame basis contains `version`, `actionSetVersion`, and
 `perspectivePlayerId`; it has no generation counter. Hosts merge the separately
 cached board static projection when materializing plugin gameplay frames.
+
+### Initialization options and actors
+
+Declare lobby options once on `createGame({ options: z.strictObject({ ... }), ... })`.
+The bundle accepts JSON-safe `options` at initialization, validates them with that
+schema, persists the parsed values, and supplies them to initial state and phase
+initializers. Without a schema, only `{}` is accepted. Options schemas must be
+JSON-native: transforms, preprocessing, and coercion are rejected. Restored
+sessions validate their stored options with the same schema.
+
+Perform shuffle, deal, and other initialization mutations in an ordinary phase
+entry callback. Setup profiles and bootstrap instructions are removed.
+Interactions use `actor` to override their phase actor; only authorized seats
+receive their input domains. Use ordinary form choices for responses and explicit
+rules plus transaction resource mutations for affordability. Prompt collectors,
+implicit costs, guidance metadata, and phase zone declarations are removed.
+
+A game authors one `view` for each requested seat. Public and private fields
+compose in that function; the transport never uses a seat view as a spectator
+payload. Static boards come directly from the compiled manifest.
+
+Use `memoize((input: SomeImmutableObject) => result)` for shared pure calculations.
+It caches by object identity with a WeakMap, including `undefined` results. Pass
+immutable snapshots (or stable immutable branches), not an open mutable transaction.
+There is no injected derived-value resolver.
+
+## React adapter dependency
+
+Framework-free consumers can import the package root without React. Applications
+using `@dreamboard-games/sdk/react` must install the maintained React store adapter
+alongside React:
+
+```sh
+pnpm add @dreamboard-games/sdk react@^19 react-dom@^19 @tanstack/react-store@0.11.1
+```
+
+`@tanstack/react-store` is an optional peer of the SDK so headless consumers do not
+install the React adapter. The `/react` entry delegates selectors to that package;
+the application bundler resolves its supported React subscription dependencies.
+
+## Local development and tests
+
+`localSource(game, { players, seed, as, options })` executes the production reducer
+and materializes the selected seat. `scenarioSource` starts from authored scenario
+checkpoints. Keep these executable game imports in your local development entry;
+the hosted entry uses only `iframeSource()` and type imports.
+
+Local sources expose `inspect`, bounded `explore`, typed explicit-actor `apply`,
+`switchSeat`, `checkpoint`, and validated `restore`. A JSON checkpoint preserves
+pending selections and terminal state; restoring does not replay commands.
+`createTestSource(snapshot)` supplies controlled frames and acknowledgements for
+instance and React tests. Static and hosted sources do not expose `apply`.
+
+Hosts import `assertReducerBundleContract`, `REDUCER_CONTRACT_VERSION`,
+`ReducerWire` types and `ReducerWireZod` schemas from `/reducer`. Canonical iframe
+and gameplay websocket schemas plus `materializePluginGameplayFrame` live at the
+root. Materialize the seat projection with static board data before publishing it;
+sources publish the canonical seat view and keep command bases private.

package/dist/chunk-DMFVAZI2.js

@@ -0,0 +1,16 @@
+// src/headless/sources/immutable.ts
+function immutableCopy(value) {
+  return freeze(structuredClone(value));
+}
+function freeze(value) {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) freeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+export {
+  immutableCopy
+};
+//# sourceMappingURL=chunk-DMFVAZI2.js.map

package/dist/chunk-DMFVAZI2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/headless/sources/immutable.ts"],"sourcesContent":["/** Source-owned snapshots and commands cannot be changed by their caller. */\nexport function immutableCopy<T>(value: T): T {\n  return freeze(structuredClone(value));\n}\nfunction freeze<T>(value: T): T {\n  if (value !== null && typeof value === \"object\") {\n    for (const child of Object.values(value)) freeze(child);\n    Object.freeze(value);\n  }\n  return value;\n}\n"],"mappings":";AACO,SAAS,cAAiB,OAAa;AAC5C,SAAO,OAAO,gBAAgB,KAAK,CAAC;AACtC;AACA,SAAS,OAAU,OAAa;AAC9B,MAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;AAC/C,eAAW,SAAS,OAAO,OAAO,KAAK,EAAG,QAAO,KAAK;AACtD,WAAO,OAAO,KAAK;AAAA,EACrB;AACA,SAAO;AACT;","names":[]}