@dreamboard-games/sdk 0.5.0-alpha.0 → 0.5.0-alpha.2

package/README.md

@@ -36,6 +36,133 @@ Include the packaged stylesheet when using SDK UI components:
 import "@dreamboard-games/sdk/ui/plugin-styles.css";
 ```
 
+## Game authoring
+
+`createGame(model)` is the single authoring entry point. The **model** is a
+plain object: manifest ids, state schemas, one Zod schema per phase, and error
+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 })`.
+
+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.
+
+```ts
+// app/game-model.ts — the model, bound once
+import { z } from "zod";
+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,
+  state: {
+    public: z.object({ currentPlayerId: ids.playerId.nullable() }),
+    private: z.object({}),
+    hidden: z.object({}),
+  },
+  phases: {
+    setup: z.object({}),
+    play: z.object({ leadCardId: ids.cardId.nullable() }),
+  },
+  errors: { NOT_YOUR_CARD: "Play a card from your own hand." },
+});
+
+export type GameState = typeof game.types.State;
+```
+
+```ts
+// app/phases/play.ts — one phase, one file
+import { game } from "../game-model";
+
+const play = game.phase("play");
+
+// Inputs name their candidate domain and eligibility predicates directly.
+// `where.errorCode` is checked against `model.errors`.
+const ownCard = play.inputs.card({
+  from: ["hand"],
+  where: {
+    id: "own-card",
+    errorCode: "NOT_YOUR_CARD",
+    test: ({ q, playerId, targetId }) =>
+      q.zone.playerCards(playerId, "hand").includes(targetId),
+  },
+});
+
+export default play.define({
+  kind: "player",
+  initialState: () => ({ leadCardId: null }),
+  actor: ({ state }) => state.publicState.currentPlayerId,
+  interactions: {
+    playCard: play.interaction({
+      inputs: { cardId: ownCard },
+      reduce({ tx, input, q }) {
+        // tx.state.phase.leadCardId and input.params.cardId are inferred.
+        tx.moveCardFromPlayerZoneToSharedZone({
+          playerId: input.playerId,
+          fromZoneId: "hand",
+          toZoneId: "trick",
+          cardId: input.params.cardId,
+        });
+        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) {
+          return tx.transition("setup");
+        }
+      },
+    }),
+  },
+});
+```
+
+```ts
+// app/game.ts — assembly
+import { game } from "./game-model";
+import play from "./phases/play";
+import setup from "./phases/setup";
+
+export default game.assemble({
+  initial: {
+    public: ({ playerIds }) => ({ currentPlayerId: playerIds[0] ?? null }),
+    private: () => ({}),
+    hidden: () => ({}),
+  },
+  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,
+      }),
+    }),
+  },
+});
+```
+
+A missing, extra, or misspelled phase key fails to typecheck at `assemble`
+or at `game.phase(name)`. Rules, views, and tests import `GameState` and
+`typeof game.types.Tx` from the model module; nothing but the test harness
+imports the assembled game, so there is no import cycle.
+
+New workspaces keep authored starter code in `app/game.ts` and `ui/App.tsx`.
+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 UI primitives with
+`createGameUi(game)` from `@dreamboard-games/sdk/runtime/workspace-contract`.
+No authoring generation step or shared workspace files are needed.
+
 ## Reducer runner contract
 
 `createReducerBundle(game)` returns exactly the contract version and four

package/dist/browser-interaction.d.ts

@@ -29,7 +29,7 @@ declare function gameplayCommitEffect(): GameplaySemanticEffect;
 declare function gameplayInvokeEffect(): GameplaySemanticEffect;
 
 declare function defineBrowserInteractionSurface<Surface extends BrowserInteractionSurface, Intent extends BrowserInteractionIntent>(definition: BrowserInteractionSurfaceDefinition<Surface, Intent>): BrowserInteractionSurfaceDefinition<Surface, Intent>;
-declare const gameplayBrowserInteractionSurface: BrowserInteractionSurfaceDefinition<"gameplay", "fill" | "arm" | "reveal" | "invoke" | "select" | "toggle" | "increment" | "decrement" | "submit", string>;
+declare const gameplayBrowserInteractionSurface: BrowserInteractionSurfaceDefinition<"gameplay", "arm" | "reveal" | "invoke" | "select" | "toggle" | "increment" | "decrement" | "fill" | "submit", string>;
 declare function createBrowserInteractionRegistry(definitions?: readonly BrowserInteractionSurfaceDefinition[]): BrowserInteractionRegistry;
 declare const defaultBrowserInteractionRegistry: BrowserInteractionRegistry;
 
@@ -111,8 +111,8 @@ declare const gameplaySemanticEffectSchema: z.ZodUnion<readonly [z.ZodObject<{
 declare const browserInteractionDiagnosticSchema: z.ZodObject<{
     code: z.ZodString;
     severity: z.ZodEnum<{
-        warning: "warning";
         error: "error";
+        warning: "warning";
     }>;
     message: z.ZodString;
     surface: z.ZodOptional<z.ZodString>;
@@ -190,8 +190,8 @@ declare const browserInteractionActuatorSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            warning: "warning";
             error: "error";
+            warning: "warning";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -225,8 +225,8 @@ declare const browserInteractionPointerTargetSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            warning: "warning";
             error: "error";
+            warning: "warning";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -315,8 +315,8 @@ declare const browserGameplayInteractionSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                warning: "warning";
                 error: "error";
+                warning: "warning";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -350,8 +350,8 @@ declare const browserGameplayInteractionSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                warning: "warning";
                 error: "error";
+                warning: "warning";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -365,8 +365,8 @@ declare const browserGameplayInteractionSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            warning: "warning";
             error: "error";
+            warning: "warning";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -458,8 +458,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    warning: "warning";
                     error: "error";
+                    warning: "warning";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -493,8 +493,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    warning: "warning";
                     error: "error";
+                    warning: "warning";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -508,8 +508,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                warning: "warning";
                 error: "error";
+                warning: "warning";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -523,8 +523,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            warning: "warning";
             error: "error";
+            warning: "warning";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -616,8 +616,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    warning: "warning";
                     error: "error";
+                    warning: "warning";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -651,8 +651,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    warning: "warning";
                     error: "error";
+                    warning: "warning";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -666,8 +666,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                warning: "warning";
                 error: "error";
+                warning: "warning";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -681,8 +681,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            warning: "warning";
             error: "error";
+            warning: "warning";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -699,8 +699,8 @@ declare const browserUnknownSurfaceSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            warning: "warning";
             error: "error";
+            warning: "warning";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -797,8 +797,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
                 diagnostics: z.ZodArray<z.ZodObject<{
                     code: z.ZodString;
                     severity: z.ZodEnum<{
-                        warning: "warning";
                         error: "error";
+                        warning: "warning";
                     }>;
                     message: z.ZodString;
                     surface: z.ZodOptional<z.ZodString>;
@@ -832,8 +832,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
                 diagnostics: z.ZodArray<z.ZodObject<{
                     code: z.ZodString;
                     severity: z.ZodEnum<{
-                        warning: "warning";
                         error: "error";
+                        warning: "warning";
                     }>;
                     message: z.ZodString;
                     surface: z.ZodOptional<z.ZodString>;
@@ -847,8 +847,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    warning: "warning";
                     error: "error";
+                    warning: "warning";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -862,8 +862,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                warning: "warning";
                 error: "error";
+                warning: "warning";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -879,8 +879,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                warning: "warning";
                 error: "error";
+                warning: "warning";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -894,8 +894,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            warning: "warning";
             error: "error";
+            warning: "warning";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;