@umicat/platform-sdk 0.2.2 → 0.3.0

package/dist/core/UmicatCore.d.ts

@@ -5,6 +5,7 @@ import { RealtimeModule } from '../realtime/RealtimeModule.js';
 import { AiModule } from '../ai/AiModule.js';
 import { PlatformModule } from '../platform/PlatformModule.js';
 import { VoiceModule } from '../voice/VoiceModule.js';
+import { FoldModule } from '../fold/FoldModule.js';
 import type { UmicatUser } from '../protocol.js';
 export interface UmicatInitOptions {
     /** Handshake timeout in ms when running inside a host. Default 5000. */
@@ -46,6 +47,9 @@ export declare class UmicatCore {
     /** Voice input (speech-to-text) with a live mic level for waveform UIs.
      *  Browser recognition in a browser, native platform recognizer in the app. */
     readonly voice: VoiceModule;
+    /** Where the device's fold falls across the play area. Always present;
+     *  reports `dualScreen: false` on every surface without a hinge. */
+    readonly fold: FoldModule;
     protected constructor(transport: Transport);
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user(): UmicatUser | null;

package/dist/core/UmicatCore.js

@@ -6,6 +6,7 @@ import { RealtimeModule } from '../realtime/RealtimeModule.js';
 import { AiModule } from '../ai/AiModule.js';
 import { PlatformModule } from '../platform/PlatformModule.js';
 import { VoiceModule } from '../voice/VoiceModule.js';
+import { FoldModule } from '../fold/FoldModule.js';
 /**
  * Umicat platform services bound to the current (game, user) — with no
  * rendering engine anywhere in sight.
@@ -48,6 +49,7 @@ export class UmicatCore {
         this.ai = new AiModule(transport);
         this.platform = new PlatformModule(transport);
         this.voice = new VoiceModule(transport);
+        this.fold = new FoldModule(transport);
     }
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user() { return this.transport.user; }

package/dist/fold/FoldModule.d.ts

@@ -0,0 +1,58 @@
+import type { Transport } from '../core/Transport.js';
+/** A rectangle in CSS pixels, in the game viewport's own coordinate space. */
+export interface FoldRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FoldLayout {
+    /** Whether the play area should present itself as two screens right now. */
+    dualScreen: boolean;
+    /** Hinge angle in degrees: 0 shut, 180 flat. Absent on a device with no hinge. */
+    angle?: number;
+    /** The crease, margins INCLUDED. A band, not a line. */
+    division?: FoldRect;
+    /** The usable panel above the crease. */
+    top?: FoldRect;
+    /** The usable panel below it. */
+    bottom?: FoldRect;
+    /**
+     * Cut-outs content must not sit under — the front cameras.
+     *
+     * Only the ACTIVE ones: a folding phone reports a camera on the display it is
+     * not currently using, and reserving space for a lens that is facing away is
+     * just lost screen.
+     */
+    occlusions: FoldRect[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Live fold state, and a subscription to changes.
+ *
+ * Reports `dualScreen: false` forever on a host that never pushes — a browser
+ * tab, an older native build, a phone that does not fold. Callers do not
+ * feature-detect; they lay out against whatever `layout` currently says.
+ */
+export declare class FoldModule {
+    private readonly transport;
+    private current;
+    private readonly listeners;
+    constructor(transport: Transport);
+    /** What the fold is doing right now. Never null. */
+    get layout(): FoldLayout;
+    /**
+     * Calls `listener` on every change, and ONCE immediately with the current
+     * value.
+     *
+     * The immediate call is the point: a game that only hears about changes comes
+     * up laid out for a flat screen on a device that was already folded when it
+     * launched, and then looks correct forever after the first hinge movement —
+     * which is the worst possible version of this bug, because it fixes itself
+     * the moment anyone tries to reproduce it.
+     */
+    subscribe(listener: (layout: FoldLayout) => void): () => void;
+}

package/dist/fold/FoldModule.js

@@ -0,0 +1,87 @@
+const FOLD_EVENT = 'umicat:fold';
+/** The flat, unfolded answer — what every surface without a hinge reports. */
+const NO_FOLD = { dualScreen: false, occlusions: [] };
+/**
+ * Live fold state, and a subscription to changes.
+ *
+ * Reports `dualScreen: false` forever on a host that never pushes — a browser
+ * tab, an older native build, a phone that does not fold. Callers do not
+ * feature-detect; they lay out against whatever `layout` currently says.
+ */
+export class FoldModule {
+    constructor(transport) {
+        this.transport = transport;
+        this.current = NO_FOLD;
+        this.listeners = new Set();
+        transport.on?.(FOLD_EVENT, (payload) => {
+            const next = parse(payload);
+            if (!next)
+                return;
+            this.current = next;
+            for (const listener of this.listeners)
+                listener(next);
+        });
+    }
+    /** What the fold is doing right now. Never null. */
+    get layout() {
+        return this.current;
+    }
+    /**
+     * Calls `listener` on every change, and ONCE immediately with the current
+     * value.
+     *
+     * The immediate call is the point: a game that only hears about changes comes
+     * up laid out for a flat screen on a device that was already folded when it
+     * launched, and then looks correct forever after the first hinge movement —
+     * which is the worst possible version of this bug, because it fixes itself
+     * the moment anyone tries to reproduce it.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.current);
+        return () => { this.listeners.delete(listener); };
+    }
+}
+function rect(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const r = value;
+    const nums = ['x', 'y', 'width', 'height'].map((k) => r[k]);
+    if (nums.some((n) => typeof n !== 'number' || !Number.isFinite(n)))
+        return undefined;
+    const [x, y, width, height] = nums;
+    return { x, y, width, height };
+}
+/**
+ * Host payload → `FoldLayout`, or null if it is not one.
+ *
+ * Validated rather than cast: this crosses a postMessage boundary, and a
+ * half-shaped payload that reaches layout code is a crash in the middle of
+ * someone's game rather than a line in a console.
+ */
+function parse(payload) {
+    if (!payload || typeof payload !== 'object')
+        return null;
+    const p = payload;
+    if (typeof p.dualScreen !== 'boolean')
+        return null;
+    const occlusions = Array.isArray(p.occlusions)
+        ? p.occlusions.map(rect).filter((r) => !!r)
+        : [];
+    const viewport = p.viewport && typeof p.viewport === 'object'
+        ? p.viewport
+        : undefined;
+    const top = rect(p.top);
+    const bottom = rect(p.bottom);
+    return {
+        // A split with only one side is not a split. Guarding here keeps every
+        // consumer from having to check both panels before using either.
+        dualScreen: p.dualScreen && !!top && !!bottom,
+        angle: typeof p.angle === 'number' ? p.angle : undefined,
+        division: rect(p.division),
+        top,
+        bottom,
+        occlusions,
+        viewport,
+    };
+}

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export type { JoinOptions, RoomListEntry, RoomListOptions } from './realtime/Rea
 export { AiModule, Npc } from './ai/AiModule.js';
 export type { NpcConfig } from './ai/AiModule.js';
 export { PlatformModule } from './platform/PlatformModule.js';
+export { FoldModule } from './fold/FoldModule.js';
+export type { FoldLayout, FoldRect } from './fold/FoldModule.js';
 export { VoiceModule, webVoiceSupported } from './voice/VoiceModule.js';
 export type { VoiceCallbacks, VoiceSession, VoiceLang } from './voice/VoiceModule.js';
 export { DialogueModule } from './dialogue/DialogueModule.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export { RealtimeModule } from './realtime/RealtimeModule.js';
 export { UmicatRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UmicatRoom.js';
 export { AiModule, Npc } from './ai/AiModule.js';
 export { PlatformModule } from './platform/PlatformModule.js';
+export { FoldModule } from './fold/FoldModule.js';
 export { VoiceModule, webVoiceSupported } from './voice/VoiceModule.js';
 export { DialogueModule } from './dialogue/DialogueModule.js';
 export { DialogueRunner, resolveLangText } from './dialogue/runner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/platform-sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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",