@threenative/ui 0.3.6 → 0.3.8

package/dist/index.d.ts

@@ -31,9 +31,25 @@ declare function UiLayer({ children }: {
  * 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.
+ *
+ * **Reads `undefined` while the loading cover is up**, so a HUD cannot draw over the loading bar
+ * and no game writes a `loaded` field to prevent it. A UI that draws its own loading screen reads
+ * through `useUiStateDuringStartup`.
  */
 declare function useUiState<TState extends object>(): TState | undefined;
 declare function useUiState<TState extends object, TSelected>(selector: (state: TState) => TSelected): TSelected | undefined;
+/**
+ * The named override of `useUiState`'s loading-cover gate, for a UI that draws the loading screen
+ * itself (a staged overlay reading the startup progress the game publishes). It reads state while
+ * the cover is up. `reason` is required and reported once as `TN_UI_STARTUP_OVERRIDE <reason>`,
+ * so a HUD that merely skipped the gate shows up in the log.
+ */
+declare function useUiStateDuringStartup<TState extends object>(options: {
+    readonly reason: string;
+}): TState | undefined;
+declare function useUiStateDuringStartup<TState extends object, TSelected>(options: {
+    readonly reason: string;
+}, selector: (state: TState) => TSelected): TSelected | undefined;
 /**
  * Send an intent to the game — `restart`, `pause`, whatever the game named.
  *
@@ -43,4 +59,4 @@ declare function useUiState<TState extends object, TSelected>(selector: (state:
  */
 declare function useUiIntent(): (intent: string, payload?: unknown) => void;
 
-export { DebugOverlay, GameCanvas, UiLayer, useGameState, useUiIntent, useUiState };
+export { DebugOverlay, GameCanvas, UiLayer, useGameState, useUiIntent, useUiState, useUiStateDuringStartup };

package/dist/index.js

@@ -109,13 +109,18 @@ function DebugOverlayView() {
     const clearOutline = () => setSelected(void 0);
     hostWindow.addEventListener("keydown", toggle);
     hostWindow.addEventListener("resize", clearOutline);
-    const timer = hostWindow.setInterval(() => setSnapshot(readSnapshot()), 100);
     return () => {
       hostWindow.removeEventListener("keydown", toggle);
       hostWindow.removeEventListener("resize", clearOutline);
-      hostWindow.clearInterval(timer);
     };
   }, []);
+  useEffect(() => {
+    if (!open || typeof window === "undefined") return void 0;
+    const hostWindow = window;
+    setSnapshot(readSnapshot());
+    const timer = hostWindow.setInterval(() => setSnapshot(readSnapshot()), 100);
+    return () => hostWindow.clearInterval(timer);
+  }, [open]);
   const capture = useCallback(() => {
     const geometry = devTools()?.geometry;
     if (typeof geometry !== "function" || capturing) return;
@@ -520,12 +525,30 @@ function UiLayer({ children }) {
   ] });
 }
 function useUiState(selector) {
-  const { mirror } = useUiLayer("useUiState");
+  return useMirrorState("useUiState", true, selector);
+}
+var reportedOverrides = /* @__PURE__ */ new Set();
+function useUiStateDuringStartup(options, selector) {
+  const reason = options.reason;
+  if (typeof reason !== "string" || reason.trim().length === 0) {
+    throw new Error(
+      "TN_UI_STARTUP_OVERRIDE_REASON: useUiStateDuringStartup needs a non-empty reason."
+    );
+  }
+  if (!reportedOverrides.has(reason)) {
+    reportedOverrides.add(reason);
+    console.info(`TN_UI_STARTUP_OVERRIDE ${reason}`);
+  }
+  return useMirrorState("useUiStateDuringStartup", false, selector);
+}
+function useMirrorState(name, hideWhileCovered, selector) {
+  const { mirror } = useUiLayer(name);
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
   return useSyncExternalStore(
     (onChange) => mirror.subscribe(onChange),
     () => {
+      if (hideWhileCovered && mirror.covered()) return void 0;
       const state = mirror.get();
       if (state === void 0) return void 0;
       return selectorRef.current === void 0 ? state : selectorRef.current(state);
@@ -541,4 +564,4 @@ function useUiIntent() {
   );
 }
 
-export { DebugOverlay, GameCanvas, UiLayer, useGameState, useUiIntent, useUiState };
+export { DebugOverlay, GameCanvas, UiLayer, useGameState, useUiIntent, useUiState, useUiStateDuringStartup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threenative/ui",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "license": "MIT",
   "description": "React bindings for mounting a ThreeNative game and reading throttled state.",
   "keywords": [
@@ -41,7 +41,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@threenative/core": ">=0.3.6 <0.4.0",
+    "@threenative/core": ">=0.3.8 <0.4.0",
     "react": ">=19.2.0 <20",
     "react-dom": ">=19.2.0 <20"
   },
@@ -56,7 +56,7 @@
     "tsup": "8.5.1",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@threenative/core": "0.3.6"
+    "@threenative/core": "0.3.8"
   },
   "scripts": {
     "build": "tsup --config tsup.config.ts && publint",