@dreamboard-games/sdk 0.2.0

package/src/infrastructure/workspace-codegen.ts

@@ -0,0 +1 @@
+export * from "./workspace-codegen/index.js";

package/src/package-set.ts

@@ -0,0 +1,19 @@
+export const DREAMBOARD_SDK_VERSION = "0.2.0";
+
+export const DREAMBOARD_SDK_PACKAGES = {
+  "@dreamboard-games/sdk": DREAMBOARD_SDK_VERSION,
+} as const;
+
+export type DreamboardSdkPackageName = keyof typeof DREAMBOARD_SDK_PACKAGES;
+
+export type DreamboardSdkPackageSet = {
+  version: 1;
+  sdkVersion: string;
+  packages: Record<DreamboardSdkPackageName, string>;
+};
+
+export const DREAMBOARD_SDK_PACKAGE_SET: DreamboardSdkPackageSet = {
+  version: 1,
+  sdkVersion: DREAMBOARD_SDK_VERSION,
+  packages: DREAMBOARD_SDK_PACKAGES,
+};

package/src/reducer/authoring/contract.ts

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { createManifestStringLiteralSchema } from "../model/manifest";
+import type {
+  ReducerGameContract,
+  ReducerManifestContract,
+  RuntimeTableRecord,
+  SchemaLike,
+  StateDefinition,
+} from "../model";
+import {
+  type ManifestIdSchemasOf,
+  validateStateSchemaIdBranding,
+} from "./validation";
+
+/**
+ * Narrows a manifest's `literals.phaseNames` and `ids.phaseName` to the
+ * author-supplied phase-name tuple. Lets `defineGameContract` override the
+ * codegen-emitted `phaseNames: readonly string[]` / `phaseName: z.string()`
+ * placeholders so `PhaseNameOfContract<Contract>` resolves to a literal
+ * union and flows through `fx.transition`, `PhaseMapOf`, and the flow
+ * state's `currentPhase`.
+ */
+type NarrowManifestPhaseNames<
+  Manifest,
+  PhaseNames extends readonly string[],
+> = Omit<Manifest, "literals" | "ids"> & {
+  literals: Manifest extends { literals: infer L }
+    ? Omit<L, "phaseNames"> & { phaseNames: PhaseNames }
+    : { phaseNames: PhaseNames };
+  ids: Manifest extends { ids: infer I }
+    ? Omit<I, "phaseName"> & { phaseName: z.ZodType<PhaseNames[number]> }
+    : { phaseName: z.ZodType<PhaseNames[number]> };
+};
+
+type ReducerGameContractInput<
+  Table extends RuntimeTableRecord,
+  Manifest extends ReducerManifestContract<
+    Table,
+    string,
+    string,
+    string,
+    string,
+    string
+  >,
+  PublicSchema extends SchemaLike<object>,
+  PrivateSchema extends SchemaLike<object>,
+  HiddenSchema extends SchemaLike<object>,
+  Phases extends Record<string, SchemaLike<object>>,
+> = {
+  manifest: Manifest;
+  state: StateDefinition<PublicSchema, PrivateSchema, HiddenSchema>;
+  phases: Phases;
+};
+
+export function defineGameContract<
+  Table extends RuntimeTableRecord,
+  const Manifest extends ReducerManifestContract<
+    Table,
+    string,
+    string,
+    string,
+    string,
+    string
+  >,
+  PublicSchema extends SchemaLike<object>,
+  PrivateSchema extends SchemaLike<object>,
+  HiddenSchema extends SchemaLike<object>,
+  const Phases extends Record<string, SchemaLike<object>>,
+>(
+  definition: ReducerGameContractInput<
+    Table,
+    Manifest,
+    PublicSchema,
+    PrivateSchema,
+    HiddenSchema,
+    Phases
+  >,
+): ReducerGameContract<
+  Table,
+  NarrowManifestPhaseNames<Manifest, readonly (keyof Phases & string)[]>,
+  PublicSchema,
+  PrivateSchema,
+  HiddenSchema,
+  Phases
+> & {
+  readonly phases: Phases;
+  readonly phaseNames: readonly (keyof Phases & string)[];
+  /**
+   * Ergonomic shortcut to the manifest-backed Zod id schemas. Equivalent to
+   * `definition.manifest.ids`. Prefer `gameContract.schemas.playerId` etc.
+   * over re-importing the generated `ids` namespace so that every authored
+   * schema is anchored to the same SDK-guided source.
+   */
+  readonly schemas: ManifestIdSchemasOf<
+    NarrowManifestPhaseNames<
+      Manifest,
+      readonly (keyof Phases & string)[]
+    >["ids"]
+  >;
+} {
+  validateStateSchemaIdBranding(definition.state.public, "public");
+  validateStateSchemaIdBranding(definition.state.private, "private");
+  validateStateSchemaIdBranding(definition.state.hidden, "hidden");
+  const phaseNames = Object.keys(definition.phases) as (keyof Phases &
+    string)[];
+  if (phaseNames.length === 0) {
+    throw new Error(
+      "defineGameContract: phases must be a non-empty record of phase schemas.",
+    );
+  }
+  for (const name of phaseNames) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new Error(
+        "defineGameContract: phase names must be non-empty strings.",
+      );
+    }
+  }
+  const phaseNameSchema = createManifestStringLiteralSchema(phaseNames);
+  const narrowedManifest = {
+    ...definition.manifest,
+    literals: {
+      ...definition.manifest.literals,
+      phaseNames,
+    },
+    ids: {
+      ...definition.manifest.ids,
+      phaseName: phaseNameSchema,
+    },
+  } as unknown as NarrowManifestPhaseNames<
+    Manifest,
+    readonly (keyof Phases & string)[]
+  >;
+  const contract = {
+    manifest: narrowedManifest,
+    state: definition.state,
+    phases: definition.phases,
+    phaseNames,
+    schemas: narrowedManifest.ids,
+  } as ReducerGameContract<
+    Table,
+    NarrowManifestPhaseNames<Manifest, readonly (keyof Phases & string)[]>,
+    PublicSchema,
+    PrivateSchema,
+    HiddenSchema,
+    Phases
+  > & {
+    readonly phases: Phases;
+    readonly phaseNames: readonly (keyof Phases & string)[];
+    readonly schemas: ManifestIdSchemasOf<
+      NarrowManifestPhaseNames<
+        Manifest,
+        readonly (keyof Phases & string)[]
+      >["ids"]
+    >;
+  };
+  return contract;
+}

package/src/reducer/authoring/effect.ts

@@ -0,0 +1,224 @@
+import { z } from "zod";
+import type {
+  AnySchema,
+  ContinuationCallable,
+  EffectRollDieDefinition,
+  EffectShuffleDefinition,
+  EffectShufflePlayerZoneDefinition,
+  ResumableEffectKind,
+} from "../model";
+import type {
+  AnyReducerGameContract,
+  ContractManifest,
+  ContractState,
+} from "./types";
+
+function createContinuationCallable<
+  DataSchema extends AnySchema,
+  ResponseSchema extends AnySchema,
+  State extends {
+    table: import("../model").RuntimeTableRecord;
+    flow: { currentPhase: string };
+  },
+  Manifest extends import("../model").ManifestContract<
+    import("../model").TableOfState<State>
+  >,
+  EffectType extends ResumableEffectKind = ResumableEffectKind,
+>(definition: {
+  id: string;
+  data: DataSchema;
+  response: ResponseSchema;
+  effectKind?: EffectType;
+  reduce: ContinuationCallable<
+    DataSchema,
+    State,
+    Manifest,
+    string,
+    EffectType
+  >["reduce"];
+}): ContinuationCallable<DataSchema, State, Manifest, string, EffectType> {
+  const continuation = ((data: z.infer<DataSchema>) => {
+    return {
+      id: continuation.id,
+      data,
+    };
+  }) as ContinuationCallable<DataSchema, State, Manifest, string, EffectType>;
+  continuation.id = definition.id;
+  continuation.source = "effect";
+  continuation.dataSchema = definition.data;
+  continuation.responseSchema = definition.response;
+  continuation.reduce = definition.reduce;
+  if (definition.effectKind !== undefined) {
+    continuation.effectKind = definition.effectKind;
+  }
+  return continuation;
+}
+
+// --- `defineEffect` ---
+//
+// Authoring factory for engine-side resumable effects (cues). An effect
+// is the registered bundle of continuation callable + optional reduce,
+// discriminated by `type` which aligns directly with `ResumableEffectKind`:
+//
+//   defineEffect<GameContract>()({ type: "rollDie",            id, context?, reduce? })
+//   defineEffect<GameContract>()({ type: "shuffleSharedZone",  id, context?, reduce? })
+//
+// Authored effects are registered under `phase.effects` and invoked from
+// a reducer via `fx.effect(effect, options)`. The wire protocol already
+// isolates the continuation payload into the ingress bundle's
+// `continuations` map keyed by `effectId`, so `fx.effect` never attaches
+// `resume: undefined` to the wire effect.
+//
+// Addressed player requests are *not* effects. Author them as
+// prompt-kind interactions via `defineInteraction({ kind: "prompt",
+// to, options, ... })`.
+
+type EffectRollDieInput<
+  Contract extends AnyReducerGameContract,
+  Id extends string,
+  ContextSchema extends AnySchema,
+> = {
+  type: "rollDie";
+  id: Id;
+  context?: ContextSchema;
+  reduce?: ContinuationCallable<
+    ContextSchema,
+    ContractState<Contract>,
+    ContractManifest<Contract>,
+    Id,
+    "rollDie"
+  >["reduce"];
+};
+
+type EffectShuffleInput<
+  Contract extends AnyReducerGameContract,
+  Id extends string,
+  ContextSchema extends AnySchema,
+> = {
+  type: "shuffleSharedZone";
+  id: Id;
+  context?: ContextSchema;
+  reduce?: ContinuationCallable<
+    ContextSchema,
+    ContractState<Contract>,
+    ContractManifest<Contract>,
+    Id,
+    "shuffleSharedZone"
+  >["reduce"];
+};
+
+type EffectShufflePlayerZoneInput<
+  Contract extends AnyReducerGameContract,
+  Id extends string,
+  ContextSchema extends AnySchema,
+> = {
+  type: "shufflePlayerZone";
+  id: Id;
+  context?: ContextSchema;
+  reduce?: ContinuationCallable<
+    ContextSchema,
+    ContractState<Contract>,
+    ContractManifest<Contract>,
+    Id,
+    "shufflePlayerZone"
+  >["reduce"];
+};
+
+export function defineEffect<Contract extends AnyReducerGameContract>() {
+  type EffectInput =
+    | EffectRollDieInput<Contract, string, AnySchema>
+    | EffectShuffleInput<Contract, string, AnySchema>
+    | EffectShufflePlayerZoneInput<Contract, string, AnySchema>;
+  type EffectOutput =
+    | EffectRollDieDefinition<
+        string,
+        AnySchema,
+        ContractState<Contract>,
+        ContractManifest<Contract>
+      >
+    | EffectShuffleDefinition<
+        string,
+        AnySchema,
+        ContractState<Contract>,
+        ContractManifest<Contract>
+      >
+    | EffectShufflePlayerZoneDefinition<
+        string,
+        AnySchema,
+        ContractState<Contract>,
+        ContractManifest<Contract>
+      >;
+  function effect<
+    Id extends string,
+    ContextSchema extends AnySchema = z.ZodObject<Record<string, never>>,
+  >(
+    definition: EffectRollDieInput<Contract, Id, ContextSchema>,
+  ): EffectRollDieDefinition<
+    Id,
+    ContextSchema,
+    ContractState<Contract>,
+    ContractManifest<Contract>
+  >;
+  function effect<
+    Id extends string,
+    ContextSchema extends AnySchema = z.ZodObject<Record<string, never>>,
+  >(
+    definition: EffectShuffleInput<Contract, Id, ContextSchema>,
+  ): EffectShuffleDefinition<
+    Id,
+    ContextSchema,
+    ContractState<Contract>,
+    ContractManifest<Contract>
+  >;
+  function effect<
+    Id extends string,
+    ContextSchema extends AnySchema = z.ZodObject<Record<string, never>>,
+  >(
+    definition: EffectShufflePlayerZoneInput<Contract, Id, ContextSchema>,
+  ): EffectShufflePlayerZoneDefinition<
+    Id,
+    ContextSchema,
+    ContractState<Contract>,
+    ContractManifest<Contract>
+  >;
+  function effect(definition: EffectInput): EffectOutput {
+    if (
+      definition.type === "rollDie" ||
+      definition.type === "shuffleSharedZone" ||
+      definition.type === "shufflePlayerZone"
+    ) {
+      const effectKind: ResumableEffectKind = definition.type;
+      if (!definition.reduce) {
+        return {
+          type: definition.type,
+          id: definition.id,
+          contextSchema: definition.context,
+        } as EffectOutput;
+      }
+      const contextSchema = (definition.context ?? z.object({})) as AnySchema;
+      const continuation = createContinuationCallable<
+        AnySchema,
+        AnySchema,
+        ContractState<Contract>,
+        ContractManifest<Contract>,
+        ResumableEffectKind
+      >({
+        id: definition.id,
+        data: contextSchema,
+        response: z.unknown() as AnySchema,
+        effectKind,
+        reduce: definition.reduce,
+      });
+      return {
+        type: definition.type,
+        id: definition.id,
+        contextSchema,
+        __continuation: continuation,
+      } as EffectOutput;
+    }
+    throw new Error(
+      `defineEffect: unknown effect definition. Expected type 'rollDie' | 'shuffleSharedZone' | 'shufflePlayerZone'. Addressed prompts are authored as prompt-kind interactions via defineInteraction({ kind: "prompt" }).`,
+    );
+  }
+  return effect;
+}

package/src/reducer/authoring/game.ts

@@ -0,0 +1,23 @@
+import type { PhaseMapOf, ReducerGameDefinition, ViewMapOf } from "../model";
+import type { AnyReducerGameContract } from "./types";
+import {
+  validateDefineGamePhaseNames,
+  validateDefineGameSimultaneousPhases,
+  validateDefineGameZoneWiring,
+} from "./validation";
+
+export function defineGame<
+  const Contract extends AnyReducerGameContract,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract> = Record<string, never>,
+>(
+  definition: { contract: Contract } & Omit<
+    ReducerGameDefinition<NoInfer<Contract>, Definitions, Views>,
+    "contract"
+  >,
+): ReducerGameDefinition<Contract, Definitions, Views> {
+  validateDefineGamePhaseNames(definition);
+  validateDefineGameSimultaneousPhases(definition);
+  validateDefineGameZoneWiring(definition);
+  return definition;
+}

package/src/reducer/authoring/interaction.ts

@@ -0,0 +1,98 @@
+import type {
+  CardActionSpec,
+  InputCollector,
+  InteractionRule,
+  InteractionSpec,
+  PlayerZoneIdOfManifest,
+  ScopedPhaseState,
+} from "../model";
+import type {
+  AnyReducerGameContract,
+  ContractManifest,
+  ContractState,
+  InferPhaseState,
+  PhaseStateInput,
+} from "./types";
+import { validateInteractionLikeDefinition } from "./validation";
+
+export function defineInteraction<
+  Contract extends AnyReducerGameContract,
+  PhaseState extends PhaseStateInput = import("../model").SchemaLike<object>,
+>() {
+  return <Collectors extends Record<string, InputCollector>>(
+    definition: InteractionSpec<
+      Collectors,
+      ScopedPhaseState<ContractState<Contract>, InferPhaseState<PhaseState>>,
+      ContractManifest<Contract>
+    >,
+  ): InteractionSpec<
+    Collectors,
+    ScopedPhaseState<ContractState<Contract>, InferPhaseState<PhaseState>>,
+    ContractManifest<Contract>
+  > => {
+    validateInteractionLikeDefinition(
+      definition as {
+        inputs?: Record<string, InputCollector>;
+        commit?: { mode: string };
+        paramsSchema?: unknown;
+      },
+      "defineInteraction",
+    );
+    return definition;
+  };
+}
+
+export function defineInteractionRule<
+  Contract extends AnyReducerGameContract,
+  PhaseState extends PhaseStateInput = import("../model").SchemaLike<object>,
+>() {
+  return <
+    Collectors extends Record<string, InputCollector> = Record<
+      string,
+      InputCollector
+    >,
+  >(
+    definition: InteractionRule<
+      Collectors,
+      ScopedPhaseState<ContractState<Contract>, InferPhaseState<PhaseState>>,
+      ContractManifest<Contract>
+    >,
+  ): InteractionRule<
+    Collectors,
+    ScopedPhaseState<ContractState<Contract>, InferPhaseState<PhaseState>>,
+    ContractManifest<Contract>
+  > => definition;
+}
+
+export function defineCardAction<
+  Contract extends AnyReducerGameContract,
+  PhaseState extends PhaseStateInput,
+>() {
+  return <
+    Collectors extends Record<string, InputCollector> = Record<string, never>,
+    const PlayFrom extends PlayerZoneIdOfManifest<ContractManifest<Contract>> =
+      PlayerZoneIdOfManifest<ContractManifest<Contract>>,
+  >(
+    definition: CardActionSpec<
+      Collectors,
+      ScopedPhaseState<ContractState<Contract>, InferPhaseState<PhaseState>>,
+      ContractManifest<Contract>,
+      PlayFrom
+    >,
+  ): CardActionSpec<
+    Collectors,
+    ScopedPhaseState<ContractState<Contract>, InferPhaseState<PhaseState>>,
+    ContractManifest<Contract>,
+    PlayFrom
+  > => {
+    validateInteractionLikeDefinition(
+      definition as {
+        inputs?: Record<string, InputCollector>;
+        commit?: { mode: string };
+        paramsSchema?: unknown;
+      },
+      "defineCardAction",
+    );
+    return definition;
+  };
+}