@anweather/game-plugin-ssdk 1.25.0 → 1.27.0

package/dist-types/runtime/index.d.ts

@@ -6,6 +6,8 @@ export type { ServePluginOptions, PluginServiceDefinition, PluginApp, RunningPlu
 export { createRegistrationLoop } from "./registration";
 export type { RegistrationOptions, RegistrationLoop } from "./registration";
 export { runConformance, assertConformance } from "./conformance";
+export { validatePresentation, assertPresentation, PRESENTATION_CATEGORIES, MAX_PRESENTATION_BYTES } from "./presentation";
+export type { PluginPresentation, PresentationCategory } from "./presentation";
 export type { ConformanceOptions, ConformanceReport } from "./conformance";
 export { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";
 export { createBlobClient, casUpdate, blobOwner, allBlobOwners, BlobStoreError, isVersionConflict } from "./blobClient";

package/dist-types/runtime/presentation.d.ts

@@ -0,0 +1,68 @@
+export declare const PRESENTATION_CATEGORIES: readonly ["classic", "strategy", "cards", "word", "wip"];
+export type PresentationCategory = (typeof PRESENTATION_CATEGORIES)[number];
+/** The platform refuses a registration whose presentation serialises
+ * larger than this. */
+export declare const MAX_PRESENTATION_BYTES: number;
+export interface PluginPresentation {
+    catalogue?: {
+        /** Shown instead of GetMetadata's displayName wherever the platform
+         * names the game (tile, game page, lists). Absent: displayName. */
+        title?: string;
+        /** The catalogue tab the tile lives under. Default "wip". */
+        category?: PresentationCategory;
+        /** Also list the tile under the catalogue's Featured tab. Default false. */
+        featured?: boolean;
+        /** The tile's gradient, top-left to bottom-right, and its text colour,
+         * as Tailwind palette tokens ("amber-700", or "white"/"black"). Absent: a neutral slate. */
+        poster?: {
+            from: string;
+            to: string;
+            text: string;
+        };
+    };
+    /** "How to play", one entry per bullet. */
+    rules?: string[];
+    board?: {
+        /** "fullscreen" (default): edge to edge, the platform's chrome in a
+         * corner menu. "page": a card on the game page, with `page` options. */
+        layout?: "fullscreen" | "page";
+        /** Only read for layout "page". nameplates: "split" (default; opponents
+         * above, you below), "below" (everyone under the board) or "none" (the
+         * board draws its own). fullBleed: no padding around the board. */
+        page?: {
+            nameplates?: "split" | "below" | "none";
+            fullBleed?: boolean;
+        };
+        /** Who shows a refused move. "platform" (default): a banner. "board":
+         * the move promise rejects and the board shows it -- only for a board
+         * that actually catches it, or the player sees nothing at all. */
+        moveErrors?: "platform" | "board";
+        /** The browser's own long press (callout, magnifier, context menu,
+         * text selection) over the board. Default: "suppress" in full screen,
+         * "allow" on a page. "allow" is the opt-out for copyable text. */
+        nativeGestures?: "suppress" | "allow";
+        /** The Recap button. Absent or false (default): no recap. An object
+         * turns it on; stepMs holds each replayed state (default 900). Only
+         * for a board that animates the change between consecutive views. */
+        recap?: false | {
+            stepMs?: number;
+        };
+        /** The ShadowMount host box. overflowX default "auto", width default
+         * "fit". */
+        host?: {
+            overflowX?: "auto" | "hidden" | "clip";
+            width?: "fit" | "full";
+        };
+    };
+    /** A two-seat game whose seats have names (chess: ["White", "Black"]):
+     * the sole winner picks their seat for the rematch. */
+    rematch?: {
+        seatNames: [string, string];
+    };
+}
+/** Every problem with `value` as a presentation, strictest reading: wrong
+ * types, unknown enum values, and unknown fields. Empty means valid. */
+export declare function validatePresentation(value: unknown): string[];
+/** validatePresentation, throwing the whole list. servePlugin calls this at
+ * startup, so a bad presentation fails the container, not the platform. */
+export declare function assertPresentation(value: unknown): asserts value is PluginPresentation;

package/dist-types/runtime/servePlugin.d.ts

@@ -5,6 +5,7 @@ import type { GamePluginService, GamePluginServiceOperations } from "../src/serv
 import type { OptionalGamePluginService, RequiredGamePluginService } from "./defaultService";
 import { type RegistrationLoop } from "./registration";
 import { type LiveServer } from "./live/server";
+import { type PluginPresentation } from "./presentation";
 import type { LiveOptions } from "./live/rooms";
 /** What a plugin supplies: every operation createGamePluginService requires,
  * except Health, which servePlugin answers itself unless overridden. */
@@ -47,6 +48,12 @@ export interface ServePluginOptions<Context = Record<string, never>> {
      * platform opens one room link per active channel to /v1/live on this
      * same server, behind the same X-Plugin-Auth token. Absent: no /v1/live. */
     live?: LiveOptions;
+    /** How the platform's frontend shows this game type (catalogue tile,
+     * rules, board layout): added to GetMetadata as `presentation` unless
+     * the service's own GetMetadata already sets one. Checked strictly at
+     * startup (validatePresentation), so a bad one fails this container
+     * rather than reaching the platform. See ./presentation.ts. */
+    presentation?: PluginPresentation;
 }
 export interface PluginApp {
     app: Express;

package/dist-types/src/models/models_0.d.ts

@@ -289,6 +289,7 @@ export interface GameTypeMetadata {
      * @public
      */
     live?: LiveCapability | undefined;
+    presentation?: __DocumentType | undefined;
 }
 export declare namespace GameTypeMetadata {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@anweather/game-plugin-ssdk",
     "description": "Generated GamePlugin RPC types/server (plugin-protocol/model/game-plugin.smithy) plus a hand-written Express bridge and default-handler wrapper (./runtime) -- see plugin-protocol/CLAUDE.md's \"Publishing for cross-repo plugins\".",
-    "version": "1.25.0",
+    "version": "1.27.0",
     "scripts": {
         "build": "concurrently 'npm:build:cjs' 'npm:build:es' 'npm:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",