@threenative/ui 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Paulo Furtado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @threenative/ui
+
+## What it is
+
+`@threenative/ui` provides React bindings for a ThreeNative game: `GameCanvas` mounts the game
+surface, `useGameState` reads its throttled state store, and `DebugOverlay` exposes development
+snapshots. It is not a scene-graph or visual-design layer; React renders HUDs, menus, and overlays,
+while the game owns gameplay and the Three.js scene.
+
+## Install
+
+Install the package with its peer dependencies:
+
+```sh
+pnpm add @threenative/ui @threenative/core react react-dom three
+```
+
+## Example
+
+In a generated `starter` project, `src/ui/App.tsx` mounts the real game and its HUD:
+
+```tsx
+import type { IGame } from "@threenative/core";
+import type { IPhysicsContext } from "@threenative/physics";
+import { DebugOverlay, GameCanvas } from "@threenative/ui";
+import type { GameState } from "../state.js";
+import { Hud } from "./Hud.js";
+import { Menu } from "./Menu.js";
+
+export function App({ game }: { game: IGame<GameState, IPhysicsContext> }) {
+  return (
+    <main className="relative h-screen w-screen overflow-hidden bg-ink">
+      <GameCanvas className="absolute inset-0" game={game} />
+      <Hud game={game} />
+      <Menu game={game} />
+      <DebugOverlay />
+    </main>
+  );
+}
+```
+
+## Styling the debug overlay
+
+`DebugOverlay` ships no presentation — it renders one `<aside data-threenative-debug-overlay="true">`
+and leaves every pixel to you. Generated projects already carry a rule for it in their stylesheet;
+a project that imports the package directly must write its own, or the overlay paints behind an
+absolutely positioned `GameCanvas` and its diagnostics are invisible:
+
+```css
+[data-threenative-debug-overlay="true"] {
+  position: fixed;
+  top: 1rem;
+  right: 1rem;
+  z-index: 50;
+  pointer-events: none;
+  background: rgb(2 6 23 / 90%);
+  color: #cffafe;
+}
+```
+
+## Links
+
+- [Repository](https://github.com/ThreeNativeHQ/threenative)
+- [MIT License](https://github.com/ThreeNativeHQ/threenative/blob/main/LICENSE)
+- Start a project with `pnpm create threenative my-game`.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { IGame } from '@threenative/core';
+import { ReactNode } from 'react';
 
 interface IGameCanvasProps<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
     className?: string;
@@ -13,4 +14,25 @@ type GameSelector<TState, TSelected> = (state: TState) => TSelected;
 declare function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>(game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>): TSelected;
 declare function useGameState<TState extends Record<string, unknown>, TPhysics>(game: IGame<TState, TPhysics>): TState;
 
-export { DebugOverlay, GameCanvas, useGameState };
+declare function UiLayer({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element | null;
+/**
+ * Read a slice of the game's published state.
+ *
+ * The UI holds a mirror, never the game object: on every native target the game is in another
+ * realm, and a HUD written against a live store would work on web and read nothing on a phone.
+ * The mirror is fed at the store's published cadence, which is not the game loop.
+ */
+declare function useUiState<TState extends object>(): TState | undefined;
+declare function useUiState<TState extends object, TSelected>(selector: (state: TState) => TSelected): TSelected | undefined;
+/**
+ * Send an intent to the game — `restart`, `pause`, whatever the game named.
+ *
+ * Intents are one-way and the game may ignore one; that is not an error. Anything the UI needs
+ * back arrives as published state, which keeps a single source of truth on the side that owns
+ * the simulation.
+ */
+declare function useUiIntent(): (intent: string, payload?: unknown) => void;
+
+export { DebugOverlay, GameCanvas, UiLayer, useGameState, useUiIntent, useUiState };

package/dist/index.js

@@ -1,5 +1,6 @@
-import { useRef, useEffect, useState, useSyncExternalStore } from 'react';
+import { createContext, useRef, useState, useEffect, useSyncExternalStore, useMemo, useContext } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
+import { connectUiBridge, subscribeUiState, publishHitRegions, sendUiIntent, UI_READY_INTENT } from '@threenative/core/ui-layer';
 
 // src/GameCanvas.tsx
 function GameCanvas({
@@ -7,8 +8,10 @@ function GameCanvas({
   game
 }) {
   const host = useRef(null);
+  const [failure, setFailure] = useState();
   useEffect(() => {
     let cancelled = false;
+    setFailure(void 0);
     void game.start().then(() => {
       const canvas = game.ctx?.renderer.domElement;
       if (!cancelled && canvas !== void 0 && host.current !== null) {
@@ -19,7 +22,8 @@ function GameCanvas({
         host.current.replaceChildren(canvas);
       }
     }).catch((error) => {
-      if (!cancelled) throw error;
+      if (cancelled) return;
+      setFailure(error instanceof Error ? error.message : String(error));
     });
     return () => {
       cancelled = true;
@@ -32,31 +36,12 @@ function GameCanvas({
       ref: host,
       className,
       "data-threenative-canvas": "true",
-      style: { height: "100%", width: "100%" }
+      style: { height: "100%", width: "100%" },
+      children: failure === void 0 ? null : /* @__PURE__ */ jsx("div", { "data-threenative-canvas-error": "true", role: "alert", children: failure })
     }
   );
 }
 var isDev = import.meta.env?.DEV === true;
-var panelStyle = {
-  background: "rgb(2 6 23 / 90%)",
-  boxShadow: "0 10px 15px -3px rgb(0 0 0 / 30%)",
-  color: "#cffafe",
-  fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
-  fontSize: "12px",
-  lineHeight: 1.5,
-  maxWidth: "24rem",
-  padding: "12px",
-  pointerEvents: "none",
-  position: "fixed",
-  right: "16px",
-  top: "16px",
-  zIndex: 50
-};
-var tableStyle = { tableLayout: "fixed", width: "100%" };
-var headerCellStyle = { paddingRight: "16px", textAlign: "left" };
-var cellStyle = { paddingRight: "16px" };
-var lastCellStyle = { textAlign: "left" };
-var valueCellStyle = { overflowWrap: "anywhere", wordBreak: "break-all" };
 function readSnapshot() {
   const snapshot = globalThis.window?.__THREENATIVE__?.snapshot;
   return typeof snapshot === "function" ? snapshot() : {};
@@ -84,33 +69,81 @@ function DebugOverlay() {
   const rows = Object.entries(snapshot).flatMap(
     ([entity, fields]) => Object.entries(fields).map(([key, value]) => ({ entity, key, value }))
   );
-  return /* @__PURE__ */ jsx(
-    "aside",
-    {
-      "aria-label": "ThreeNative entity debug overlay",
-      "data-threenative-debug-overlay": "true",
-      style: panelStyle,
-      children: /* @__PURE__ */ jsxs("table", { style: tableStyle, children: [
-        /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
-          /* @__PURE__ */ jsx("th", { style: headerCellStyle, children: "entity" }),
-          /* @__PURE__ */ jsx("th", { style: headerCellStyle, children: "key" }),
-          /* @__PURE__ */ jsx("th", { style: lastCellStyle, children: "value" })
-        ] }) }),
-        /* @__PURE__ */ jsx("tbody", { children: rows.map(({ entity, key, value }) => /* @__PURE__ */ jsxs("tr", { children: [
-          /* @__PURE__ */ jsx("td", { style: cellStyle, children: entity }),
-          /* @__PURE__ */ jsx("td", { style: cellStyle, children: key }),
-          /* @__PURE__ */ jsx("td", { style: valueCellStyle, children: displayValue(value) })
-        ] }, `${entity}.${key}`)) })
-      ] })
-    }
-  );
+  return /* @__PURE__ */ jsx("aside", { "aria-label": "ThreeNative entity debug overlay", "data-threenative-debug-overlay": "true", children: /* @__PURE__ */ jsxs("table", { children: [
+    /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+      /* @__PURE__ */ jsx("th", { children: "entity" }),
+      /* @__PURE__ */ jsx("th", { children: "key" }),
+      /* @__PURE__ */ jsx("th", { children: "value" })
+    ] }) }),
+    /* @__PURE__ */ jsx("tbody", { children: rows.map(({ entity, key, value }) => /* @__PURE__ */ jsxs("tr", { children: [
+      /* @__PURE__ */ jsx("td", { children: entity }),
+      /* @__PURE__ */ jsx("td", { children: key }),
+      /* @__PURE__ */ jsx("td", { children: displayValue(value) })
+    ] }, `${entity}.${key}`)) })
+  ] }) });
 }
 function useGameState(game, selector = (state) => state) {
   return useSyncExternalStore(
     (onStoreChange) => game.state.subscribe(onStoreChange),
-    () => selector(game.state.getState()),
-    () => selector(game.state.getState())
+    () => selector(game.state.getPublishedState()),
+    () => selector(game.state.getPublishedState())
+  );
+}
+var UiLayerContext = createContext(void 0);
+function useUiLayer(name) {
+  const value = useContext(UiLayerContext);
+  if (value === void 0) {
+    throw new Error(`TN_UI_LAYER_MISSING: ${name} must be used inside <UiLayer>.`);
+  }
+  return value;
+}
+function UiLayer({ children }) {
+  const [value, setValue] = useState(void 0);
+  const registryRef = useRef(void 0);
+  useEffect(() => {
+    const bridge = connectUiBridge({ end: "ui" });
+    const mirror = subscribeUiState(bridge);
+    setValue({ bridge, mirror });
+    return () => {
+      registryRef.current?.stop();
+      registryRef.current = void 0;
+      mirror.stop();
+      bridge.close();
+      setValue(void 0);
+    };
+  }, []);
+  useEffect(() => {
+    if (value === void 0) return;
+    const registry = publishHitRegions({ bridge: value.bridge });
+    registryRef.current = registry;
+    sendUiIntent(value.bridge, UI_READY_INTENT, registry.regions().length);
+    return () => {
+      registryRef.current = void 0;
+    };
+  }, [value]);
+  if (value === void 0) return null;
+  return /* @__PURE__ */ jsx(UiLayerContext.Provider, { value, children });
+}
+function useUiState(selector) {
+  const { mirror } = useUiLayer("useUiState");
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+  return useSyncExternalStore(
+    (onChange) => mirror.subscribe(onChange),
+    () => {
+      const state = mirror.get();
+      if (state === void 0) return void 0;
+      return selectorRef.current === void 0 ? state : selectorRef.current(state);
+    },
+    () => void 0
+  );
+}
+function useUiIntent() {
+  const { bridge } = useUiLayer("useUiIntent");
+  return useMemo(
+    () => (intent, payload) => sendUiIntent(bridge, intent, payload),
+    [bridge]
   );
 }
 
-export { DebugOverlay, GameCanvas, useGameState };
+export { DebugOverlay, GameCanvas, UiLayer, useGameState, useUiIntent, useUiState };

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@threenative/ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
+  "license": "MIT",
   "description": "React bindings for mounting a ThreeNative game and reading throttled state.",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,7 +23,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@threenative/core": ">=0.1.0 <0.2.0",
+    "@threenative/core": ">=0.3.0 <0.4.0",
     "react": ">=19.2.0 <20",
     "react-dom": ">=19.2.0 <20"
   },
@@ -35,11 +37,11 @@
     "react-test-renderer": "19.2.0",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
-    "@threenative/core": "0.2.0"
+    "@threenative/core": "0.3.0"
   },
   "scripts": {
     "build": "tsup --config tsup.config.ts && publint",
     "typecheck": "tsc --noEmit",
-    "test": "pnpm run build"
+    "test": "publint --strict"
   }
 }