@threenative/core 0.1.0 → 0.3.0

package/dist/ui-layer.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The UI bridge — one message channel between the game and the UI, identical on every host.
+ *
+ * The UI runs in the platform's own browser-class renderer (a `WebView` on Android, a
+ * `WKWebView` on iOS, a child web view on desktop) while the game runs in the native
+ * runtime beside it. They are two JavaScript realms in, usually, two processes, so
+ * everything that crosses is a message.
+ *
+ * Every host already offers a `MessagePort`-shaped primitive — `addWebMessageListener` on
+ * Android, `WKScriptMessageHandler` on iOS, an IPC handler on desktop — so this file adopts
+ * that shape rather than inventing one, and each host only has to fill in two slots:
+ *
+ * - **outbound**, a function that takes one JSON string;
+ * - **inbound**, a global the host calls with one JSON string.
+ *
+ * On the web target there is no host and no second realm: the game and the UI are the same
+ * page, so both ends connect to an in-process broker and the same `src/ui/` code runs
+ * unchanged. That is the whole point — the transport differs, the protocol does not.
+ *
+ * Fail closed: a message that is not a JSON object with a string `type` throws on the way
+ * out, and a malformed frame throws on the way in. A dropped message is a UI that silently
+ * stops updating, which is the failure this refuses to have.
+ */
+/** Which side of the bridge a caller is on. `ui` runs in the web view; `game` in the runtime. */
+type UiBridgeEnd = "game" | "ui";
+/** How a connected bridge actually moves bytes. Reported, never chosen by a game. */
+type UiBridgeTransport = "host" | "in-process";
+/** Every frame on the bridge is a JSON object whose `type` names it. */
+interface IUiMessage {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+interface IUiBridge {
+    /** Which end this handle is. */
+    readonly end: UiBridgeEnd;
+    /** `host` when a platform channel was found, `in-process` on the web target. */
+    readonly transport: UiBridgeTransport;
+    /**
+     * Whether anything is listening on the other end.
+     *
+     * A game whose UI renderer is `native` has no peer and never will, and publishing state to
+     * nobody is a JSON serialisation of the whole store several times a second for no reader.
+     * Reported rather than assumed: on a host transport this asks the host, so it also answers
+     * "did the overlay actually come up" honestly.
+     */
+    hasPeer(): boolean;
+    /** Send one message to the other end. Throws if it is not a typed JSON object. */
+    post(message: IUiMessage): void;
+    /** Listen for messages from the other end. Returns an unsubscribe function. */
+    onMessage(listener: (message: IUiMessage) => void): () => void;
+    /** Detach every listener and release the host slots this end installed. */
+    close(): void;
+}
+/** The message the UI end publishes whenever its interactive rectangles move. */
+declare const HIT_REGIONS_MESSAGE = "tn:hit-regions";
+/** The message the game end publishes when its shared state changes. */
+declare const GAME_STATE_MESSAGE = "tn:state";
+/** The message the UI end sends when the player acts on a control. */
+declare const UI_INTENT_MESSAGE = "tn:intent";
+/**
+ * The intent the UI layer sends once, when its tree has rendered and its rectangles are published.
+ *
+ * Namespaced so it cannot collide with a game's own vocabulary, and framework-sent so a game does
+ * not have to remember to announce itself. It is what lets "the overlay never came up" be told
+ * apart from "the game has no HUD" — two states that look identical in a screenshot.
+ */
+declare const UI_READY_INTENT = "tn:ready";
+/**
+ * The globals each host fills in. Named here so a host implementation and this file cannot
+ * drift: an Android, iOS or desktop host that writes different names has no bridge at all,
+ * and a typo is a silent dead channel rather than a build error.
+ */
+declare const UI_BRIDGE_GLOBALS: {
+    /** UI end, inbound: the host calls this with one JSON string. */
+    readonly uiReceive: "__tnUiReceive";
+    /** UI end, outbound: an injected object with `postMessage(string)`. */
+    readonly uiHost: "tnHost";
+    /** Game end, inbound: the runtime calls this with one JSON string. */
+    readonly gameReceive: "__tnUiGameReceive";
+    /** Game end, outbound: the runtime installs this and forwards to the web view. */
+    readonly gamePost: "__tnUiPost";
+};
+/**
+ * The realm a bridge end installs into.
+ *
+ * Indexed rather than typed as `Window`, because the host globals it looks for are ones no
+ * TypeScript DOM library has heard of and the tests drive it with a plain object.
+ */
+interface IScope {
+    [key: string]: unknown;
+}
+interface IConnectOptions {
+    readonly end: UiBridgeEnd;
+    /** The realm to install into. Defaults to `globalThis`; injected by tests and by hosts. */
+    readonly scope?: IScope;
+}
+/**
+ * Connect one end of the bridge.
+ *
+ * The transport is discovered, never configured: a game asks for `ui` or `game` and gets the
+ * platform channel when one exists and the in-process broker when it does not. That is what
+ * keeps the backend — which web view, which host API — out of every game's source.
+ * @situation connect game code to a platform-owned UI realm
+ * @situation share one UI bridge implementation across web, Android, iOS, and desktop
+ * @example const bridge = connectUiBridge({ end: "game" });
+ */
+declare function connectUiBridge(options: IConnectOptions): IUiBridge;
+
+/**
+ * What crosses the bridge, in both directions: published state out, intents back.
+ *
+ * The UI is a different realm from the game on every native target, so it cannot hold the game
+ * object, subscribe to its store, or call its methods. It holds a **mirror** — the last state
+ * the game published — and it sends **intents**, which the game is free to ignore.
+ *
+ * That asymmetry is deliberate and it is what keeps one `src/ui/` honest. A HUD written against
+ * a live store works on web and silently has nothing to read on a phone; a HUD written against
+ * the mirror behaves identically on both, because on web the mirror is fed by the same
+ * publication through an in-process channel.
+ *
+ * Publications are **coalesced**: many store writes inside one turn produce one frame. React
+ * must never re-render on the game loop, and neither may the bridge carry a frame per tick.
+ */
+/**
+ * The minimum a store must offer to be published.
+ *
+ * `getPublishedState` is optional and preferred when present: ThreeNative's game store keeps a
+ * live `getState()` that moves every tick and a `getPublishedState()` that moves at most ten
+ * times a second. The UI wants the throttled one — the live one would put a bridge frame on
+ * every tick, which is the thing React must never do.
+ */
+interface IPublishableStore<T> {
+    getState(): T;
+    getPublishedState?(): T;
+    subscribe(listener: () => void): () => void;
+}
+interface IUiStatePublisher {
+    /** Send the current state now, whether or not it changed. */
+    publish(): void;
+    /** Stop publishing. The mirror keeps whatever it last received. */
+    stop(): void;
+}
+interface IUiStateMirror<T> {
+    /** The last state the game published, or undefined before the first frame arrives. */
+    get(): T | undefined;
+    /** Called after each accepted publication. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Stop listening. */
+    stop(): void;
+}
+interface IPublishOptions {
+    /**
+     * How a coalesced publication is deferred. Defaults to a microtask, which collapses every
+     * write in one turn into one frame. A game with a chatty store may pass a frame scheduler.
+     */
+    readonly schedule?: (flush: () => void) => void;
+}
+/**
+ * Publish a store to the UI over `bridge`.
+ *
+ * Only the `game` end publishes: the UI is a mirror, and a UI that could write the game's state
+ * directly would be a second source of truth that only diverges on the platform where the two
+ * are actually separate processes.
+ * @situation publish game state to a HUD in another realm
+ * @situation keep a web and native UI mirror on the same throttled state stream
+ * @example const publisher = publishUiState(bridge, store);
+ */
+declare function publishUiState<T>(bridge: IUiBridge, store: IPublishableStore<T>, options?: IPublishOptions): IUiStatePublisher;
+/**
+ * Mirror the game's published state on the UI end.
+ *
+ * Fail closed: a `tn:state` frame with no `state` object throws rather than leaving the mirror
+ * showing stale values, which is the failure mode where a HUD keeps displaying the last health
+ * it saw and nobody can tell it stopped updating.
+ * @situation read published game state from a UI HUD
+ * @situation subscribe a web or native UI to the game's mirrored state
+ * @example const mirror = subscribeUiState<{ health: number }>(bridge);
+ */
+declare function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T>;
+/**
+ * Send one intent from the UI to the game. The game may ignore it; that is not an error.
+ * @situation send a button or menu action from a UI HUD to game code
+ * @situation keep UI input portable across web and native hosts
+ * @example sendUiIntent(bridge, "restart");
+ */
+declare function sendUiIntent(bridge: IUiBridge, intent: string, payload?: unknown): void;
+/**
+ * Receive UI intents on the game end. Returns an unsubscribe function.
+ * @situation handle a HUD button action in game code
+ * @situation route native and web UI commands through one listener
+ * @example const stop = onUiIntent(bridge, (intent) => handleIntent(intent));
+ */
+declare function onUiIntent(bridge: IUiBridge, listener: (intent: string, payload: unknown) => void): () => void;
+
+/**
+ * The interactive-rect registry — how a touch decides whether it belongs to the UI or the game.
+ *
+ * A web view is a native view with a **rectangular** hit-test region owned by the platform.
+ * CSS hit-testing happens inside that surface, after the native view has already claimed the
+ * gesture, so `pointer-events: none` does not hand a touch back to the game beneath. It is a
+ * useful property inside the page and it is not the pass-through mechanism.
+ *
+ * The mechanism is this: the page marks its interactive islands with `data-tn-interactive`,
+ * this registry publishes where they are, and the native input host does the hit test before
+ * either surface sees the gesture.
+ *
+ * ```tsx
+ * <button data-tn-interactive onClick={restart}>Restart</button>
+ * ```
+ *
+ * Three properties make it correct, and each one is a defect this file exists to prevent:
+ *
+ * - **Published, never queried.** The host owns a snapshot. Asking the page per touch means an
+ *   async round trip inside the input path: latency, and a race with the frame that moved it.
+ * - **Decided on pointer-down, held to pointer-up.** That rule belongs to the host, because
+ *   only the host sees the whole gesture; this file just keeps the snapshot true.
+ * - **Republished per frame while a transition is live.** A sliding menu is drawn where the
+ *   compositor put it this frame, and a rect published before the slide points at empty space.
+ *
+ * Rects are **normalized to the viewport**, 0..1, so no host has to know about CSS pixels,
+ * device pixel ratio, or the page's zoom to place them on its own surface. That is also what
+ * lets a sibling-layer host and an offscreen-texture host read the same payload.
+ */
+/** One interactive rectangle, normalized to the UI viewport: `0,0` top-left, `1,1` bottom-right. */
+interface IHitRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface IHitRegionRegistry {
+    /** Recompute and publish now. Called for you; exposed for a game that moves a rect itself. */
+    refresh(): void;
+    /** The regions as last published. */
+    regions(): readonly IHitRegion[];
+    /** Stop observing and publish an empty set, so the host stops consuming touches. */
+    stop(): void;
+}
+interface IRegistryOptions {
+    /** The connected bridge whose `ui` end publishes the regions. */
+    readonly bridge: IUiBridge;
+    /** The realm to observe. Defaults to `globalThis`; injected by tests. */
+    readonly scope?: IScopeLike;
+    /** The marker attribute. Defaults to `data-tn-interactive`; a game should not change it. */
+    readonly attribute?: string;
+}
+/** The attribute a game puts on an element it wants to receive touches. */
+declare const INTERACTIVE_ATTRIBUTE = "data-tn-interactive";
+interface IRectLike {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface IElementLike {
+    getClientRects?: () => ArrayLike<IRectLike>;
+    getBoundingClientRect: () => IRectLike;
+    /** Used only to name an unmarked control in the development warning below. */
+    closest?: (selector: string) => IElementLike | null;
+    tagName?: string;
+    id?: string;
+    className?: string;
+}
+/** Anything that can be listened to. The document and the window both satisfy it structurally. */
+interface IEventTargetLike {
+    addEventListener?: (type: string, listener: () => void, options?: unknown) => void;
+    removeEventListener?: (type: string, listener: () => void, options?: unknown) => void;
+}
+interface IDocumentLike extends IEventTargetLike {
+    querySelectorAll: (selector: string) => ArrayLike<IElementLike>;
+    documentElement?: {
+        clientWidth?: number;
+        clientHeight?: number;
+    };
+}
+/**
+ * The realm the registry observes, as the parts of it this file actually touches.
+ *
+ * Declared structurally rather than as `Window`, because the registry has to be drivable from a
+ * test with no DOM — and because the host it really runs in is a web view whose globals the type
+ * system here has never seen.
+ */
+interface IScopeLike extends IEventTargetLike {
+    [key: string]: unknown;
+    document?: IDocumentLike;
+    console?: {
+        warn?: (message: string) => void;
+    };
+    innerWidth?: number;
+    innerHeight?: number;
+    requestAnimationFrame?: (callback: () => void) => number;
+    cancelAnimationFrame?: (handle: number) => void;
+}
+/**
+ * Start publishing interactive rectangles over `bridge`.
+ *
+ * Fail closed: with no document there is nothing to measure, and a registry that quietly
+ * published nothing would look exactly like a UI with no buttons — every touch would fall
+ * through to the game and the bug would present as "the button does nothing".
+ * @situation give native input hosts the rectangles claimed by UI controls
+ * @situation keep touch hit testing aligned with a moving web or native HUD
+ * @example const regions = publishHitRegions({ bridge });
+ */
+declare function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry;
+
+export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, type IHitRegion, type IHitRegionRegistry, INTERACTIVE_ATTRIBUTE, type IPublishableStore, type IUiBridge, type IUiMessage, type IUiStateMirror, type IUiStatePublisher, UI_BRIDGE_GLOBALS, UI_INTENT_MESSAGE, UI_READY_INTENT, type UiBridgeEnd, type UiBridgeTransport, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };