@umicat/platform-sdk 0.3.0 → 0.4.0

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

@@ -17,6 +17,7 @@ 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';

package/dist/index.js

@@ -16,6 +16,7 @@ export { UmicatRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT
 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.3.0",
+  "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",