@dreamboard-games/sdk 0.4.0-alpha.1 → 0.4.0-alpha.2

package/dist/{chunk-XXBSIPJX.js → chunk-CP35NPPY.js}

@@ -13,7 +13,7 @@ function createStringPropertySchema(description) {
     description
   };
 }
-function createStandard52CardDeck() {
+function createStandard52CardDeck(defaultHome = { type: "detached" }) {
   const suits = ["SPADES", "HEARTS", "CLUBS", "DIAMONDS"];
   const ranks = [
     "3",
@@ -51,6 +51,7 @@ function createStandard52CardDeck() {
     id: STANDARD_DECK_ID,
     name: "Standard 52-Card Deck",
     type: "manual",
+    defaultHome,
     cards,
     cardSchema: {
       properties: {
@@ -68,7 +69,7 @@ function addStandardDecksIfNeeded(manifest) {
     ...manifest,
     cardSets: manifest.cardSets.map(
       (cardSet) => cardSet.type === "preset" && cardSet.presetId === STANDARD_DECK_ID ? {
-        ...createStandard52CardDeck(),
+        ...createStandard52CardDeck(cardSet.defaultHome),
         id: cardSet.id,
         name: cardSet.name
       } : cardSet
@@ -79,7 +80,7 @@ function materializePresetCardSet(presetCardSet) {
   if (presetCardSet.presetId !== STANDARD_DECK_ID) {
     throw new Error(`Unsupported preset deck: ${presetCardSet.presetId}`);
   }
-  const standardDeck = createStandard52CardDeck();
+  const standardDeck = createStandard52CardDeck(presetCardSet.defaultHome);
   return {
     ...standardDeck,
     id: presetCardSet.id,
@@ -434,6 +435,10 @@ function validateSlotHostsAndHomes(manifest) {
     if (cardSet.type !== "manual") {
       continue;
     }
+    validateHome(
+      cardSet.defaultHome,
+      `manifest.cardSets[${cardSetIndex}].defaultHome`
+    );
     for (const [cardIndex, card] of cardSet.cards.entries()) {
       validateHome(
         card.home,
@@ -526,21 +531,32 @@ function validateCardHomes(manifest) {
     (manifest.zones ?? []).map((zone) => [zone.id, zone.scope])
   );
   for (const [cardSetIndex, cardSet] of manifest.cardSets.entries()) {
-    if (cardSet.type !== "manual") {
+    if (!cardSet.defaultHome) {
+      issues.push(
+        `manifest.cardSets[${cardSetIndex}].defaultHome: ${cardSet.type === "manual" ? "Manual" : "Preset"} card sets must declare defaultHome.`
+      );
       continue;
     }
-    for (const [cardIndex, card] of cardSet.cards.entries()) {
-      const path = `manifest.cardSets[${cardSetIndex}].cards[${cardIndex}].home`;
-      if (card.home?.type === "zone" && zoneScopeById.get(card.home.zoneId) === "perPlayer") {
+    const validateCardHome = (home, path, label) => {
+      if (home?.type === "zone" && zoneScopeById.get(home.zoneId) === "perPlayer") {
         issues.push(
-          `${path}.zoneId: Card '${card.type}' cannot target per-player zone '${card.home.zoneId}' because card inventory has no ownerId. Place it during reducer setup instead.`
+          `${path}.zoneId: ${label} cannot target per-player zone '${home.zoneId}' because card inventory has no ownerId. Place it during reducer setup instead.`
         );
       }
-      if (homeTargetsBoard(card.home) && boardScopeById.get(card.home.boardId) === "perPlayer") {
+      if (homeTargetsBoard(home) && boardScopeById.get(home.boardId) === "perPlayer") {
         issues.push(
-          `${path}.boardId: Card '${card.type}' cannot target per-player board '${card.home.boardId}' because card inventory has no ownerId. Place it during reducer setup instead.`
+          `${path}.boardId: ${label} cannot target per-player board '${home.boardId}' because card inventory has no ownerId. Place it during reducer setup instead.`
         );
       }
+    };
+    validateCardHome(
+      cardSet.defaultHome,
+      `manifest.cardSets[${cardSetIndex}].defaultHome`,
+      `Card set '${cardSet.id}' defaultHome`
+    );
+    for (const [cardIndex, card] of (cardSet.type === "manual" ? cardSet.cards : []).entries()) {
+      const path = `manifest.cardSets[${cardSetIndex}].cards[${cardIndex}].home`;
+      validateCardHome(card.home, path, `Card '${card.type}'`);
     }
   }
   return issues;
@@ -3042,6 +3058,11 @@ ${validation.errors.join("\n")}`
   ]);
   const resolveRuntimeBoardId = (boardBaseId, ownerId, context) => {
     const analyzedBoard = boardAnalysisByBaseId.get(boardBaseId);
+    if (!analyzedBoard) {
+      throw new Error(
+        `${context ?? "Component home"}.boardId: Unknown board '${boardBaseId}'.`
+      );
+    }
     if (analyzedBoard?.board.scope === "perPlayer") {
       if (!ownerId) {
         throw new Error(
@@ -3052,18 +3073,30 @@ ${validation.errors.join("\n")}`
     }
     return boardBaseId;
   };
-  const resolveBoardEdgeId = (boardBaseId, spaceIds) => edgeIdByBoardBaseIdAndSpaces.get(boardBaseId)?.get(boardSpaceRefKey(spaceIds)) ?? boardSpaceRefKey(spaceIds);
-  const resolveBoardVertexId = (boardBaseId, spaceIds) => vertexIdByBoardBaseIdAndSpaces.get(boardBaseId)?.get(boardSpaceRefKey(spaceIds)) ?? boardSpaceRefKey(spaceIds);
-  const assignCardHome = (cardId, home, context) => {
-    if (!home || home.type === "detached") {
-      componentLocations[cardId] = {
-        type: "Detached",
-        position: nextLocationPosition({ type: "Detached" })
-      };
-      return;
+  const resolveBoardEdgeId = (boardBaseId, spaceIds) => {
+    const edgeId = edgeIdByBoardBaseIdAndSpaces.get(boardBaseId)?.get(boardSpaceRefKey(spaceIds));
+    if (!edgeId) {
+      throw new Error(
+        `Unknown edge on board '${boardBaseId}' for spaces [${spaceIds.join(", ")}].`
+      );
+    }
+    return edgeId;
+  };
+  const resolveBoardVertexId = (boardBaseId, spaceIds) => {
+    const vertexId = vertexIdByBoardBaseIdAndSpaces.get(boardBaseId)?.get(boardSpaceRefKey(spaceIds));
+    if (!vertexId) {
+      throw new Error(
+        `Unknown vertex on board '${boardBaseId}' for spaces [${spaceIds.join(", ")}].`
+      );
+    }
+    return vertexId;
+  };
+  const materializeComponentLocation = (home, context) => {
+    if (home.type === "detached") {
+      return { type: "Detached" };
     }
     if (home.type === "slot") {
-      componentLocations[cardId] = {
+      return {
         type: "InSlot",
         host: home.host,
         slotId: home.slotId,
@@ -3073,15 +3106,20 @@ ${validation.errors.join("\n")}`
           slotId: home.slotId
         })
       };
-      return;
     }
     if (home.type === "zone") {
-      if (zoneScopeById.get(home.zoneId) === "perPlayer") {
+      const zoneScope = zoneScopeById.get(home.zoneId);
+      if (!zoneScope) {
+        throw new Error(
+          `${context.path}.zoneId: ${context.label} targets unknown zone '${home.zoneId}'.`
+        );
+      }
+      if (zoneScope === "perPlayer") {
         throw new Error(
           `${context.path}.zoneId: ${context.label} cannot target per-player zone '${home.zoneId}' because card inventory has no ownerId. Place it during reducer setup instead.`
         );
       }
-      componentLocations[cardId] = {
+      return {
         type: "InDeck",
         deckId: home.zoneId,
         playedBy: null,
@@ -3091,7 +3129,6 @@ ${validation.errors.join("\n")}`
           playedBy: null
         })
       };
-      return;
     }
     if (home.type === "space") {
       const boardId = resolveRuntimeBoardId(
@@ -3099,7 +3136,12 @@ ${validation.errors.join("\n")}`
         null,
         `${context.path}.boardId: ${context.label}`
       );
-      componentLocations[cardId] = {
+      if (!analysis.spaceIdsByBoardId.get(home.boardId)?.includes(home.spaceId)) {
+        throw new Error(
+          `${context.path}.spaceId: ${context.label} targets unknown space '${home.spaceId}' on board '${home.boardId}'.`
+        );
+      }
+      return {
         type: "OnSpace",
         boardId,
         spaceId: home.spaceId,
@@ -3109,7 +3151,6 @@ ${validation.errors.join("\n")}`
           spaceId: home.spaceId
         })
       };
-      return;
     }
     if (home.type === "container") {
       const boardId = resolveRuntimeBoardId(
@@ -3117,7 +3158,12 @@ ${validation.errors.join("\n")}`
         null,
         `${context.path}.boardId: ${context.label}`
       );
-      componentLocations[cardId] = {
+      if (!analysis.containerIdsByBoardId.get(home.boardId)?.includes(home.containerId)) {
+        throw new Error(
+          `${context.path}.containerId: ${context.label} targets unknown container '${home.containerId}' on board '${home.boardId}'.`
+        );
+      }
+      return {
         type: "InContainer",
         boardId,
         containerId: home.containerId,
@@ -3127,7 +3173,6 @@ ${validation.errors.join("\n")}`
           containerId: home.containerId
         })
       };
-      return;
     }
     if (home.type === "edge") {
       const boardId = resolveRuntimeBoardId(
@@ -3136,7 +3181,7 @@ ${validation.errors.join("\n")}`
         `${context.path}.boardId: ${context.label}`
       );
       const edgeId = resolveBoardEdgeId(home.boardId, home.ref.spaces);
-      componentLocations[cardId] = {
+      return {
         type: "OnEdge",
         boardId,
         edgeId,
@@ -3146,7 +3191,6 @@ ${validation.errors.join("\n")}`
           edgeId
         })
       };
-      return;
     }
     if (home.type === "vertex") {
       const boardId = resolveRuntimeBoardId(
@@ -3155,7 +3199,7 @@ ${validation.errors.join("\n")}`
         `${context.path}.boardId: ${context.label}`
       );
       const vertexId = resolveBoardVertexId(home.boardId, home.ref.spaces);
-      componentLocations[cardId] = {
+      return {
         type: "OnVertex",
         boardId,
         vertexId,
@@ -3166,6 +3210,10 @@ ${validation.errors.join("\n")}`
         })
       };
     }
+    const exhaustive = home;
+    throw new Error(
+      `Unsupported component home: ${JSON.stringify(exhaustive)}`
+    );
   };
   for (const [cardSetIndex, cardSet] of manifest.cardSets.entries()) {
     const materializedCardSet = materializeCardSet(cardSet);
@@ -3187,10 +3235,15 @@ ${validation.errors.join("\n")}`
             ...card.properties ?? {}
           }
         };
-        assignCardHome(cardId, card.home, {
-          path: `manifest.cardSets[${cardSetIndex}].cards[${cardIndex}].home`,
-          label: `Card '${card.type}' instance ${instanceIndex + 1}`
-        });
+        const resolvedHome = card.home ?? materializedCardSet.defaultHome;
+        const path = card.home === void 0 ? `manifest.cardSets[${cardSetIndex}].defaultHome` : `manifest.cardSets[${cardSetIndex}].cards[${cardIndex}].home`;
+        componentLocations[cardId] = materializeComponentLocation(
+          resolvedHome,
+          {
+            path,
+            label: `Card '${card.type}' instance ${instanceIndex + 1}`
+          }
+        );
       }
     }
   }
@@ -7029,6 +7082,7 @@ import {
   type BoardHexViewProps as BoardHexViewPropsGeneric,
   type BoardSpaceTargetProps as BoardSpaceTargetPropsGeneric,
   type ClientParamSchemaMap,
+  type DefineGameUIConfig,
   type DreamboardUI,
   type GameMeState,
   type GamePlayersState,
@@ -7048,6 +7102,7 @@ import {
   type WorkspaceHandSurfaceDescriptor,
   type WorkspaceHandSurface,
   type WorkspaceInteractionFormDescriptor,
+  type WorkspaceInteractionFormDialogProps,
   type WorkspaceInteractionSlotComponent,
   type WorkspaceInteractionFormsDescriptor,
   type WorkspacePileSurface,
@@ -7606,7 +7661,7 @@ type InteractionInputSlotByCollectorKind<
 export type InteractionFormSurface<Key extends InteractionKey> = {
   readonly Root: InteractionSlotComponent;
   readonly Form: DreamboardUI<typeof uiContract>["Interaction"]["Form"];
-  readonly Dialog: DreamboardUI<typeof uiContract>["Interaction"]["Dialog"];
+  readonly Dialog: (props: WorkspaceInteractionFormDialogProps) => ReactElement | null;
   readonly State: DreamboardUI<typeof uiContract>["Interaction"]["State"];
   readonly Arm: DreamboardUI<typeof uiContract>["Interaction"]["Trigger"];
   readonly Submit: DreamboardUI<typeof uiContract>["Interaction"]["Submit"];
@@ -7750,8 +7805,9 @@ export type HandAuthoredTarget<
 
 /**
  * Summary projected from the live draft for a single hand. Authors render
- * counts and validity hints via \`renderSummary\` or mirror them to outside
- * state via \`onSelectionSummary\`.
+ * counts and validity hints through the compound \`hand.Summary\` and
+ * \`hand.Actions\` slots, or mirror them to outside state via
+ * \`onSelectionSummary\`.
  */
 export type HandSelectionSummary<Card extends string> = {
   readonly selectedCount: number;
@@ -7797,23 +7853,6 @@ export type HandSurfaceProps<
   onCardIntent?: (
     intent: HandCardIntent<Card, HandAuthoredTarget<Card, Space, Edge, Vertex>>,
   ) => void;
-  /**
-   * Render-safe slot for selection summary content. Fires during render
-   * with the latest projected summary so authors can compose count chrome
-   * (e.g. "3 of 5 selected") without owning effect timing. Use
-   * \`onSelectionSummary\` for analytics or external state mirrors that
-   * need an effect.
-   */
-  renderSummary?: (summary: HandSelectionSummary<Card>) => ReactNode;
-  /**
-   * Render-safe slot for the hand's commit/action chrome (e.g. a submit
-   * button for a many-select interaction). Receives the same live summary as
-   * \`renderSummary\`. Rendered below the hand inline on desktop and pinned as a
-   * sticky footer inside the mobile dock, so the action stays reachable while
-   * the hand is docked \u2014 prefer this over anchoring the action elsewhere on
-   * the board, where the dock would otherwise cover it.
-   */
-  renderActions?: (summary: HandSelectionSummary<Card>) => ReactNode;
   /**
    * Optional selection summary observer. Invoked from a layout effect so
    * consumers may safely call \`setState\` in response.
@@ -7821,12 +7860,27 @@ export type HandSurfaceProps<
   onSelectionSummary?: (summary: HandSelectionSummary<Card>) => void;
 };
 
-type HandCardsComponent<
+type HandComponent<
   Card extends string,
   Space extends string,
   Edge extends string,
   Vertex extends string,
-> = InteractionSlotComponent<HandSurfaceProps<Card, Space, Edge, Vertex>>;
+> = InteractionSlotComponent<
+  Omit<HandSurfaceProps<Card, Space, Edge, Vertex>, "children"> & {
+    children: ReactNode;
+  }
+>;
+
+type HandCardsComponent = InteractionSlotComponent<{
+  children: (
+    card: WorkspaceZoneCard,
+    state: InteractionVisualState,
+  ) => ReactNode;
+}>;
+
+type HandSummaryComponent<Card extends string> = InteractionSlotComponent<{
+  children?: ReactNode | ((summary: HandSelectionSummary<Card>) => ReactNode);
+}>;
 
 /**
  * Always-visible staging surface for a many-select card collection (e.g. the
@@ -7849,12 +7903,15 @@ export type HandStagingProps = {
 type HandStagingComponent = InteractionSlotComponent<HandStagingProps>;
 
 export type HandSurface<Zones extends readonly WorkspaceZoneId[] = readonly WorkspaceZoneId[]> = {
-  readonly Hand: HandCardsComponent<
+  readonly Hand: HandComponent<
     CardId & string,
     SpaceId & string,
     EdgeId & string,
     VertexId & string
   >;
+  readonly Cards: HandCardsComponent;
+  readonly Summary: HandSummaryComponent<CardId & string>;
+  readonly Actions: HandSummaryComponent<CardId & string>;
   readonly Card: ZoneCardComponent;
   readonly Staging: HandStagingComponent;
   readonly slot: {
@@ -8137,6 +8194,21 @@ type WorkspaceUI = Omit<
 	  defineSurfaces<const Spec extends WorkspaceSurfaceSpec>(
 	    spec: Spec,
 	  ): () => WorkspaceSurfaceValue<Spec>;
+	  defineGameUI<Surfaces>(
+	    config: DefineGameUIConfig<GameRootState, Surfaces> & {
+	      useSurfaces: () => Surfaces;
+	      interactionRoutes?: (context: {
+	        game: GameRootState;
+	        surfaces: Surfaces;
+	      }) => InteractionRoutes;
+	      phases: {
+	        readonly [Phase in PhaseName]: (context: {
+	          game: GameRootState;
+	          surfaces: Surfaces;
+	        }) => ReactNode;
+	      };
+	    },
+	  ): (props: Omit<UIRootProps, "children">) => ReactElement;
 	  readonly Game: TypedGame<typeof uiContract, GameView, PlayerId, PhaseName>;
 	  readonly Interaction: Pick<DreamboardUI<typeof uiContract>["Interaction"], "State" | "Dialog"> & {
 	    useForm<Key extends InteractionKey>(interaction: Key): InteractionFormSurface<Key>;
@@ -8715,4 +8787,4 @@ export {
   generateAuthoritativeFiles,
   generateDynamicGeneratedFiles
 };
-//# sourceMappingURL=chunk-XXBSIPJX.js.map
+//# sourceMappingURL=chunk-CP35NPPY.js.map