feat: ui renderer default virtual screen

creator/sdk7/2d-ui/onscreen-ui.md

@@ -168,7 +168,7 @@ A definition of a UI module can only have one parent-level entity. You can defin
 
 ## Screen Virtual Scale
 
-Set a vitual width and height for the UI. This is encouraged to make sure your UI looks the same on different screen sizes, regardless of the actual screen size in pixels.
+Set a virtual width and height for the UI. This makes sure your UI looks the same on different screen sizes, regardless of the actual screen size in pixels.
 
 ```ts
 export function setupUi() {
@@ -180,6 +180,45 @@ If you set a virtual width to 1920, and a virtual height to 1080, the UI will be
 
 The actual calculation for the Ui Scale Factor that gets multiplied on pixel values is [`Math.min(realWidth / virtualWidth, realHeight / virtualHeight) / devicePixelRatio`](https://github.com/decentraland/js-sdk-toolchain/blob/main/packages/%40dcl/react-ecs/src/system.ts)
 
+### Default virtual screen
+
+If you **don't** provide a virtual size, a platform default is now applied automatically, so your UI is scaled consistently even when you don't set one explicitly:
+
+* **1600x720 on mobile**
+* **1920x1080 on any other platform** (desktop, web)
+
+```ts
+export function setupUi() {
+    // No virtual size provided → a platform default is applied automatically
+    ReactEcsRenderer.setUiRenderer(uiComponent)
+}
+```
+
+{% hint style="info" %}
+**📔 Note**: This default applies to both `setUiRenderer()` and `addUiRenderer()`. In earlier SDK versions, omitting the virtual size meant no scaling was applied at all. Scenes that relied on that behavior will now see their pixel values scaled against the platform default.
+{% endhint %}
+
+The virtual size is resolved on every tick, so it reacts correctly when the platform is detected as mobile a few frames after the scene starts.
+
+### Mobile 16:9 override
+
+Phone screens are much wider than 16:9, so a 16:9 virtual canvas would letterbox the UI on mobile. To avoid this, when a **valid 16:9** virtual size (e.g. `1920x1080` or `1280x720`) is provided **on mobile**, it is automatically overridden to **1600x720**. A message is logged to the console (once per provided size) to inform you of the override.
+
+Non-16:9 sizes on mobile, and any valid size on desktop/web, are respected as provided.
+
+### Disabling the virtual screen
+
+If you want to opt out of any UI scaling entirely — including the platform default — provide an **explicitly invalid** virtual size (any value less than or equal to `0`):
+
+```ts
+export function setupUi() {
+    // Disable the virtual screen: no UI scaling is applied
+    ReactEcsRenderer.setUiRenderer(uiComponent, { virtualWidth: -1, virtualHeight: -1 })
+}
+```
+
+With an invalid size, the virtual screen is disabled: no UI scaling is applied, and any previously applied scale factor is released. This matches the old behavior of calling `setUiRenderer()` with no options.
+
 ## Multiple UI modules
 
 If your scene contains multiple systems or modules that each define their own UI, you can render each UI module with `ReactEcsRenderer.addUiRenderer()`. This is especially useful when working on a complex scene with multiple UI components, or when defining UIs for a [smart item](../smart-items/smart-items.md), which should be usable independent of what's in the code of the rest of the scene.

creator/sdk7/building-for-mobile/ui-best-practices.md

@@ -29,6 +29,10 @@ The single most useful recommendation when adapting an existing desktop UI to mo
 
 Combined with the SDK's `virtualWidth` / `virtualHeight` setup, this gives you readable text, comfortably tappable buttons, and a layout that holds up across devices. Always confirm the result on a real phone — see [Preview on mobile](preview-on-mobile.md).
 
+{% hint style="info" %}
+**📔 Note**: On mobile, if you don't provide a virtual size, the SDK applies a **1600x720** default (instead of the **1920x1080** used on desktop/web). Phone screens are much wider than 16:9, so if you provide a valid 16:9 virtual size (e.g. `1920x1080`) on mobile it is automatically overridden to **1600x720** to avoid letterboxing the UI. See [Screen Virtual Scale](../2d-ui/onscreen-ui.md#screen-virtual-scale) for the full behavior, including how to disable UI scaling entirely.
+{% endhint %}
+
 ## Current limitations
 
 These limitations apply to scene UI on the current mobile client. They are tracked and expected to be lifted over time.