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

package/README.md

@@ -36,6 +36,128 @@ 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 { createGame } from "@dreamboard-games/sdk/reducer";
+import { ids, manifestContract } from "../shared/manifest-contract";
+
+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`.
+Run the package-local `pnpm generate` command to refresh framework-owned
+manifest and UI contracts; generated files are not authoring surfaces.
+
 ## Reducer runner contract
 
 `createReducerBundle(game)` returns exactly the contract version and four

package/dist/authoring/index.js

@@ -7,9 +7,9 @@ import {
   materializeManifest,
   projectAuthoringAdapter,
   validateManifest
-} from "../chunk-KGV2EUNN.js";
-import "../chunk-KWHOFBDM.js";
-import "../chunk-HIH6Y4FA.js";
+} from "../chunk-QLSK3DYO.js";
+import "../chunk-EY2LL5WD.js";
+import "../chunk-JUGQ6F3N.js";
 import "../chunk-PZ5AY32C.js";
 export {
   GENERATED_WORKSPACE_PATHS,

package/dist/authoring-compiler.js

@@ -1,9 +1,9 @@
 import {
   materializeWorkspace
-} from "./chunk-HUK4234C.js";
-import "./chunk-KGV2EUNN.js";
-import "./chunk-KWHOFBDM.js";
-import "./chunk-HIH6Y4FA.js";
+} from "./chunk-2WJSQQT7.js";
+import "./chunk-QLSK3DYO.js";
+import "./chunk-EY2LL5WD.js";
+import "./chunk-JUGQ6F3N.js";
 import "./chunk-PZ5AY32C.js";
 export {
   materializeWorkspace

package/dist/{authoring-materialize-cli.js → authoring-generate-cli.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   materializeWorkspace
-} from "./chunk-HUK4234C.js";
-import "./chunk-KGV2EUNN.js";
-import "./chunk-KWHOFBDM.js";
-import "./chunk-HIH6Y4FA.js";
+} from "./chunk-2WJSQQT7.js";
+import "./chunk-QLSK3DYO.js";
+import "./chunk-EY2LL5WD.js";
+import "./chunk-JUGQ6F3N.js";
 import "./chunk-PZ5AY32C.js";
 
-// src/authoring-materialize-cli.ts
+// src/authoring-generate-cli.ts
 var options = parseArgs(process.argv.slice(2));
 var result = await materializeWorkspace(options);
 console.log(JSON.stringify(result, null, 2));
@@ -42,4 +42,4 @@ function parseArgs(argv) {
     ...writeMissingSeeds ? { writeMissingSeeds: true } : {}
   };
 }
-//# sourceMappingURL=authoring-materialize-cli.js.map
+//# sourceMappingURL=authoring-generate-cli.js.map

package/dist/authoring-generate-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/authoring-generate-cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { materializeWorkspace } from \"./authoring/materialize-workspace.js\";\n\nconst options = parseArgs(process.argv.slice(2));\nconst result = await materializeWorkspace(options);\nconsole.log(JSON.stringify(result, null, 2));\n\nfunction parseArgs(argv: readonly string[]): {\n  readonly manifestPath: string;\n  readonly projectRoot?: string;\n  readonly writeMissingSeeds?: boolean;\n} {\n  let manifestPath: string | undefined;\n  let projectRoot: string | undefined;\n  let writeMissingSeeds = false;\n  for (let index = 0; index < argv.length; index += 1) {\n    const arg = argv[index];\n    if (arg === \"--manifest\") {\n      manifestPath = argv[index + 1];\n      index += 1;\n      continue;\n    }\n    if (arg === \"--project-root\") {\n      projectRoot = argv[index + 1];\n      index += 1;\n      continue;\n    }\n    if (arg === \"--write-missing-seeds\") {\n      writeMissingSeeds = true;\n      continue;\n    }\n    throw new Error(`Unknown argument '${arg}'.`);\n  }\n  if (!manifestPath) {\n    throw new Error(\"--manifest is required.\");\n  }\n  return {\n    manifestPath,\n    ...(projectRoot === undefined ? {} : { projectRoot }),\n    ...(writeMissingSeeds ? { writeMissingSeeds: true } : {}),\n  };\n}\n"],"mappings":";;;;;;;;;;AAGA,IAAM,UAAU,UAAU,QAAQ,KAAK,MAAM,CAAC,CAAC;AAC/C,IAAM,SAAS,MAAM,qBAAqB,OAAO;AACjD,QAAQ,IAAI,KAAK,UAAU,QAAQ,MAAM,CAAC,CAAC;AAE3C,SAAS,UAAU,MAIjB;AACA,MAAI;AACJ,MAAI;AACJ,MAAI,oBAAoB;AACxB,WAAS,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAAG;AACnD,UAAM,MAAM,KAAK,KAAK;AACtB,QAAI,QAAQ,cAAc;AACxB,qBAAe,KAAK,QAAQ,CAAC;AAC7B,eAAS;AACT;AAAA,IACF;AACA,QAAI,QAAQ,kBAAkB;AAC5B,oBAAc,KAAK,QAAQ,CAAC;AAC5B,eAAS;AACT;AAAA,IACF;AACA,QAAI,QAAQ,yBAAyB;AACnC,0BAAoB;AACpB;AAAA,IACF;AACA,UAAM,IAAI,MAAM,qBAAqB,GAAG,IAAI;AAAA,EAC9C;AACA,MAAI,CAAC,cAAc;AACjB,UAAM,IAAI,MAAM,yBAAyB;AAAA,EAC3C;AACA,SAAO;AAAA,IACL;AAAA,IACA,GAAI,gBAAgB,SAAY,CAAC,IAAI,EAAE,YAAY;AAAA,IACnD,GAAI,oBAAoB,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAAA,EACzD;AACF;","names":[]}

package/dist/{chunk-HUK4234C.js → chunk-2WJSQQT7.js}

@@ -1,9 +1,9 @@
 import {
   generateWorkspaceArtifacts
-} from "./chunk-KGV2EUNN.js";
+} from "./chunk-QLSK3DYO.js";
 import {
   WORKSPACE_CODEGEN_OWNERSHIP
-} from "./chunk-HIH6Y4FA.js";
+} from "./chunk-JUGQ6F3N.js";
 
 // src/authoring/materialize-workspace.ts
 import { createHash, randomUUID } from "crypto";
@@ -163,4 +163,4 @@ async function isFile(filePath) {
 export {
   materializeWorkspace
 };
-//# sourceMappingURL=chunk-HUK4234C.js.map
+//# sourceMappingURL=chunk-2WJSQQT7.js.map