@dreamboard-games/sdk 0.4.0-alpha.5 → 0.4.0-alpha.7

package/dist/{chunk-K5ZRJTZZ.js → chunk-3QIZKXJ2.js}

@@ -1,12 +1,14 @@
 import {
-  HostToPluginEnvelopeSchema,
   InteractionUiProvider,
   PluginGameplayFrameProvider,
   PluginSessionProvider,
   RuntimeContext,
-  RuntimeJsonSchema,
   usePluginSession
-} from "./chunk-O6M6PN4E.js";
+} from "./chunk-VLG4YST5.js";
+import {
+  HostToPluginEnvelopeSchema,
+  RuntimeJsonSchema
+} from "./chunk-5IHU5CUK.js";
 
 // src/runtime/core/create-plugin-runtime-client.ts
 var defaultClock = {
@@ -85,7 +87,10 @@ function createPluginRuntimeClient(options) {
     }
     const parseResult = HostToPluginEnvelopeSchema.safeParse(rawMessage);
     if (!parseResult.success) {
-      sendRuntimeError("Invalid host-to-plugin protocol envelope.", "invalid-envelope");
+      sendRuntimeError(
+        "Invalid host-to-plugin protocol envelope.",
+        "invalid-envelope"
+      );
       return;
     }
     const message = parseResult.data;
@@ -325,4 +330,4 @@ export {
   createPluginRuntimeClient,
   PluginRuntimeBoundary
 };
-//# sourceMappingURL=chunk-K5ZRJTZZ.js.map
+//# sourceMappingURL=chunk-3QIZKXJ2.js.map

package/dist/chunk-3QIZKXJ2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/core/create-plugin-runtime-client.ts","../src/runtime/components/PluginRuntimeBoundary.tsx"],"sourcesContent":["import {\n  HostToPluginEnvelopeSchema,\n  RuntimeJsonSchema,\n  type HostToPluginEnvelope,\n  type PluginGameplayFrame,\n  type PluginInteractionBasis,\n  type PluginSessionDescriptor,\n  type SubmissionResult,\n  type ValidationResult,\n} from \"@dreamboard-games/plugin-runtime-contract\";\nimport type {\n  PluginRuntimeClient,\n  PluginRuntimeClientOptions,\n  RuntimeClock,\n  RuntimeIdFactory,\n} from \"./types.js\";\n\nconst defaultClock: RuntimeClock = {\n  now: () => Date.now(),\n};\n\nconst defaultIdFactory: RuntimeIdFactory = {\n  nextId: (prefix) => {\n    const cryptoLike = (\n      globalThis as typeof globalThis & {\n        crypto?: { randomUUID?: () => string };\n      }\n    ).crypto;\n    if (cryptoLike?.randomUUID) {\n      try {\n        return `${prefix}-${cryptoLike.randomUUID()}`;\n      } catch {\n        // Fall through to deterministic-enough fallback for older test DOMs.\n      }\n    }\n    return `${prefix}-${Date.now().toString(16)}-${Math.random()\n      .toString(16)\n      .slice(2)}`;\n  },\n};\n\nfunction createSubmissionError(\n  result: Extract<SubmissionResult, { accepted: false }>,\n): Error & { errorCode?: string } {\n  const error = new Error(result.message ?? \"Submission failed\") as Error & {\n    errorCode?: string;\n  };\n  error.name = \"SubmissionError\";\n  error.errorCode = result.errorCode;\n  return error;\n}\n\nfunction disconnectedValidationResult(): ValidationResult {\n  return {\n    valid: false,\n    errorCode: \"runtime-disconnected\",\n    message: \"Plugin runtime disconnected\",\n  };\n}\n\nexport function createPluginRuntimeClient(\n  options: PluginRuntimeClientOptions,\n): PluginRuntimeClient {\n  const clock = options.clock ?? defaultClock;\n  const idFactory = options.idFactory ?? defaultIdFactory;\n  const requestTimeoutMs = options.requestTimeoutMs ?? 10_000;\n  let session: PluginSessionDescriptor | null = null;\n  let frame: PluginGameplayFrame | null = null;\n  let disconnected = false;\n  let stopTransport: (() => void) | undefined;\n  const sessionListeners = new Set<() => void>();\n  const frameListeners = new Set<() => void>();\n  const pendingValidations = new Map<\n    string,\n    (result: ValidationResult) => void\n  >();\n  const pendingSubmissions = new Map<\n    string,\n    {\n      resolve: () => void;\n      reject: (error: Error & { errorCode?: string }) => void;\n    }\n  >();\n\n  const notifySession = () => {\n    for (const listener of sessionListeners) {\n      listener();\n    }\n  };\n\n  const notifyFrame = () => {\n    for (const listener of frameListeners) {\n      listener();\n    }\n  };\n\n  const currentBasis = (): PluginInteractionBasis => {\n    if (!frame) {\n      throw new Error(\"Plugin runtime has not received a gameplay frame.\");\n    }\n    return {\n      gameVersion: frame.gameVersion,\n      actionSetVersion: frame.actionSetVersion,\n      perspectivePlayerId: frame.perspectivePlayerId,\n    };\n  };\n\n  const sendRuntimeError = (message: string, code?: string) => {\n    if (disconnected) {\n      return;\n    }\n    options.transport.send({\n      type: \"runtime.error\",\n      message,\n      ...(code ? { code } : {}),\n    });\n  };\n\n  const handleHostMessage = (rawMessage: HostToPluginEnvelope) => {\n    if (disconnected) {\n      return;\n    }\n    const parseResult = HostToPluginEnvelopeSchema.safeParse(rawMessage);\n    if (!parseResult.success) {\n      sendRuntimeError(\n        \"Invalid host-to-plugin protocol envelope.\",\n        \"invalid-envelope\",\n      );\n      return;\n    }\n    const message = parseResult.data;\n    const clientReceivedAtMs = clock.now();\n\n    switch (message.payload.type) {\n      case \"runtime.init\": {\n        session = message.payload.session;\n        notifySession();\n        options.transport.send({ type: \"runtime.ready\" });\n        options.transport.send({\n          type: \"runtime.ack\",\n          sequence: message.sequence,\n          clientReceivedAtMs,\n        });\n        break;\n      }\n      case \"gameplay.frame\": {\n        frame = message.payload.frame;\n        notifyFrame();\n        const sendRenderedAck = () => {\n          if (disconnected) {\n            return;\n          }\n          options.transport.send({\n            type: \"runtime.ack\",\n            sequence: message.sequence,\n            clientReceivedAtMs,\n            clientRenderedAtMs: clock.now(),\n          });\n        };\n        if (typeof requestAnimationFrame === \"function\") {\n          requestAnimationFrame(sendRenderedAck);\n        } else {\n          queueMicrotask(sendRenderedAck);\n        }\n        break;\n      }\n      case \"interaction.validation-result\": {\n        const resolve = pendingValidations.get(message.payload.requestId);\n        if (resolve) {\n          pendingValidations.delete(message.payload.requestId);\n          resolve(message.payload.result);\n        }\n        break;\n      }\n      case \"interaction.submit-result\": {\n        const pending = pendingSubmissions.get(message.payload.requestId);\n        if (!pending) {\n          break;\n        }\n        pendingSubmissions.delete(message.payload.requestId);\n        if (message.payload.result.accepted) {\n          pending.resolve();\n        } else {\n          pending.reject(createSubmissionError(message.payload.result));\n        }\n        break;\n      }\n      default: {\n        const _exhaustive: never = message.payload;\n        return _exhaustive;\n      }\n    }\n  };\n\n  stopTransport = options.transport.start(handleHostMessage);\n\n  const rejectPending = () => {\n    for (const resolve of pendingValidations.values()) {\n      resolve(disconnectedValidationResult());\n    }\n    pendingValidations.clear();\n    for (const pending of pendingSubmissions.values()) {\n      const error = new Error(\"Plugin runtime disconnected\") as Error & {\n        errorCode?: string;\n      };\n      error.name = \"SubmissionError\";\n      error.errorCode = \"runtime-disconnected\";\n      pending.reject(error);\n    }\n    pendingSubmissions.clear();\n  };\n\n  return {\n    getSession: () => session,\n    subscribeSession: (listener) => {\n      sessionListeners.add(listener);\n      return () => {\n        sessionListeners.delete(listener);\n      };\n    },\n    getFrame: () => frame,\n    subscribeFrame: (listener) => {\n      frameListeners.add(listener);\n      return () => {\n        frameListeners.delete(listener);\n      };\n    },\n    validateInteraction: async (interactionId, params) =>\n      new Promise((resolve) => {\n        if (disconnected) {\n          resolve(disconnectedValidationResult());\n          return;\n        }\n        let basis: PluginInteractionBasis;\n        try {\n          basis = currentBasis();\n        } catch (error) {\n          resolve({\n            valid: false,\n            errorCode: \"runtime-not-ready\",\n            message:\n              error instanceof Error\n                ? error.message\n                : \"Plugin runtime is not ready.\",\n          });\n          return;\n        }\n        const parsedParams = RuntimeJsonSchema.safeParse(params);\n        if (!parsedParams.success) {\n          resolve({\n            valid: false,\n            errorCode: \"invalid-runtime-json\",\n            message: \"Interaction params must be runtime JSON.\",\n          });\n          return;\n        }\n        const requestId = idFactory.nextId(\"validate\");\n        pendingValidations.set(requestId, resolve);\n        options.transport.send({\n          type: \"interaction.validate\",\n          requestId,\n          basis,\n          interactionId,\n          params: parsedParams.data,\n        });\n        setTimeout(() => {\n          if (!pendingValidations.delete(requestId)) {\n            return;\n          }\n          resolve({\n            valid: false,\n            errorCode: \"validation-timeout\",\n            message: \"Validation request timed out\",\n          });\n        }, requestTimeoutMs);\n      }),\n    submitInteraction: async (interactionId, params) =>\n      new Promise((resolve, reject) => {\n        if (disconnected) {\n          const error = new Error(\"Plugin runtime disconnected\") as Error & {\n            errorCode?: string;\n          };\n          error.name = \"SubmissionError\";\n          error.errorCode = \"runtime-disconnected\";\n          reject(error);\n          return;\n        }\n        const parsedParams = RuntimeJsonSchema.safeParse(params);\n        if (!parsedParams.success) {\n          const error = new Error(\n            \"Interaction params must be runtime JSON.\",\n          ) as Error & { errorCode?: string };\n          error.name = \"SubmissionError\";\n          error.errorCode = \"invalid-runtime-json\";\n          reject(error);\n          return;\n        }\n        let basis: PluginInteractionBasis;\n        try {\n          basis = currentBasis();\n        } catch (error) {\n          const submissionError = new Error(\n            error instanceof Error\n              ? error.message\n              : \"Plugin runtime is not ready.\",\n          ) as Error & { errorCode?: string };\n          submissionError.name = \"SubmissionError\";\n          submissionError.errorCode = \"runtime-not-ready\";\n          reject(submissionError);\n          return;\n        }\n        const requestId = idFactory.nextId(\"submit\");\n        pendingSubmissions.set(requestId, { resolve, reject });\n        options.transport.send({\n          type: \"interaction.submit\",\n          requestId,\n          basis,\n          interactionId,\n          params: parsedParams.data,\n        });\n        setTimeout(() => {\n          const pending = pendingSubmissions.get(requestId);\n          if (!pending) {\n            return;\n          }\n          pendingSubmissions.delete(requestId);\n          const error = new Error(\"Submission request timed out\") as Error & {\n            errorCode?: string;\n          };\n          error.name = \"SubmissionError\";\n          error.errorCode = \"submission-timeout\";\n          pending.reject(error);\n        }, requestTimeoutMs);\n      }),\n    disconnect: () => {\n      disconnected = true;\n      stopTransport?.();\n      stopTransport = undefined;\n      sessionListeners.clear();\n      frameListeners.clear();\n      rejectPending();\n      session = null;\n      frame = null;\n    },\n  };\n}\n","import React, { useMemo } from \"react\";\nimport { InteractionUiProvider } from \"../context/InteractionDraftContext.js\";\nimport {\n  PluginSessionProvider,\n  usePluginSession,\n} from \"../context/PluginSessionContext.js\";\nimport { PluginGameplayFrameProvider } from \"../context/PluginGameplayFrameContext.js\";\nimport { RuntimeContext } from \"../context/RuntimeContext.js\";\nimport type { PluginRuntimeClient } from \"../core/types.js\";\nimport type { RuntimeAPI } from \"../types/runtime-api.js\";\n\nfunction runtimeApiFromClient(runtime: PluginRuntimeClient): RuntimeAPI {\n  return {\n    validateInteraction: (interactionId, params) =>\n      runtime.validateInteraction(interactionId, params),\n    submitInteraction: (interactionId, params) =>\n      runtime.submitInteraction(interactionId, params),\n    getSessionState: () => {\n      const session = runtime.getSession();\n      const frame = runtime.getFrame();\n      return {\n        status: session ? \"ready\" : \"loading\",\n        sessionId: session?.sessionId ?? null,\n        controllingPlayerId: frame?.perspectivePlayerId ?? null,\n      };\n    },\n    disconnect: () => runtime.disconnect(),\n  };\n}\n\nexport function PluginRuntimeBoundary({\n  runtime,\n  children,\n}: {\n  runtime: PluginRuntimeClient;\n  children: React.ReactNode;\n}) {\n  const runtimeApi = useMemo(() => runtimeApiFromClient(runtime), [runtime]);\n\n  return (\n    <RuntimeContext.Provider value={runtimeApi}>\n      <PluginSessionProvider runtime={runtime}>\n        <PluginGameplayFrameProvider runtime={runtime}>\n          <SessionScopedInteractionUiProvider>\n            {children}\n          </SessionScopedInteractionUiProvider>\n        </PluginGameplayFrameProvider>\n      </PluginSessionProvider>\n    </RuntimeContext.Provider>\n  );\n}\n\nfunction SessionScopedInteractionUiProvider({\n  children,\n}: {\n  children: React.ReactNode;\n}) {\n  const { controllingPlayerId } = usePluginSession();\n  return (\n    <InteractionUiProvider key={controllingPlayerId ?? \"__no_player__\"}>\n      {children}\n    </InteractionUiProvider>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-KHY3RJLT.js → chunk-52DH7VQF.js}

@@ -1117,6 +1117,10 @@ function collectManifestRecordKeyIssues(manifest) {
           value: profile.id,
           path: `manifest.setupProfiles[${profileIndex}].id`
         },
+        ...(profile.guidance?.steps ?? []).map((step, stepIndex) => ({
+          value: step.id,
+          path: `manifest.setupProfiles[${profileIndex}].guidance.steps[${stepIndex}].id`
+        })),
         ...Object.entries(profile.optionValues ?? {}).flatMap(
           ([optionId, choiceId]) => [
             {
@@ -1287,6 +1291,17 @@ function validateManifestAuthoring(manifest) {
       label: "setup profile id"
     })
   );
+  for (const [profileIndex, profile] of (manifest.setupProfiles ?? []).entries()) {
+    errors.push(
+      ...collectDuplicateIdIssues({
+        entries: (profile.guidance?.steps ?? []).map((step, stepIndex) => ({
+          id: step.id,
+          path: `manifest.setupProfiles[${profileIndex}].guidance.steps[${stepIndex}].id`
+        })),
+        label: `setup profile '${profile.id}' guidance step id`
+      })
+    );
+  }
   errors.push(...validateSlotHostsAndHomes(manifest));
   errors.push(...validatePlayerScopedSeedHomes(manifest));
   errors.push(...validateCardHomes(manifest));
@@ -2604,7 +2619,15 @@ function analyzeManifest(inputManifest) {
           Object.entries(profile.optionValues).filter(
             (entry) => typeof entry[1] === "string"
           )
-        ) : null
+        ) : null,
+        guidance: profile.guidance ? {
+          summary: profile.guidance.summary ?? null,
+          steps: (profile.guidance.steps ?? []).map((step) => ({
+            id: step.id,
+            label: step.label,
+            description: step.description ?? null
+          }))
+        } : null
       }
     ])
   );
@@ -7075,11 +7098,15 @@ import {
   type BoardSpaceIdOf,
   type InteractionVisualState,
 } from "@dreamboard-games/sdk/ui";
-import { type InteractionDescriptor } from "@dreamboard-games/sdk/runtime";
+import {
+  type BoardGridInteractionFilter,
+  type InteractionDescriptor,
+} from "@dreamboard-games/sdk/runtime";
 import {
   createWorkspaceUIContract,
   type BoardHexGridProps as BoardHexGridPropsGeneric,
   type BoardHexViewProps as BoardHexViewPropsGeneric,
+  type BoardSquareGridProps as BoardSquareGridPropsGeneric,
   type BoardSpaceTargetProps as BoardSpaceTargetPropsGeneric,
   type ClientParamSchemaMap,
   type DefineGameUIConfig,
@@ -7321,7 +7348,7 @@ export type RequiredInteractionInputKey<Key extends InteractionKey> =
   RequiredInteractionInputKeysOf<Key>;
 
 type InteractionSlotComponent<Props = object> = (
-  props: Props extends { children: unknown }
+  props: Props extends { children?: unknown }
     ? Props
     : Props & { children?: ReactNode },
 ) => ReactElement | null;
@@ -7867,12 +7894,7 @@ type HandComponent<
   Vertex extends string,
 > = InteractionSlotComponent<
   Omit<HandSurfaceProps<Card, Space, Edge, Vertex>, "children"> & {
-    children:
-      | ReactNode
-      | ((
-          card: WorkspaceZoneCard,
-          state: InteractionVisualState,
-        ) => ReactNode);
+    children: ReactNode;
   }
 >;
 
@@ -8052,17 +8074,31 @@ declare module "@dreamboard-games/sdk/runtime" {
 /** Generated hex-board topology source, keyed by hex-board id. */
 const hexStaticBoards = staticBoards.hex;
 
+/** Generated square-board topology source, keyed by square-board id. */
+const squareStaticBoards = staticBoards.square;
+
 /** Union of authored hex-board ids in this workspace's manifest. */
 export type HexBoardId = keyof typeof hexStaticBoards & string;
 
+/** Union of authored square-board ids in this workspace's manifest. */
+export type SquareBoardId = keyof typeof squareStaticBoards & string;
+
 /** Topology object for the named hex board, drawn from \`staticBoards.hex\`. */
 export type HexBoardTopology<Id extends HexBoardId> = (typeof hexStaticBoards)[Id];
 
+/** Topology object for the named square board, drawn from \`staticBoards.square\`. */
+export type SquareBoardTopology<Id extends SquareBoardId> = (typeof squareStaticBoards)[Id];
+
 /** Space id type for the named hex board. */
 export type HexBoardSpaceId<Id extends HexBoardId> = BoardSpaceIdOf<
   HexBoardTopology<Id>
 >;
 
+/** Space id type for the named square board. */
+export type SquareBoardSpaceId<Id extends SquareBoardId> = BoardSpaceIdOf<
+  SquareBoardTopology<Id>
+>;
+
 export type HexBoardViewProps<
   Id extends HexBoardId,
   TSpaceView extends { id: HexBoardSpaceId<Id> },
@@ -8080,6 +8116,14 @@ export type HexBoardGridProps<
   board: Id;
 };
 
+export type SquareBoardGridProps<Id extends SquareBoardId> = Omit<
+  BoardSquareGridPropsGeneric<SquareBoardTopology<Id>>,
+  "board" | "interactions"
+> & {
+  board: Id;
+  interactions?: BoardGridInteractionFilter<InteractionKey>;
+};
+
 type WorkspaceBoard = {
   surface<const Board extends BoardSurfaceBoardId>(
     board: Board,
@@ -8097,6 +8141,9 @@ type WorkspaceBoard = {
     const Id extends HexBoardId,
     const TSpaceView extends { id: HexBoardSpaceId<Id> },
   >(props: HexBoardGridProps<Id, TSpaceView>): ReactElement;
+  SquareGrid<const Id extends SquareBoardId>(
+    props: SquareBoardGridProps<Id>,
+  ): ReactElement;
 };
 
 type WorkspaceCardProperties = CardProperties extends Record<string, unknown>
@@ -8257,7 +8304,8 @@ export const UI = createWorkspaceUIContract<
   typeof uiContract,
   ResourceId,
   WorkspaceZoneCard,
-  typeof hexStaticBoards
+  typeof hexStaticBoards,
+  typeof squareStaticBoards
 >({
   uiContract,
   clientParamSchemasByPhase: createClientParamSchemasByPhase(game) as ClientParamSchemaMap,
@@ -8267,6 +8315,7 @@ export const UI = createWorkspaceUIContract<
     Record<string, { label?: string; icon?: string }>
   >,
   hexStaticBoards,
+  squareStaticBoards,
   cardIdFromZoneCard: (card) => card.id,
   zoneIdFromZoneCard: (card) => card.zone,
 });
@@ -8365,7 +8414,7 @@ function generateReducerDerivedSeed() {
 //
 //   reduce({ state, derived, accept }) {
 //     const winner = derived(winnerOf);
-//     return accept({ ...state, publicState: { ...state.publicState, winnerPlayerId: winner } });
+//     return accept({ ...state, publicState: { ...state.publicState, currentLeaderId: winner } });
 //   }
 //
 // Do NOT mirror derived values back into \`publicState\`. Keep the raw
@@ -8381,7 +8430,7 @@ function generateReducerDerivedSeed() {
 //   name: "winnerOf",
 //   compute: ({ state }) => {
 //     // Example: return the first player at or above the VP target.
-//     return state.publicState.winnerPlayerId ?? null;
+//     return state.publicState.currentLeaderId ?? null;
 //   },
 // });
 
@@ -8792,4 +8841,4 @@ export {
   generateAuthoritativeFiles,
   generateDynamicGeneratedFiles
 };
-//# sourceMappingURL=chunk-KHY3RJLT.js.map
+//# sourceMappingURL=chunk-52DH7VQF.js.map