@umicat/platform-sdk 0.1.0 → 0.2.1

package/README.md

@@ -4,10 +4,13 @@ The engine-neutral half of the Umicat game SDK. Identity, cloud saves, shared
 game data, multiplayer rooms, runtime AI, voice input and scripted dialogue —
 none of which care how pixels get on screen.
 
-**Status: extracted and verified, not yet adopted.** `@umicat/phaser-sdk` still
-ships its own copies; the swap is proven safe by `scripts/verify-swap.mjs` but
-has not been applied, because applying it requires publishing this package to
-npm first. Nothing in production consumes this yet.
+**Status: adopted.** `@umicat/phaser-sdk@1.0.91` consumes this package — the
+platform code exists in one place again. `@umicat/three-sdk` consumes it too.
+
+`scripts/verify-swap.mjs` is now a regression guard rather than a migration
+plan: it still copies both repos to scratch, applies the swap from scratch, and
+asserts the Phaser SDK exports the same 105 names and passes its whole suite.
+Run it after changing anything in here.
 
 ## Why it exists
 

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { UmicatCore } from './core/UmicatCore.js';
 export type { UmicatInitOptions } from './core/UmicatCore.js';
+export { ORIENTATION_DIMENSIONS } from './orientation.js';
+export type { Orientation } from './orientation.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';
 export { PostMessageTransport } from './core/transports/PostMessageTransport.js';

package/dist/index.js

@@ -4,6 +4,7 @@
 // three.js, or by something we have not chosen yet. Anything that needs to
 // know how pixels get on screen belongs in a runtime package, not here.
 export { UmicatCore } from './core/UmicatCore.js';
+export { ORIENTATION_DIMENSIONS } from './orientation.js';
 export { RpcError } from './core/Transport.js';
 export { PostMessageTransport } from './core/transports/PostMessageTransport.js';
 export { LocalStorageTransport } from './core/transports/LocalStorageTransport.js';

package/dist/orientation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The canvas shape a game is authored for.
+ *
+ * Platform data, not engine data: it is the contract between the host surface
+ * and the game about what shape the play area is, and it reads the same whether
+ * the game is drawn by Phaser, by three.js, or by something later. The value is
+ * chosen at game creation and is immutable afterwards — every scene is laid out
+ * against it, so switching mid-development breaks layouts.
+ *
+ * `@umicat/phaser-sdk` still carries its own copy of these six lines (it
+ * predates this package). Consolidating it there is a safe cleanup for whenever
+ * that package is next touched; it is frozen data, so the drift risk is low.
+ */
+export type Orientation = 'portrait' | 'landscape';
+export declare const ORIENTATION_DIMENSIONS: Record<Orientation, {
+    width: number;
+    height: number;
+}>;

package/dist/orientation.js

@@ -0,0 +1,4 @@
+export const ORIENTATION_DIMENSIONS = {
+    landscape: { width: 1280, height: 720 },
+    portrait: { width: 720, height: 1280 },
+};

package/dist/protocol.d.ts

@@ -202,6 +202,20 @@ export interface AiActSuccess {
 export interface AiActFailure {
     ok: false;
     reason: AiReason;
+    /**
+     * The platform's own sentence about why, when it has one worth reading.
+     *
+     * Set by the host for a deliberate 4xx the backend explained — today that
+     * is overwhelmingly `UNAVAILABLE` from a 403 because the game has not
+     * declared the `ai` capability in its Settings. It exists because the
+     * reason codes are for the GAME to branch on, and none of them can tell a
+     * creator what to go and fix.
+     *
+     * Human-readable, English, written by the platform for the person holding
+     * the device — not localized, not a stable identifier, and never something
+     * to branch on. Show it when you have nothing better to say.
+     */
+    detail?: string;
 }
 export type AiActResult = AiActSuccess | AiActFailure;
 export interface AiCompleteParams {
@@ -225,6 +239,8 @@ export interface AiCompleteSuccess {
 export interface AiCompleteFailure {
     ok: false;
     reason: AiReason;
+    /** As `AiActFailure.detail`. */
+    detail?: string;
 }
 export type AiCompleteResult = AiCompleteSuccess | AiCompleteFailure;
 export interface RealtimeGetTokenParams {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/platform-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Umicat's platform layer, independent of any rendering engine: identity, cloud saves, shared game data, multiplayer, runtime AI, voice and scripted dialogue. Consumed by @umicat/phaser-sdk and @umicat/three-sdk alike.",
   "type": "module",
   "main": "dist/index.js",
@@ -45,4 +45,4 @@
     "type": "git",
     "url": "umicat-platform-sdk"
   }
-}
+}