@dcl/react-ecs 7.25.1-31496802383.commit-d3168c9 → 7.25.1-31605440953.commit-08dff78

package/dist/components/InteractableArea/index.js

@@ -1,6 +1,6 @@
 import { ReactEcs } from '../../react-ecs';
 import { UiEntity } from '../index';
-import { getInteractableArea } from '../utils';
+import { compensateInsetForUiScale, getInteractableArea } from '../utils';
 /**
  *
  * @public
@@ -23,7 +23,8 @@ import { getInteractableArea } from '../utils';
  */
 /* @__PURE__ */
 export function InteractableArea(props) {
-    const { top, left, right, bottom } = getInteractableArea();
+    // Insets are canvas px; pre-divide so the parser's scale multiplication cancels out.
+    const { top, left, right, bottom } = compensateInsetForUiScale(getInteractableArea());
     const { uiTransform, ...otherProps } = props;
     return (ReactEcs.createElement(UiEntity, { ...otherProps, uiTransform: {
             ...uiTransform,

package/dist/components/ScreenInsetArea/index.js

@@ -1,6 +1,6 @@
 import { ReactEcs } from '../../react-ecs';
 import { UiEntity } from '../index';
-import { getScreenInsetArea } from '../utils';
+import { compensateInsetForUiScale, getScreenInsetArea } from '../utils';
 /**
  *
  * @public
@@ -22,7 +22,8 @@ import { getScreenInsetArea } from '../utils';
  */
 /* @__PURE__ */
 export function ScreenInsetArea(props) {
-    const { top, left, right, bottom } = getScreenInsetArea();
+    // Insets are canvas px; pre-divide so the parser's scale multiplication cancels out.
+    const { top, left, right, bottom } = compensateInsetForUiScale(getScreenInsetArea());
     const { uiTransform, ...otherProps } = props;
     return (ReactEcs.createElement(UiEntity, { ...otherProps, uiTransform: {
             ...uiTransform,

package/dist/components/utils.js

@@ -38,8 +38,8 @@ export function getScaleAndUnit(scaleUnit) {
 /**
  * @internal
  */
-export function scaleOnDim(scale, dim, pxRatio) {
-    return (dim / 100) * (scale / pxRatio);
+export function scaleOnDim(scale, dim) {
+    return (dim / 100) * scale;
 }
 /**
  * @internal
@@ -90,6 +90,21 @@ export function resetUiScaleFactor(owner) {
     uiScaleOwner = undefined;
     uiScaleFactor = 1;
 }
+/**
+ * Divides an inset area by the current UI scale factor.
+ *
+ * Inset areas are reported by the renderer in canvas pixels, but raw pixel
+ * values in `uiTransform` props are multiplied by the UI scale factor when
+ * parsed. Pre-dividing cancels that multiplication out, so the values sent to
+ * the renderer stay in canvas pixels regardless of the virtual screen.
+ *
+ * @internal
+ */
+export function compensateInsetForUiScale(area) {
+    const scale = getUiScaleFactor();
+    const factor = scale > 0 ? scale : 1;
+    return { top: area.top / factor, left: area.left / factor, right: area.right / factor, bottom: area.bottom / factor };
+}
 /**
  * @internal
  */
@@ -169,9 +184,12 @@ export function calcOnViewport(value, ctx = getScaleCtx()) {
     const [scale, unit] = getScaleAndUnit(value);
     if (!ctx)
         return scale;
-    const { height, width, ratio } = ctx;
+    // `ctx.ratio` is intentionally not read: '1vw' is 1% of the canvas width by
+    // definition, exactly as in CSS. It stays on ScaleContext as an informational
+    // density hint for callers that need to pick an asset resolution.
+    const { height, width } = ctx;
     if (unit === 'vh')
-        return scaleOnDim(scale, height, ratio);
+        return scaleOnDim(scale, height);
     // by default, we scale by 'vw' (width)
-    return scaleOnDim(scale, width, ratio);
+    return scaleOnDim(scale, width);
 }

package/dist/platform.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Injects the function used to detect whether the scene runs on a mobile
+ * platform. Called by `@dcl/sdk` with its `isMobile()` platform helper.
+ */
+export declare function setIsMobileProvider(provider: () => boolean): void;
+/**
+ * Whether the scene is running on a mobile platform, according to the
+ * injected provider. Platform detection is asynchronous on the SDK side, so
+ * this may return false during the first ticks and flip to true once the
+ * explorer information arrives.
+ */
+export declare function isMobile(): boolean;

package/dist/platform.js

@@ -0,0 +1,26 @@
+/**
+ * Platform detection hook for the UI scale system.
+ *
+ * react-ecs stays independent of the scene runtime (`~system/*` modules), so
+ * it cannot ask the explorer which platform it runs on. Instead, the host SDK
+ * injects the check at module-load time (see `@dcl/sdk/react-ecs`). Until a
+ * provider is injected — or when none ever is — the platform is assumed to be
+ * non-mobile.
+ */
+let isMobileProvider = () => false;
+/**
+ * Injects the function used to detect whether the scene runs on a mobile
+ * platform. Called by `@dcl/sdk` with its `isMobile()` platform helper.
+ */
+export function setIsMobileProvider(provider) {
+    isMobileProvider = provider;
+}
+/**
+ * Whether the scene is running on a mobile platform, according to the
+ * injected provider. Platform detection is asynchronous on the SDK side, so
+ * this may return false during the first ticks and flip to true once the
+ * explorer information arrives.
+ */
+export function isMobile() {
+    return isMobileProvider();
+}

package/dist/system.d.ts

@@ -4,12 +4,29 @@ import type { ReactEcs } from './react-ecs';
  * @public
  */
 export type UiComponent = () => ReactEcs.JSX.ReactNode;
+/**
+ * Screen area used to position a renderer's UI entities:
+ * - `'device'` (default): the device safe area (excludes notch, status bar,
+ *   rounded corners), reported in `UiCanvasInformation.screenInsetArea`.
+ * - `'interactable'`: the area free of the Explorer's native HUD (minimap, chat, ...),
+ *   reported in `UiCanvasInformation.interactableArea`.
+ * - `'none'`: the whole screen, with 0,0 at its top-left corner.
+ * @public
+ */
+export type UiScreenInset = 'device' | 'interactable' | 'none';
 /**
  * @public
  */
 export type UiRendererOptions = {
-    virtualWidth: number;
-    virtualHeight: number;
+    virtualWidth?: number;
+    virtualHeight?: number;
+    /**
+     * Screen area the renderer's UI is positioned in. Defaults to `'device'`, so UI
+     * stays inside the device safe area unless the creator opts out with `'none'`.
+     * Each renderer honors its own value, so the main UI and additional renderers
+     * can use different insets simultaneously.
+     */
+    screenInset?: UiScreenInset;
 };
 /**
  * @public
@@ -21,6 +38,16 @@ export interface ReactBasedUiSystem {
     destroy(): void;
     /**
      * Set the main UI renderer. Optional virtual size defines the global UI scale factor.
+     *
+     * When no virtual size is provided, a platform default is used: 1600x720 on
+     * mobile, 1920x1080 otherwise. Providing an invalid size disables the virtual
+     * screen (no UI scaling): either a value \<= 0, or only one of the two
+     * dimensions, which additionally logs a warning. On mobile, a provided 16:9
+     * virtual size is overridden to 1600x720 to fit phone screens.
+     *
+     * The optional `screenInset` selects the screen area the UI is positioned in
+     * (see {@link UiScreenInset}); it defaults to `'device'`. Pass `'none'` to
+     * place the UI over the whole screen.
      */
     setUiRenderer(ui: UiComponent, options?: UiRendererOptions): void;
     /**
@@ -35,7 +62,10 @@ export interface ReactBasedUiSystem {
      * @param entity - The entity to associate with this UI renderer. When the entity is removed,
      *                 the UI renderer is automatically cleaned up.
      * @param ui - The UI component to render
-     * @param options - Optional virtual size used for UI scale factor when main UI has none
+     * @param options - Optional virtual size used for UI scale factor when main UI has none.
+     *                  Defaults and the mobile 16:9 override behave as in {@link ReactBasedUiSystem.setUiRenderer}.
+     *                  `screenInset` is honored per renderer, independently of the main UI's value,
+     *                  and defaults to `'device'` here too.
      */
     addUiRenderer(entity: Entity, ui: UiComponent, options?: UiRendererOptions): void;
     /**

package/dist/system.js

@@ -3,13 +3,49 @@ import * as ecsComponents from '@dcl/ecs/dist/components';
 import React from 'react';
 import { createReconciler } from './reconciler';
 import { getUiScaleFactor, resetInteractableArea, resetScreenInsetArea, resetUiScaleFactor, setInteractableArea, setScreenInsetArea, setUiScaleFactor } from './components/utils';
+import { InteractableArea, ScreenInsetArea } from './components';
+import { isMobile } from './platform';
+/**
+ * Default virtual screen size used on mobile platforms, and the size 16:9
+ * virtual screens are overridden to on mobile (phone screens are much wider
+ * than 16:9, so a 16:9 virtual canvas would letterbox the UI).
+ */
+const DEFAULT_MOBILE_VIRTUAL_SIZE = { virtualWidth: 1600, virtualHeight: 720 };
+/**
+ * Default virtual screen size used on non-mobile platforms.
+ */
+const DEFAULT_VIRTUAL_SIZE = { virtualWidth: 1920, virtualHeight: 1080 };
+/**
+ * Screen area a renderer uses when it doesn't pick one. UI defaults to the device
+ * safe area: drawing under a notch, a status bar or a rounded corner is something
+ * a creator should opt into, not the out-of-the-box behavior.
+ */
+const DEFAULT_SCREEN_INSET = 'device';
+function hasVirtualSize(options) {
+    return !!options && (options.virtualWidth !== undefined || options.virtualHeight !== undefined);
+}
+function isValidVirtualSize(options) {
+    return !!options && (options.virtualWidth ?? 0) > 0 && (options.virtualHeight ?? 0) > 0;
+}
+/**
+ * Whether a provided size spells out one dimension but not the other. Both are
+ * optional in the type, so this is reachable. It is invalid either way — this only
+ * decides whether to warn, since a half-given size is a mistake while a value
+ * \<= 0 is the documented way to turn the virtual screen off.
+ */
+function isPartialVirtualSize(options) {
+    return (options.virtualWidth === undefined) !== (options.virtualHeight === undefined);
+}
+function is16by9(options) {
+    return options.virtualWidth * 9 === options.virtualHeight * 16;
+}
 /**
  * @public
  */
 export function createReactBasedUiSystem(engine, pointerSystem) {
     const renderer = createReconciler(engine, pointerSystem);
     let uiComponent = undefined;
-    let virtualSize = undefined;
+    let mainOptions = undefined;
     const additionalRenderers = new Map();
     const UiCanvasInformation = ecsComponents.UiCanvasInformation(engine);
     // Unique owner to prevent other UI systems resetting this scale factor.
@@ -18,21 +54,92 @@ export function createReactBasedUiSystem(engine, pointerSystem) {
     const screenInsetAreaOwner = Symbol('react-ecs-screen-inset-area');
     // Unique owner for the interactable area module variable.
     const interactableAreaOwner = Symbol('react-ecs-interactable-area');
+    // Last 16:9 size we already logged the mobile override for, so the log
+    // fires once per provided size instead of every tick. Tracked as raw numbers
+    // to avoid allocating a comparison string every tick.
+    let loggedMobileOverrideW = 0;
+    let loggedMobileOverrideH = 0;
+    // Same once-per-size guard for the incomplete-size warning. A partial size maps
+    // its missing dimension to 0, and the provided one can itself be 0, so -1 is the
+    // "nothing logged yet" sentinel — 0/0 is a reachable real value here.
+    let loggedPartialW = -1;
+    let loggedPartialH = -1;
     function getActiveVirtualSize() {
         // Main renderer options win; otherwise use the first additional renderer option.
-        if (virtualSize)
-            return virtualSize;
+        // Options carrying no virtual dims (e.g. only a screen inset) are skipped so
+        // they don't count as a provided-but-invalid virtual size.
+        if (hasVirtualSize(mainOptions))
+            return mainOptions;
         for (const entry of additionalRenderers.values()) {
-            if (entry.options)
+            if (hasVirtualSize(entry.options))
                 return entry.options;
         }
         return undefined;
     }
+    /**
+     * Resolves the virtual screen to scale the UI against, or `undefined` when
+     * the virtual screen is disabled.
+     */
+    function resolveVirtualSize() {
+        const provided = getActiveVirtualSize();
+        const mobile = isMobile();
+        // No creator-provided size: fall back to the platform default.
+        if (!provided) {
+            return mobile ? DEFAULT_MOBILE_VIRTUAL_SIZE : DEFAULT_VIRTUAL_SIZE;
+        }
+        // An explicitly provided but invalid size disables the virtual screen — no UI
+        // scaling at all. That covers a value <= 0 (the deliberate opt-out) and a size
+        // that gives only one of its two dimensions.
+        if (!isValidVirtualSize(provided)) {
+            // A half-given size is a mistake rather than an opt-out, and disabling scaling
+            // is not what the creator was reaching for, so say so once per provided size.
+            // The <= 0 opt-out is documented and stays silent.
+            if (isPartialVirtualSize(provided)) {
+                const width = provided.virtualWidth ?? 0;
+                const height = provided.virtualHeight ?? 0;
+                if (loggedPartialW !== width || loggedPartialH !== height) {
+                    loggedPartialW = width;
+                    loggedPartialH = height;
+                    console.log(`Incomplete virtual screen size (virtualWidth: ${provided.virtualWidth}, virtualHeight: ${provided.virtualHeight}): both dimensions are required, so the virtual screen is disabled and no UI scaling is applied.`);
+                }
+            }
+            return undefined;
+        }
+        // On mobile, 16:9 virtual screens don't fit phone aspect ratios — override them.
+        if (mobile && is16by9(provided)) {
+            if (loggedMobileOverrideW !== provided.virtualWidth || loggedMobileOverrideH !== provided.virtualHeight) {
+                loggedMobileOverrideW = provided.virtualWidth;
+                loggedMobileOverrideH = provided.virtualHeight;
+                console.log(`Mobile platform detected: overriding 16:9 virtual screen size ${provided.virtualWidth}x${provided.virtualHeight} with ${DEFAULT_MOBILE_VIRTUAL_SIZE.virtualWidth}x${DEFAULT_MOBILE_VIRTUAL_SIZE.virtualHeight}`);
+            }
+            return DEFAULT_MOBILE_VIRTUAL_SIZE;
+        }
+        return provided;
+    }
+    /**
+     * Wraps a renderer's component in a container positioned within the selected
+     * screen inset area. `'none'` adds no wrapper, leaving the UI on the whole
+     * screen. Applied per renderer, so each renderer can use a different inset.
+     */
+    function wrapWithScreenInset(ui, inset, key) {
+        // An omitted inset is resolved to DEFAULT_SCREEN_INSET ('device') before the
+        // switch, so it lands on `case 'device'`. Only an explicit 'none' reaches the
+        // `default` clause below — the two are unrelated despite sharing a name.
+        switch (inset ?? DEFAULT_SCREEN_INSET) {
+            case 'device':
+                return React.createElement(ScreenInsetArea, { key }, React.createElement(ui));
+            case 'interactable':
+                return React.createElement(InteractableArea, { key }, React.createElement(ui));
+            // 'none' — the whole screen, no wrapper entity
+            default:
+                return React.createElement(ui, { key });
+        }
+    }
     function ReactBasedUiSystem() {
         const components = [];
         // Add main UI component
         if (uiComponent) {
-            components.push(React.createElement(uiComponent, { key: '__main__' }));
+            components.push(wrapWithScreenInset(uiComponent, mainOptions?.screenInset, '__main__'));
         }
         const entitiesToRemove = [];
         for (const [entity, entry] of additionalRenderers) {
@@ -41,7 +148,7 @@ export function createReactBasedUiSystem(engine, pointerSystem) {
                 entitiesToRemove.push(entity);
             }
             else {
-                components.push(React.createElement(entry.ui, { key: `__entity_${entity}__` }));
+                components.push(wrapWithScreenInset(entry.ui, entry.options?.screenInset, `__entity_${entity}__`));
             }
         }
         // Entity-based cleanup
@@ -68,22 +175,33 @@ export function createReactBasedUiSystem(engine, pointerSystem) {
         if (canvasInfo?.interactableArea) {
             setInteractableArea(canvasInfo.interactableArea, interactableAreaOwner);
         }
-        const activeVirtualSize = getActiveVirtualSize();
-        if (!activeVirtualSize) {
+        // The virtual screen (provided or defaulted) only applies while some
+        // renderer is registered; with no UI at all the scale factor is released.
+        if (uiComponent === undefined && additionalRenderers.size === 0) {
             // Reset only if this system owns the scale factor.
             resetUiScaleFactor(uiScaleFactorOwner);
             return;
         }
+        const activeVirtualSize = resolveVirtualSize();
+        if (!activeVirtualSize) {
+            // Virtual screen explicitly disabled by an invalid provided size.
+            resetUiScaleFactor(uiScaleFactorOwner);
+            return;
+        }
         if (!canvasInfo)
             return;
-        const { width, height, devicePixelRatio } = canvasInfo;
+        const { width, height } = canvasInfo;
         const { virtualWidth, virtualHeight } = activeVirtualSize;
-        if (!virtualWidth || !virtualHeight)
-            return;
-        // Normalize by devicePixelRatio so virtual px map to logical px (matching the
-        // vw/vh path); without it the scale was inflated on high-dpr mobile screens.
-        const ratio = devicePixelRatio || 1;
-        const nextScale = Math.min(width / virtualWidth, height / virtualHeight) / ratio;
+        // The scale factor is the contain-fit of the design resolution inside the canvas,
+        // and nothing else.
+        //
+        // devicePixelRatio is deliberately absent. It is a density hint — "how many physical
+        // pixels per canvas unit", for picking a 1x/2x/3x asset — not a layout unit, the same
+        // role it has in CSS and React Native, where it is exposed but never enters layout.
+        // Dividing by it made UI size inversely proportional to a quantity the scene author
+        // does not control and that measures something different on every renderer: panel
+        // density on mobile, OS display scaling on web, display/window on native desktop.
+        const nextScale = Math.min(width / virtualWidth, height / virtualHeight);
         if (Number.isFinite(nextScale) && nextScale !== getUiScaleFactor()) {
             // Track ownership when updating to avoid cross-system conflicts.
             setUiScaleFactor(nextScale, uiScaleFactorOwner);
@@ -104,7 +222,7 @@ export function createReactBasedUiSystem(engine, pointerSystem) {
         },
         setUiRenderer(ui, options) {
             uiComponent = ui;
-            virtualSize = options;
+            mainOptions = options;
         },
         addUiRenderer(entity, ui, options) {
             additionalRenderers.set(entity, { ui, options });

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dcl/react-ecs",
   "description": "Decentraland ECS",
-  "version": "7.25.1-31496802383.commit-d3168c9",
+  "version": "7.25.1-31605440953.commit-08dff78",
   "author": "DCL",
   "bugs": "https://github.com/decentraland/js-sdk-toolchain/issues",
   "dependencies": {
-    "@dcl/ecs": "7.25.1-31496802383.commit-d3168c9",
+    "@dcl/ecs": "7.25.1-31605440953.commit-08dff78",
     "react": "^18.2.0",
     "react-reconciler": "^0.29.0"
   },
@@ -40,5 +40,5 @@
     "tsconfig": "./tsconfig.json"
   },
   "types": "./dist/index.d.ts",
-  "commit": "d3168c9833ced3a80eba5de83601e5dff7f00a75"
+  "commit": "08dff7864080ec5e4a06b533827c69799774a2f2"
 }