Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(ui): synchronize virtualized lists with resolved viewport bounds

yhh0cbf55db3dac
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 954ad2d59..ade1c5477 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Virtualized lists follow their resolved UI viewport.** Layout constraints, window changes and safe areas update the visible range, linear row sizing and scroll limits together. Viewport and content changes clamp the offset once, preserving reachable final rows. The list sample fills its constrained panes so rows no longer overlap the footer.
+
- **Native UI follows the device safe area.** iOS view insets and Android content bounds reach `SafeArea` in surface pixels, including delayed layouts and landscape side changes. The localization and virtualized-list samples place their text and controls inside authored safe-area containers so the iPhone cutout does not cover paragraphs or list rows.
- **The installed macOS MCP entry launches the bundled editor.** It reads `CFBundleExecutable` from the app's Info.plist instead of assuming the product name matches the executable file.
diff --git a/docs/astro/src/content/docs/ui/lists.mdx b/docs/astro/src/content/docs/ui/lists.mdx
index 843259d1d..abe336005 100644
--- a/docs/astro/src/content/docs/ui/lists.mdx
+++ b/docs/astro/src/content/docs/ui/lists.mdx
@@ -49,7 +49,7 @@ satisfies it).
|---|---|---|
| `world` / `host` | — | The ECS world and the ticking plugin (`uiPlugin`). Required. |
| `parent` | root | Parent entity for the viewport. |
-| `viewportSize` | — | Pixel size of the visible window. Required — the scroll math needs it up front. |
+| `viewportSize` | — | Initial UI layout size. Required; virtualization and scroll bounds follow the resolved viewport box. |
| `node` | sized to `viewportSize` | Extra `UINode` props for the viewport box. |
| `background` | transparent | Viewport visual. The default is an invisible **hit-target** — it must exist so the wheel and drag land on the list. |
| `data` | — | A `DataSource<T>`, or a raw array (wrapped in an `ArrayDataSource` — the array is **copied**, so mutate the source afterwards, not your original array). |
@@ -72,6 +72,11 @@ satisfies it).
### The item template
+For a viewport that fills a constrained parent, set `node` dimensions with
+`percent(100)`. Window or safe-area changes then update the visible range and
+scroll limits together. Default linear layouts also fit the resolved cross axis;
+grids and custom providers retain their authored item sizing.
+
An item template is a **create / bind** pair (`ListItemTemplate<T>`):
```typescript
@@ -369,6 +374,10 @@ scroll range · `scroll` (the underlying `ScrollContainer`) · `dispose()`.
## The scrolling model
+Manual compositions can use `scroll.setSizes(viewportSize, contentSize)` to
+update both extents before clamping. This preserves a valid offset during resize
+and emits only the final changed offset.
+
Both factories drive a **`ScrollContainer`** — a pure scroll-state model with
no input or ECS knowledge. It clamps the offset to `[0, contentSize −
viewportSize]` per axis (a `'vertical'` container pins `x` to 0 and vice
diff --git a/docs/astro/src/content/docs/zh-cn/ui/lists.mdx b/docs/astro/src/content/docs/zh-cn/ui/lists.mdx
index 794063351..8e81afc3c 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/lists.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/lists.mdx
@@ -43,7 +43,7 @@ const list = createListView<Player>({
|---|---|---|
| `world` / `host` | — | ECS world 与负责 tick 的插件(`uiPlugin`)。必填。 |
| `parent` | 根 | 视口的父实体。 |
-| `viewportSize` | — | 可见窗口的像素尺寸。必填——滚动数学需要预先知道。 |
+| `viewportSize` | — | 初始 UI 布局尺寸。必填;虚拟化与滚动边界跟随布局解算后的视口盒。 |
| `node` | 尺寸取 `viewportSize` | 视口盒的额外 `UINode` 属性。 |
| `background` | 透明 | 视口视觉。默认是不可见的**命中目标**——它必须存在,滚轮和拖拽才能落在列表上。 |
| `data` | — | 一个 `DataSource<T>`,或裸数组(会被包成 `ArrayDataSource`——数组会被**拷贝**,之后请改数据源而不是你的原数组)。 |
@@ -66,6 +66,10 @@ const list = createListView<Player>({
### 条目模板
+视口需要填满受约束的父容器时,可用 `percent(100)` 设置 `node` 尺寸。
+窗口或安全区变化后,可见条目范围与滚动边界一起更新。默认线性布局的交叉轴
+也跟随解算后的尺寸;网格和自定义布局保留所定义的条目大小。
+
条目模板是一对 **create / bind**(`ListItemTemplate<T>`):
```typescript
@@ -329,6 +333,9 @@ panel.scrollTo({ x: 0, y: 300 });
## 滚动模型
+手动组合可通过 `scroll.setSizes(viewportSize, contentSize)` 先同时更新两个范围,
+再约束偏移。这样调整尺寸时不会丢失仍然有效的位置,也只通知最终变化的偏移。
+
两个工厂驱动的都是 **`ScrollContainer`**——不含输入与 ECS 知识的纯滚动状态模型。
它把偏移按轴收敛到 `[0, contentSize − viewportSize]`(`'vertical'` 容器把 `x` 钉在 0,
反之亦然),任何变化都通知 `onScroll` 监听者。工厂订阅它并把内容框平移 `-offset`;
diff --git a/examples/ui-list/README.md b/examples/ui-list/README.md
index a89a2dc6d..08a2e80ea 100644
--- a/examples/ui-list/README.md
+++ b/examples/ui-list/README.md
@@ -44,3 +44,7 @@ scene-plus-factories split as the `ui-controls` example.
The panel sits under an absolute `SafeArea` content container. Device cutouts
move the whole interactive list and its controls together; the panel keeps its
authored margins inside that container.
+
+The panes and widget viewports fill their constrained parent heights. After
+layout, the widgets use their resolved sizes for virtualization and scrolling,
+so a home indicator or a smaller window cannot hide the last row behind the footer.
diff --git a/examples/ui-list/assets/scenes/main.esscene b/examples/ui-list/assets/scenes/main.esscene
index 03e414954..2e1283e40 100644
--- a/examples/ui-list/assets/scenes/main.esscene
+++ b/examples/ui-list/assets/scenes/main.esscene
@@ -141,7 +141,7 @@
"type": "UINode",
"data": {
"width": { "value": 340, "unit": 0 },
- "height": { "value": 404, "unit": 0 }
+ "height": { "value": 100, "unit": 1 }
}
},
{
@@ -208,7 +208,7 @@
"type": "UINode",
"data": {
"width": { "value": 336, "unit": 0 },
- "height": { "value": 404, "unit": 0 }
+ "height": { "value": 100, "unit": 1 }
}
},
{
diff --git a/examples/ui-list/src/config.ts b/examples/ui-list/src/config.ts
index 0ba36da17..48d6550e9 100644
--- a/examples/ui-list/src/config.ts
+++ b/examples/ui-list/src/config.ts
@@ -1,7 +1,7 @@
import type { Color } from 'esengine';
-// Viewport sizes must be known up front (createListView needs them for the
-// scroll math); the slot boxes in the scene use the same numbers.
+// Initial viewport hints match the authored slots. Layout constraints can shrink
+// those slots; the widget synchronizes its scroll and virtualized window afterward.
export const LIST_W = 340;
export const LIST_H = 378;
export const GRID_W = 336;
diff --git a/examples/ui-list/src/systems/build.ts b/examples/ui-list/src/systems/build.ts
index 6354d0341..6ae887451 100644
--- a/examples/ui-list/src/systems/build.ts
+++ b/examples/ui-list/src/systems/build.ts
@@ -6,7 +6,7 @@ import {
createListView, createButton,
ArrayDataSource,
spawnUIEntity,
- themeColors, px,
+ themeColors, px, percent,
UIPositionType, TextVerticalAlign,
} from 'esengine';
import type {
@@ -81,6 +81,7 @@ export const buildSystem = defineSystem(
host: uiPlugin,
world, parent: listSlot,
viewportSize: { x: LIST_W, y: LIST_H },
+ node: { width: percent(100), height: percent(100) },
background: { color: { r: 0.11, g: 0.11, b: 0.13, a: 1 } },
data: contacts,
layout: { itemHeight: ROW_H, spacing: ROW_SPACING },
@@ -111,6 +112,7 @@ export const buildSystem = defineSystem(
host: uiPlugin,
world, parent: gridSlot,
viewportSize: { x: GRID_W, y: GRID_H },
+ node: { width: percent(100), height: percent(100) },
background: { color: { r: 0.11, g: 0.11, b: 0.13, a: 1 } },
data: Array.from({ length: TILES }, (_, i) => i),
layout: { columns: GRID_COLUMNS, itemSize: { x: TILE, y: TILE }, spacing: { x: TILE_SPACING, y: TILE_SPACING } },
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 0bad39cfc..1f7bef6c3 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -7549,6 +7549,7 @@ onScroll: (listener: ScrollListener) => () => void
scrollBy: (delta: Vec2) => void
setContentSize: (size: Vec2) => void
setOffset: (offset: Vec2) => void
+setSizes: (viewport: Vec2, content: Vec2) => void
setViewportSize: (size: Vec2) => void
static new (opts: ScrollContainerOptions): ScrollContainer
static prototype: ScrollContainer
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 742e0f01c..684b86404 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -7753,6 +7753,7 @@ onScroll: (listener: ScrollListener) => () => void
scrollBy: (delta: Vec2) => void
setContentSize: (size: Vec2) => void
setOffset: (offset: Vec2) => void
+setSizes: (viewport: Vec2, content: Vec2) => void
setViewportSize: (size: Vec2) => void
static new (opts: ScrollContainerOptions): ScrollContainer
static prototype: ScrollContainer
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ad67d80ce..5acd8184a 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -7544,6 +7544,7 @@ onScroll: (listener: ScrollListener) => () => void
scrollBy: (delta: Vec2) => void
setContentSize: (size: Vec2) => void
setOffset: (offset: Vec2) => void
+setSizes: (viewport: Vec2, content: Vec2) => void
setViewportSize: (size: Vec2) => void
static new (opts: ScrollContainerOptions): ScrollContainer
static prototype: ScrollContainer
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index ca0d4999d..48ffb97cd 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -7817,6 +7817,7 @@ onScroll: (listener: ScrollListener) => () => void
scrollBy: (delta: Vec2) => void
setContentSize: (size: Vec2) => void
setOffset: (offset: Vec2) => void
+setSizes: (viewport: Vec2, content: Vec2) => void
setViewportSize: (size: Vec2) => void
static new (opts: ScrollContainerOptions): ScrollContainer
static prototype: ScrollContainer
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index ae4f9a849..f2b668f6f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -7551,6 +7551,7 @@ onScroll: (listener: ScrollListener) => () => void
scrollBy: (delta: Vec2) => void
setContentSize: (size: Vec2) => void
setOffset: (offset: Vec2) => void
+setSizes: (viewport: Vec2, content: Vec2) => void
setViewportSize: (size: Vec2) => void
static new (opts: ScrollContainerOptions): ScrollContainer
static prototype: ScrollContainer
diff --git a/sdk/src/ui/collection/scroll-container.ts b/sdk/src/ui/collection/scroll-container.ts
index c3f52ef81..cdbf09570 100644
--- a/sdk/src/ui/collection/scroll-container.ts
+++ b/sdk/src/ui/collection/scroll-container.ts
@@ -113,14 +113,19 @@ export class ScrollContainer {
}
setViewportSize(size: Vec2): void {
- if (size.x === this.viewportSize_.x && size.y === this.viewportSize_.y) return;
- this.viewportSize_ = { x: size.x, y: size.y };
- this.setOffset(this.offset_); // re-clamp
+ this.setSizes(size, this.contentSize_);
}
setContentSize(size: Vec2): void {
- if (size.x === this.contentSize_.x && size.y === this.contentSize_.y) return;
- this.contentSize_ = { x: size.x, y: size.y };
+ this.setSizes(this.viewportSize_, size);
+ }
+
+ /** Update both extents before clamping, so resize emits only its final offset. */
+ setSizes(viewport: Vec2, content: Vec2): void {
+ if (viewport.x === this.viewportSize_.x && viewport.y === this.viewportSize_.y
+ && content.x === this.contentSize_.x && content.y === this.contentSize_.y) return;
+ this.viewportSize_ = { x: viewport.x, y: viewport.y };
+ this.contentSize_ = { x: content.x, y: content.y };
this.setOffset(this.offset_);
}
diff --git a/sdk/src/ui/widgets/list-view.ts b/sdk/src/ui/widgets/list-view.ts
index 5e4f7f667..14a79b5ae 100644
--- a/sdk/src/ui/widgets/list-view.ts
+++ b/sdk/src/ui/widgets/list-view.ts
@@ -35,8 +35,87 @@ import {
MeasuredLinearLayoutProvider,
GridLayoutProvider,
} from '../collection/layout-provider';
-import { ListView } from '../collection/list-view';
+import { ListView, type ListViewOptions } from '../collection/list-view';
import { ScrollContainer } from '../collection/scroll-container';
+import { worldEngineApi, type EngineApi } from '../../ecs/bridge/engineApi';
+import { WasmBridge } from '../../wasm/WasmBridge';
+
+class ViewportBridge extends WasmBridge<NonNullable<EngineApi>> {
+ protected readonly label = 'listViewport';
+}
+
+/** Linear UI items fill the resolved cross axis; custom layouts keep their own sizes. */
+class CrossAxisLayout implements LayoutProvider {
+ constructor(private readonly base_: LayoutProvider, private readonly axis_: 'vertical' | 'horizontal',
+ private crossSize_: number) {}
+
+ resize(size: Vec2): void {
+ this.crossSize_ = this.axis_ === 'vertical' ? size.x : size.y;
+ }
+
+ getContentSize(count: number): Vec2 {
+ const size = this.base_.getContentSize(count);
+ if (count <= 0) return size;
+ return this.axis_ === 'vertical' ? { x: this.crossSize_, y: size.y } : { x: size.x, y: this.crossSize_ };
+ }
+
+ getItemRect(index: number): Rect {
+ const rect = this.base_.getItemRect(index);
+ return this.axis_ === 'vertical' ? { ...rect, width: this.crossSize_ } : { ...rect, height: this.crossSize_ };
+ }
+
+ getVisibleRange(viewport: Rect, count: number): [number, number] {
+ return this.base_.getVisibleRange(viewport, count);
+ }
+
+ invalidate(): void {
+ (this.base_ as LayoutProvider & { invalidate?: () => void }).invalidate?.();
+ }
+}
+
+/** The actual UI box owns the visible range and scroll bounds, in layout-local units. */
+class LayoutBoundListView<T> extends ListView<T> {
+ private uiDisposed_ = false;
+ private readonly viewportWorld_: World;
+ private readonly bounds_ = new ViewportBridge();
+ private boundsEngine_: EngineApi | null = null;
+
+ constructor(opts: ListViewOptions<T>, private readonly viewport_: Entity,
+ private readonly scroll_: ScrollContainer, private readonly crossLayout_: CrossAxisLayout | null) {
+ super(opts);
+ this.viewportWorld_ = opts.world;
+ }
+
+ override update(): void {
+ if (this.uiDisposed_ || !this.viewportWorld_.valid(this.viewport_)) return;
+ const engine = worldEngineApi(this.viewportWorld_);
+ const registry = this.viewportWorld_.getCppRegistry();
+ if (engine && registry && engine !== this.boundsEngine_) {
+ this.bounds_.connect(engine);
+ this.boundsEngine_ = engine;
+ }
+ const bounds = engine && registry ? this.bounds_.module : null;
+ const x = bounds?.getUINodeComputedWidth?.(registry!, this.viewport_) ?? 0;
+ const y = bounds?.getUINodeComputedHeight?.(registry!, this.viewport_) ?? 0;
+ const current = this.getViewport();
+ // Unresolved layout keeps the initial hint; only finite resolved boxes resize.
+ if (Number.isFinite(x) && Number.isFinite(y) && x > 0 && y > 0
+ && (x !== current.width || y !== current.height)) {
+ const size = { x, y };
+ this.crossLayout_?.resize(size);
+ this.setViewportSize(size);
+ this.scroll_.setSizes(size, this.getContentSize());
+ }
+ super.update();
+ }
+
+ override dispose(): void {
+ this.uiDisposed_ = true;
+ this.bounds_.disconnect();
+ this.boundsEngine_ = null;
+ super.dispose();
+ }
+}
/**
* The per-frame runtime a list view plugs into: the tick registry that drives
@@ -71,7 +150,7 @@ export interface CreateListViewOptions<T> {
/** The plugin that ticks virtualization + routes scroll input (`uiPlugin`). */
host: ListViewHost;
parent?: Entity;
- /** Pixel size of the visible window. Required — scroll math needs it up front. */
+ /** Initial UI layout size; virtualization and scroll bounds follow the resolved box. */
viewportSize: Vec2;
/** Extra viewport UINode props (its size defaults to `viewportSize`). */
node?: UINodeInit;
@@ -203,9 +282,14 @@ export function createListView<T>(opts: CreateListViewOptions<T>): ListViewHandl
// 3) Resolve data + layout.
const data: DataSource<T> = isDataSource(opts.data) ? opts.data : new ArrayDataSource<T>(opts.data);
- const { layout, axis } = isLayoutProvider(opts.layout)
+ const resolved = isLayoutProvider(opts.layout)
? { layout: opts.layout, axis: 'vertical' as const }
: buildLayout(opts.layout, viewportSize);
+ const { axis } = resolved;
+ const crossLayout = !isLayoutProvider(opts.layout) && !('columns' in opts.layout)
+ ? new CrossAxisLayout(resolved.layout, axis, axis === 'vertical' ? viewportSize.x : viewportSize.y)
+ : null;
+ const layout = crossLayout ?? resolved.layout;
// 4) Item templates → ViewPool template shape ({ factory, binder }).
const single = 'create' in opts.item && 'bind' in opts.item;
@@ -215,8 +299,16 @@ export function createListView<T>(opts: CreateListViewOptions<T>): ListViewHandl
templates[type] = { factory: tpl.create, binder: tpl.bind };
}
- // 5) The virtualization driver, parented to the content frame.
- const view = new ListView<T>({
+ // The scroll model and virtualization driver share the resolved viewport.
+ const scroll = new ScrollContainer({
+ viewportSize,
+ contentSize: layout.getContentSize(data.getCount()),
+ direction: opts.direction ?? axis,
+ wheelSpeed: opts.wheelSpeed,
+ dragScroll: opts.dragScroll,
+ decelerationRate: opts.decelerationRate,
+ });
+ const view = new LayoutBoundListView<T>({
world,
parent: content,
dataSource: data,
@@ -227,19 +319,10 @@ export function createListView<T>(opts: CreateListViewOptions<T>): ListViewHandl
placeItem: (w, e, rect) => placeByInset(w, e, rect),
setVisible: (w, e, v) => setUIVisible(w, e, v),
onItemBound: opts.onItemBound,
- });
+ }, viewport, scroll, crossLayout);
host.registerListView(view as ListView<unknown>);
- // 6) Scroll model: wheel- and drag-driven by the plugin; onScroll translates
- // the content frame and pushes the offset into the driver.
- const scroll = new ScrollContainer({
- viewportSize,
- contentSize: layout.getContentSize(data.getCount()),
- direction: opts.direction ?? axis,
- wheelSpeed: opts.wheelSpeed,
- dragScroll: opts.dragScroll,
- decelerationRate: opts.decelerationRate,
- });
+ // Scroll input translates the content and pushes the same offset into the driver.
const offScroll = scroll.onScroll((offset) => {
const n = world.get(content, UINode) as UINodeData;
n.insetLeft = px(-offset.x);
diff --git a/sdk/tests/ui-list-view-widget.test.ts b/sdk/tests/ui-list-view-widget.test.ts
index 5ab1e47a4..a054c8f6e 100644
--- a/sdk/tests/ui-list-view-widget.test.ts
+++ b/sdk/tests/ui-list-view-widget.test.ts
@@ -11,10 +11,12 @@ import { describe, it, expect, beforeAll } from 'vitest';
import { App } from '../src/app/app';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
import { uiPlugin } from '../src/ui/ui-plugin';
-import { createListView } from '../src/ui/widgets/list-view';
+import { createListView, type ListViewHandle } from '../src/ui/widgets/list-view';
import { spawnUIEntity } from '../src/ui/core/compose';
import { arrayDataSource } from '../src/ui/collection/data-source';
-import { px } from '../src/ui/core/dimension';
+import { px, percent } from '../src/ui/core/dimension';
+import { UINode, type UINodeData } from '../src/ui/core/ui-node';
+import { Canvas } from '../src/ecs/component';
import type { ESEngineModule, CppRegistry } from '../src/wasm';
import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
@@ -144,4 +146,97 @@ describe.skipIf(!HAS_WASM)('createListView (WASM integration)', () => {
list.dispose();
disposeApp(app, registry);
});
+
+ it('keeps a constrained viewport, scroll range and final row in agreement after resize', async () => {
+ const { app, registry } = createApp();
+ const parent = spawnUIEntity({ world: app.world, node: { width: px(180), height: px(140) } });
+ app.world.insert(parent, Canvas, {});
+ const list = createListView<number>({
+ host: uiPlugin, world: app.world, parent,
+ viewportSize: { x: 200, y: 200 },
+ node: { width: percent(100), height: percent(100) },
+ data: bigList(100), layout: { itemHeight: 40 }, item: numberRow,
+ });
+ try {
+ module.uiLayout_update(registry, 0, 0, 800, 600, true);
+ expect(module.getUINodeComputedHeight(registry, list.entity)).toBe(140);
+ await app.tick(1 / 60);
+ expect(list.scroll.getViewportSize()).toEqual({ x: 180, y: 140 });
+ const node = app.world.get(parent, UINode) as UINodeData;
+ node.width = px(160);
+ node.height = px(80);
+ app.world.insert(parent, UINode, node);
+ module.uiLayout_update(registry, 0, 0, 800, 600, true);
+ await app.tick(1 / 60);
+ expect(list.scroll.getViewportSize()).toEqual({ x: 160, y: 80 });
+ expect(list.view.getContentSize().x).toBe(160);
+ list.scrollToIndex(99);
+ await app.tick(1 / 60);
+ expect(list.scroll.getOffset().y).toBe(3920);
+ expect(list.view.getVisibleRange()).toEqual([98, 100]);
+ expect(list.mountedCount()).toBeLessThanOrEqual(6);
+ node.width = px(240);
+ node.height = px(240);
+ app.world.insert(parent, UINode, node);
+ module.uiLayout_update(registry, 0, 0, 800, 600, true);
+ await app.tick(1 / 60);
+ expect(list.scroll.getViewportSize()).toEqual({ x: 240, y: 240 });
+ expect(list.scroll.getOffset().y).toBe(3760);
+ expect(list.view.getViewport().y).toBe(3760);
+ } finally {
+ list.dispose();
+ disposeApp(app, registry);
+ }
+ });
+
+ it('reads viewport geometry from its own world after another app binds UI', () => {
+ const first = createApp();
+ const root = spawnUIEntity({ world: first.app.world, node: { width: px(180), height: px(140) } });
+ first.app.world.insert(root, Canvas, {});
+ const list = createListView<number>({ host: uiPlugin, world: first.app.world, parent: root,
+ viewportSize: { x: 200, y: 200 }, node: { width: percent(100), height: percent(100) },
+ data: bigList(100), layout: { itemHeight: 40 }, item: numberRow });
+ module.uiLayout_update(first.registry, 0, 0, 800, 600, true);
+ const second = createApp();
+ try {
+ list.view.update();
+ expect(list.scroll.getViewportSize()).toEqual({ x: 180, y: 140 });
+ expect(list.view.getViewport().width).toBe(180);
+ } finally {
+ list.dispose();
+ disposeApp(first.app, first.registry);
+ disposeApp(second.app, second.registry);
+ }
+ });
+
+ it('remeasures variable-height items at the new width before clamping the scroll extent', async () => {
+ const { app, registry } = createApp();
+ const parent = spawnUIEntity({ world: app.world, node: { width: px(180), height: px(140) } });
+ app.world.insert(parent, Canvas, {});
+ let list: ListViewHandle<number> | undefined;
+ list = createListView<number>({ host: uiPlugin, world: app.world, parent,
+ viewportSize: { x: 200, y: 200 }, node: { width: percent(100), height: percent(100) },
+ data: bigList(100), item: numberRow,
+ layout: { itemHeight: () => (list?.view.getViewport().width ?? 200) > 160 ? 40 : 80 } });
+ try {
+ module.uiLayout_update(registry, 0, 0, 800, 600, true);
+ await app.tick(1 / 60);
+ list.scroll.setOffset({ x: 0, y: 850 });
+ const node = app.world.get(parent, UINode) as UINodeData;
+ node.width = px(160);
+ node.height = px(80);
+ app.world.insert(parent, UINode, node);
+ module.uiLayout_update(registry, 0, 0, 800, 600, true);
+ await app.tick(1 / 60);
+ expect(list.scroll.getOffset().y).toBe(850);
+ expect(list.scroll.getContentSize()).toEqual({ x: 160, y: 8000 });
+ list.scrollToIndex(99);
+ await app.tick(1 / 60);
+ expect(list.scroll.getOffset().y).toBe(7920);
+ expect(list.view.getVisibleRange()).toEqual([99, 100]);
+ } finally {
+ list.dispose();
+ disposeApp(app, registry);
+ }
+ });
});
diff --git a/sdk/tests/ui-scroll-container.test.ts b/sdk/tests/ui-scroll-container.test.ts
index be88cd7ae..5f0691572 100644
--- a/sdk/tests/ui-scroll-container.test.ts
+++ b/sdk/tests/ui-scroll-container.test.ts
@@ -4,6 +4,19 @@ import { describe, it, expect, vi } from 'vitest';
import { ScrollContainer, ScrollContainerRegistry } from '../src/ui';
describe('ScrollContainer', () => {
+ it('resizes both extents without an intermediate clamp losing the current row', () => {
+ const c = new ScrollContainer({ viewportSize: { x: 100, y: 100 },
+ contentSize: { x: 100, y: 1000 }, initialOffset: { x: 0, y: 850 } });
+ const changed = vi.fn();
+ c.onScroll(changed);
+ c.setSizes({ x: 100, y: 50 }, { x: 100, y: 900 });
+ expect(c.getOffset().y).toBe(850);
+ expect(changed).not.toHaveBeenCalled();
+ c.setSizes({ x: 100, y: 200 }, { x: 100, y: 950 });
+ expect(c.getOffset().y).toBe(750);
+ expect(changed).toHaveBeenCalledTimes(1);
+ expect(changed).toHaveBeenLastCalledWith({ x: 0, y: 750 });
+ });
it('clamps initial offset to [0, max]', () => {
const c = new ScrollContainer({
viewportSize: { x: 200, y: 100 },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2e9cc73b1..813cc700e 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(ui): synchronize virtualized lists with resolved viewport bounds':
+ { note: 'Virtualized lists follow their resolved UI viewport.' },
'fix(samples): keep virtualized UI inside device safe areas':
{ note: 'Native UI follows the device safe area.' },
'fix(verification): read renderer counters after a completed frame':