@umicat/platform-sdk 0.2.2 → 0.4.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/fold/ScreensModule.d.ts

@@ -0,0 +1,21 @@
+import type { FoldModule } from './FoldModule.js';
+export declare class ScreensModule {
+    /** Above the crease when folded; the whole viewport when flat. */
+    readonly top: HTMLElement;
+    /** Below the crease. Hidden — but still yours, and still populated — when
+     *  the device is flat. */
+    readonly bottom: HTMLElement;
+    private second;
+    private readonly listeners;
+    constructor(fold: FoldModule);
+    /** Whether `bottom` is a real second screen right now. */
+    get hasSecondScreen(): boolean;
+    /**
+     * Calls `listener` on every change, and once immediately — same contract as
+     * `FoldModule.subscribe`, and for the same reason: a game told only about
+     * CHANGES lays itself out for one screen on a device that was already folded
+     * when it launched.
+     */
+    subscribe(listener: (screens: ScreensModule) => void): () => void;
+    private apply;
+}

package/dist/fold/ScreensModule.js

@@ -0,0 +1,101 @@
+// Two screens a game can put ANYTHING on.
+//
+// `FoldModule` answers "where is the crease"; this answers "here are the two
+// surfaces". A game that wants a map, an inventory, a text box or a second
+// rendered view on the lower screen appends it to `bottom` and is done — the
+// SDK keeps both boxes glued to the panels as the hinge moves.
+//
+// **Both elements always exist, and neither is ever replaced.** The obvious
+// alternative — `bottom: HTMLElement | null`, null when the device is flat —
+// is more honest about the hardware and much worse to use: every game would
+// branch at startup, and anything already appended would be destroyed on the
+// first unfold. Instead `bottom` is simply hidden while there is no second
+// screen, so a game appends once and its content survives folding, unfolding
+// and folding again. `hasSecondScreen` is there for the game that genuinely
+// wants to say something different when there is only one.
+//
+// **`position: fixed` children land inside their screen, not the window.** The
+// containers carry a `transform`, and a transformed ancestor becomes the
+// containing block for fixed descendants. That is what lets an existing HUD —
+// authored as fixed, anchored to "bottom-right" — move onto a panel whole,
+// without touching a single widget.
+/** Pointer-events are off on the container and on for what the game adds, so
+ *  an empty top screen does not swallow taps meant for the world below it. */
+const BASE_STYLE = {
+    position: 'fixed',
+    pointerEvents: 'none',
+    // Clips to the panel: content must not bleed across the crease, which is the
+    // one place on this device where "slightly too tall" is physically bent.
+    overflow: 'hidden',
+    // Establishes the containing block (see above) AND its own stacking context.
+    transform: 'translateZ(0)',
+    // Under the SDK's own touch layer (z-index 10), which shares the lower panel.
+    zIndex: '5',
+};
+export class ScreensModule {
+    constructor(fold) {
+        this.second = false;
+        this.listeners = new Set();
+        this.top = make('top');
+        this.bottom = make('bottom');
+        fold.subscribe((layout) => this.apply(layout));
+    }
+    /** Whether `bottom` is a real second screen right now. */
+    get hasSecondScreen() {
+        return this.second;
+    }
+    /**
+     * Calls `listener` on every change, and once immediately — same contract as
+     * `FoldModule.subscribe`, and for the same reason: a game told only about
+     * CHANGES lays itself out for one screen on a device that was already folded
+     * when it launched.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this);
+        return () => { this.listeners.delete(listener); };
+    }
+    apply(layout) {
+        const split = layout.dualScreen && !!layout.top && !!layout.bottom;
+        this.second = split;
+        if (split) {
+            box(this.top, layout.top);
+            box(this.bottom, layout.bottom);
+            this.bottom.style.display = '';
+        }
+        else {
+            // Flat: the top screen IS the window, and there is no second one.
+            Object.assign(this.top.style, { left: '0', top: '0', width: '100%', height: '100%' });
+            this.bottom.style.display = 'none';
+        }
+        for (const listener of this.listeners)
+            listener(this);
+    }
+}
+function make(name) {
+    // Headless (tests, SSR): hand back a detached stub rather than throwing. A
+    // game is never rendering in that case, so the box has nothing to be glued
+    // to — but `screens.top` must still be an element, or every caller needs a
+    // null check for a situation that only exists in a test runner.
+    if (typeof document === 'undefined') {
+        return { style: {}, dataset: {}, setAttribute() { }, appendChild() { } };
+    }
+    const el = document.createElement('div');
+    el.dataset.umicatScreen = name;
+    // Survives the editor's "hide every static element" sweep, which otherwise
+    // takes anything it does not recognise in index.html.
+    el.setAttribute('data-umicat-keep', '');
+    Object.assign(el.style, BASE_STYLE);
+    if (name === 'bottom')
+        el.style.display = 'none';
+    (document.body ?? document.documentElement).appendChild(el);
+    return el;
+}
+function box(el, r) {
+    Object.assign(el.style, {
+        left: `${r.x}px`,
+        top: `${r.y}px`,
+        width: `${r.width}px`,
+        height: `${r.height}px`,
+    });
+}

package/dist/fold/foldVariables.d.ts

@@ -0,0 +1,37 @@
+import type { FoldModule, FoldLayout } from './FoldModule.js';
+/**
+ * Publishes the fold geometry as CSS custom properties, so a game's own DOM can
+ * follow the crease without reading the SDK at all:
+ *
+ *     --umicat-top-height, --umicat-bottom-top, --umicat-bottom-height,
+ *     --umicat-fold-top, --umicat-fold-height
+ *
+ * plus `data-umicat-dual-screen` on `<html>`, because a stylesheet cannot ask a
+ * module a question.
+ *
+ * **Engine-agnostic on purpose.** These NAMES are a contract between the SDK and
+ * a game's stylesheet — Gomoku's chat panel moves to the lower screen with no
+ * JavaScript at all — and a contract with two definitions drifts. It lived in
+ * `@umicat/three-sdk` while 3D was the only consumer; it moved here the moment
+ * the Phaser side needed the same names.
+ *
+ * All values are `0` when there is no fold, so a stylesheet that uses them is
+ * correct on a flat screen too.
+ *
+ * **Never give these a fallback in `var()`.** Without the property the whole
+ * `calc()` is invalid, the declaration is dropped, and the unfolded rule stands
+ * — which is right. A `0px` fallback computes a real but wrong position: for a
+ * bottom-anchored element, one off the screen.
+ */
+export declare function installFoldVariables(fold: FoldModule): () => void;
+/**
+ * Puts a canvas in the panel above the crease, or back where it was.
+ *
+ * The CSS BOX only — never the drawing buffer. Which half of the job that is
+ * depends on the engine: Phaser's scale manager sizes the buffer itself once
+ * the box changes, while a three.js game has to be told (`viewportSize`).
+ * Shared because the positioning is identical and the trap is too: a buffer
+ * sized to the upper panel inside a canvas still stretched across the window
+ * draws the picture at twice its height.
+ */
+export declare function placeCanvasInPanel(canvas: HTMLCanvasElement, layout: FoldLayout): void;

package/dist/fold/foldVariables.js

@@ -0,0 +1,67 @@
+/**
+ * Publishes the fold geometry as CSS custom properties, so a game's own DOM can
+ * follow the crease without reading the SDK at all:
+ *
+ *     --umicat-top-height, --umicat-bottom-top, --umicat-bottom-height,
+ *     --umicat-fold-top, --umicat-fold-height
+ *
+ * plus `data-umicat-dual-screen` on `<html>`, because a stylesheet cannot ask a
+ * module a question.
+ *
+ * **Engine-agnostic on purpose.** These NAMES are a contract between the SDK and
+ * a game's stylesheet — Gomoku's chat panel moves to the lower screen with no
+ * JavaScript at all — and a contract with two definitions drifts. It lived in
+ * `@umicat/three-sdk` while 3D was the only consumer; it moved here the moment
+ * the Phaser side needed the same names.
+ *
+ * All values are `0` when there is no fold, so a stylesheet that uses them is
+ * correct on a flat screen too.
+ *
+ * **Never give these a fallback in `var()`.** Without the property the whole
+ * `calc()` is invalid, the declaration is dropped, and the unfolded rule stands
+ * — which is right. A `0px` fallback computes a real but wrong position: for a
+ * bottom-anchored element, one off the screen.
+ */
+export function installFoldVariables(fold) {
+    return fold.subscribe(publish);
+}
+function publish(layout) {
+    if (typeof document === 'undefined')
+        return;
+    const root = document.documentElement;
+    const px = (n) => `${Math.round(n ?? 0)}px`;
+    const on = layout.dualScreen;
+    root.style.setProperty('--umicat-top-height', px(on ? layout.top?.height : 0));
+    root.style.setProperty('--umicat-bottom-top', px(on ? layout.bottom?.y : 0));
+    root.style.setProperty('--umicat-bottom-height', px(on ? layout.bottom?.height : 0));
+    root.style.setProperty('--umicat-fold-top', px(on ? layout.division?.y : 0));
+    root.style.setProperty('--umicat-fold-height', px(on ? layout.division?.height : 0));
+    if (on)
+        root.dataset.umicatDualScreen = '';
+    else
+        delete root.dataset.umicatDualScreen;
+}
+/**
+ * Puts a canvas in the panel above the crease, or back where it was.
+ *
+ * The CSS BOX only — never the drawing buffer. Which half of the job that is
+ * depends on the engine: Phaser's scale manager sizes the buffer itself once
+ * the box changes, while a three.js game has to be told (`viewportSize`).
+ * Shared because the positioning is identical and the trap is too: a buffer
+ * sized to the upper panel inside a canvas still stretched across the window
+ * draws the picture at twice its height.
+ */
+export function placeCanvasInPanel(canvas, layout) {
+    if (layout.dualScreen && layout.top) {
+        Object.assign(canvas.style, {
+            position: 'fixed',
+            left: `${layout.top.x}px`,
+            top: `${layout.top.y}px`,
+            width: `${layout.top.width}px`,
+            height: `${layout.top.height}px`,
+        });
+    }
+    else {
+        Object.assign(canvas.style, { position: '', left: '', top: '', width: '', height: '' });
+    }
+}

package/dist/index.d.ts

@@ -16,6 +16,9 @@ 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 { installFoldVariables, placeCanvasInPanel } from './fold/foldVariables.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,8 @@ 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 { installFoldVariables, placeCanvasInPanel } from './fold/foldVariables.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.4.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",