lynx-family · ykai55 · Aug 14, 2026
diff --git a/core/renderer/dom/fiber/fiber_element.cc b/core/renderer/dom/fiber/fiber_element.cc
@@ -5220,6 +5220,11 @@ void Element::UpdateDynamicElementStyleRecursively(uint32_t style,
     }
   }
 
+  if (IsOverlay() && (style & DynamicCSSStylesManager::kUpdateScreenMetrics)) {
+    inner_force_update |= true;
+    MarkLayoutDirty();
+  }
+
   if ((dynamic_style_flags_ > 0 || inner_force_update) && !is_wrapper()) {
     // Style could never be "all" here.
     NotifyUnitValuesUpdatedToAnimation(style);

diff --git a/core/renderer/ui_wrapper/painting/ios/painting_context_darwin.mm b/core/renderer/ui_wrapper/painting/ios/painting_context_darwin.mm
@@ -484,6 +484,8 @@ void RunOnMainThreadSync(dispatch_block_t block) {
 
 std::vector<float> PaintingContextDarwin::getWindowSize(int id) {
   std::vector<float> res;
+  // TODO(xiamengfei.moonface): [ResizableWindowSize] Check whether this should use window or
+  // physical screen metrics.
   CGSize size = UIScreen.mainScreen.bounds.size;
   res.push_back(size.width);
   res.push_back(size.height);
@@ -532,6 +534,8 @@ void RunOnMainThreadSync(dispatch_block_t block) {
   LynxUI* ui = [uiOwner_ findUIBySign:id];
   if (ui != NULL) {
     CGRect re = [ui getRectToWindow];
+    // TODO(xiamengfei.moonface): [ResizableWindowScale] Check whether this should use window or
+    // physical screen metrics.
     int scale = UIScreen.mainScreen.scale;
     res.push_back(re.origin.x * scale);
     res.push_back(re.origin.y * scale);

diff --git a/core/renderer/ui_wrapper/painting/ios/platform_renderer_context_darwin.mm b/core/renderer/ui_wrapper/painting/ios/platform_renderer_context_darwin.mm
@@ -30,6 +30,8 @@
 }
 
 CGSize PlatformRendererContextDarwin::GetScreenSize() {
+  // TODO(xiamengfei.moonface): [ResizableWindowSize] Check whether this should use window or
+  // physical screen metrics.
   CGSize size = UIScreen.mainScreen.bounds.size;
   return size;
 }

diff --git a/platform/darwin/common/lynx/LynxScreenMetrics.m b/platform/darwin/common/lynx/LynxScreenMetrics.m
@@ -32,12 +32,22 @@ - (instancetype)init {
 
 - (instancetype)initWithScreenSize:(CGSize)screenSize scale:(CGFloat)scale {
   if (self = [self init]) {
-    [self setLynxScreenSize:screenSize];
+    _screenSize = screenSize;
     _scale = scale;
   }
   return self;
 }
 
+// Keep the legacy setters for source and binary compatibility. New code should create immutable
+// snapshots with initWithScreenSize:scale: instead.
+- (void)setScreenSize:(CGSize)screenSize {
+  _screenSize = screenSize;
+}
+
+- (void)setScale:(CGFloat)scale {
+  _scale = scale;
+}
+
 - (void)setLynxScreenSize:(CGSize)screenSize {
   _screenSize = screenSize;
 }

diff --git a/platform/darwin/common/lynx/public/LynxScreenMetrics.h b/platform/darwin/common/lynx/public/LynxScreenMetrics.h
@@ -10,12 +10,17 @@
 NS_ASSUME_NONNULL_BEGIN
 
 @interface LynxScreenMetrics : NSObject
-@property(nonatomic, assign, readwrite) CGSize screenSize;
-@property(nonatomic, assign, readwrite) CGFloat scale;
+@property(nonatomic, assign, readonly) CGSize screenSize;
+@property(nonatomic, assign, readonly) CGFloat scale;
 
 + (LynxScreenMetrics*)getDefaultLynxScreenMetrics;
 - (instancetype)initWithScreenSize:(CGSize)screenSize scale:(CGFloat)scale;
-- (void)setLynxScreenSize:(CGSize)screenSize;
+- (void)setScreenSize:(CGSize)screenSize
+    __attribute__((deprecated("Use initWithScreenSize:scale: to create an immutable snapshot.")));
+- (void)setScale:(CGFloat)scale
+    __attribute__((deprecated("Use initWithScreenSize:scale: to create an immutable snapshot.")));
+- (void)setLynxScreenSize:(CGSize)screenSize
+    __attribute__((deprecated("Use initWithScreenSize:scale: to create an immutable snapshot.")));
 
 @end
 

diff --git a/platform/darwin/common/lynx/public/LynxTemplateRenderProtocol.h b/platform/darwin/common/lynx/public/LynxTemplateRenderProtocol.h
@@ -22,6 +22,7 @@ NS_ASSUME_NONNULL_BEGIN
 @class LynxTemplateData;
 @class LynxUpdateMeta;
 @class LynxContext;
+@class LynxScreenMetrics;
 @protocol LynxModule;
 
 @protocol LynxTemplateRenderProtocol <NSObject>
@@ -164,6 +165,10 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void)updateScreenMetricsWithWidth:(CGFloat)width height:(CGFloat)height;
 
+- (void)updateScreenMetricsWithWidth:(CGFloat)width height:(CGFloat)height scale:(CGFloat)scale;
+
+- (void)updateScreenMetrics:(LynxScreenMetrics*)screenMetrics;
+
 - (void)updateFontScale:(CGFloat)scale;
 
 - (void)updateColorScheme:(LynxColorScheme)scheme;

diff --git a/platform/darwin/ios/api/lynx_ios.api b/platform/darwin/ios/api/lynx_ios.api
@@ -633,6 +633,7 @@ public class LynxBaseConfigurator : NSObject {
   public id<LynxTemplateResourceFetcher> LynxBaseConfigurator::templateResourceFetcher templateResourceFetcher;
   public BOOL LynxBaseConfigurator::enableFetchUIImage enableFetchUIImage;
   public CGSize LynxBaseConfigurator::screenSize screenSize;
+  public CGFloat LynxBaseConfigurator::screenScale screenScale;
   public BOOL LynxBaseConfigurator::debuggable debuggable;
   public BOOL LynxBaseConfigurator::enablePreUpdateData enablePreUpdateData;
   public LynxBackgroundJsRuntimeType LynxBaseConfigurator::backgroundJsRuntimeType backgroundJsRuntimeType;
@@ -3481,7 +3482,9 @@ public class LynxScreenMetrics : NSObject {
   public CGFloat LynxScreenMetrics::scale scale;
   public LynxScreenMetrics * LynxScreenMetrics::getDefaultLynxScreenMetrics();
   public instancetype LynxScreenMetrics::initWithScreenSize:scale:(CGSize screenSize,[scale] CGFloat scale);
-  public void LynxScreenMetrics::setLynxScreenSize:(CGSize screenSize);
+  public void LynxScreenMetrics::setScreenSize:((deprecated("Use initWithScreenSize:scale: to create an immutable snapshot.")) __attribute__);
+  public void LynxScreenMetrics::setScale:((deprecated("Use initWithScreenSize:scale: to create an immutable snapshot.")) __attribute__);
+  public void LynxScreenMetrics::setLynxScreenSize:((deprecated("Use initWithScreenSize:scale: to create an immutable snapshot.")) __attribute__);
 }
 
 public class LynxScrollEventManager : NSObject {
@@ -4066,6 +4069,8 @@ public protocol LynxTemplateRenderProtocol-p : <NSObject> {
   public void LynxTemplateRenderProtocol-p::updateViewport();
   public void LynxTemplateRenderProtocol-p::updateViewport:(BOOL needLayout);
   public void LynxTemplateRenderProtocol-p::updateScreenMetricsWithWidth:height:(CGFloat width,[height] CGFloat height);
+  public void LynxTemplateRenderProtocol-p::updateScreenMetricsWithWidth:height:scale:(CGFloat width,[height] CGFloat height,[scale] CGFloat scale);
+  public void LynxTemplateRenderProtocol-p::updateScreenMetrics:(LynxScreenMetrics *screenMetrics);
   public void LynxTemplateRenderProtocol-p::updateFontScale:(CGFloat scale);
   public void LynxTemplateRenderProtocol-p::updateColorScheme:(LynxColorScheme scheme);
   public void LynxTemplateRenderProtocol-p::pauseRootLayoutAnimation();
@@ -4747,6 +4752,7 @@ public class LynxUIContext : NSObject {
   public int64_t LynxUIContext::shellPtr shellPtr;
   public id<ListNodeInfoFetcherProtocol> LynxUIContext::fetcher fetcher;
   public LynxScreenMetrics* LynxUIContext::screenMetrics screenMetrics;
+  public LynxViewportMetrics* LynxUIContext::viewportMetrics viewportMetrics;
   public LynxUIIntersectionObserverManager* LynxUIContext::intersectionManager intersectionManager;
   public LynxUIExposure* LynxUIContext::uiExposure uiExposure;
   public NSDictionary* LynxUIContext::keyframesDict keyframesDict;
@@ -4813,6 +4819,8 @@ public class LynxUIContext : NSObject {
   public void LynxUIContext::resumeExposure();
   public void LynxUIContext::findShadowNodeAndRunTask:task:(NSInteger sign,[task] void(^ task)(LynxShadowNode *));
   public nullable id< LynxResourceFetcher > LynxUIContext::getGenericResourceFetcher();
+  public void LynxUIContext()::updateScreenMetrics:(LynxScreenMetrics *screenMetrics);
+  public void LynxUIContext()::updateViewportMetrics:(nullable LynxViewportMetrics *viewportMetrics);
   public void LynxUIContext()::setUIConfig:(id< LUIConfig > config);
   public void LynxUIContext()::setDefaultOverflowVisible:(BOOL enable);
   public void LynxUIContext()::setDefaultImplicitAnimation:(BOOL enable);
@@ -5318,6 +5326,8 @@ public protocol LynxUIRendererProtocol-p : <NSObject> {
   public void LynxUIRendererProtocol-p::setImageFetcherInUIOwner:(id< LynxImageFetcher > imageFetcher);
   public void LynxUIRendererProtocol-p::setResourceFetcherInUIOwner:(id< LynxResourceFetcher > resourceFetcher);
   public void LynxUIRendererProtocol-p::updateScreenWidth:height:(CGFloat width,[height] CGFloat height);
+  public void LynxUIRendererProtocol-p::updateScreenMetrics:(LynxScreenMetrics *screenMetrics);
+  public void LynxUIRendererProtocol-p::updateViewportMetrics:(nullable LynxViewportMetrics *viewportMetrics);
   public void LynxUIRendererProtocol-p::pauseRootLayoutAnimation();
   public void LynxUIRendererProtocol-p::resumeRootLayoutAnimation();
   public void LynxUIRendererProtocol-p::restartAnimation();
@@ -5539,6 +5549,8 @@ public class LynxView : UIView, <LUIBodyView>, <LynxSecurityTarget>, <LynxRender
   public double LynxView::subscribeSessionStorage:withCallback:(nonnull NSString *key,[withCallback] void(^_Nullable callback)(id< NSObject > _Nullable));
   public void LynxView::unSubscribeSessionStorage:withId:(nonnull NSString *key,[withId] double callbackId);
   public void LynxView::updateScreenMetricsWithWidth:height:(CGFloat width,[height] CGFloat height);
+  public void LynxView::updateScreenMetricsWithWidth:height:scale:(CGFloat width,[height] CGFloat height,[scale] CGFloat scale);
+  public void LynxView::updateScreenMetrics:(nonnull LynxScreenMetrics *screenMetrics);
   public void LynxView::updateFontScale:(CGFloat scale);
   public void LynxView::getLynxElementRoot:(void(^_Nullable callback)(LynxElement *_Nullable root));
   public void LynxView::updateColorScheme:(LynxColorScheme scheme);
@@ -5696,6 +5708,13 @@ public protocol LynxViewLifecycleV2-p : <LynxViewBaseLifecycle>, <LynxPerformanc
   public void LynxViewLifecycleV2-p::onResourceLoaded:(nonnull LynxResourceLoadInfo *result);
 }
 
+public class LynxViewportMetrics : NSObject {
+  public CGSize LynxViewportMetrics::size size;
+  public LynxViewSizeMode LynxViewportMetrics::widthMode widthMode;
+  public LynxViewSizeMode LynxViewportMetrics::heightMode heightMode;
+  public instancetype LynxViewportMetrics::initWithSize:widthMode:heightMode:(CGSize size,[widthMode] LynxViewSizeMode widthMode,[heightMode] LynxViewSizeMode heightMode);
+}
+
 public protocol LynxViewVisibleHelper-p : <NSObject> {
   public BOOL LynxViewVisibleHelper-p::IsViewVisible();
 }

diff --git a/platform/darwin/ios/lynx/BUILD.gn b/platform/darwin/ios/lynx/BUILD.gn
@@ -158,6 +158,7 @@ subspec_target("lynx") {
     "LynxViewBuilder+Internal.h",
     "LynxViewBuilder.mm",
     "LynxViewGroup.mm",
+    "LynxViewportMetrics.m",
     "LynxWasmFuncRegistry.mm",
     "PaintingContextProxy.h",
     "PaintingContextProxy.mm",
@@ -480,6 +481,7 @@ subspec_target("UnitTests") {
     "../../common/lynx/performance/memory/LynxMemoryUsageQueryUnitTest.m",
     "LynxElementUnitTest.m",
     "LynxModuleManagerDarwinUnitTest.mm",
+    "LynxRuntimeMetricsUnitTest.m",
     "LynxTemplateRenderMemoryUsageUnitTest.mm",
     "LynxUnitTestUtils.h",
     "LynxUnitTestUtils.mm",

diff --git a/platform/darwin/ios/lynx/LynxBaseConfigurator.mm b/platform/darwin/ios/lynx/LynxBaseConfigurator.mm
@@ -12,11 +12,34 @@
 #import "LynxTraceEventDef.h"
 #import "LynxUIRendererCreator.h"
 
+#include <cmath>
+
 @implementation LynxBaseConfigurator {
   LynxEmbeddedMode _embeddedMode;
   NSMutableDictionary<NSString*, LynxAliasFontInfo*>* _builderRegisteredAliasFontMap;
 }
 
+- (void)setScreenSize:(CGSize)screenSize {
+  if (!CGSizeEqualToSize(screenSize, CGSizeZero) &&
+      (!std::isfinite(screenSize.width) || !std::isfinite(screenSize.height))) {
+    _LogE(@"Non-finite Lynx screen size %@ will fall back to the next configuration source.",
+          NSStringFromCGSize(screenSize));
+  } else if (!CGSizeEqualToSize(screenSize, CGSizeZero) &&
+             (screenSize.width <= 0 || screenSize.height <= 0)) {
+    _LogW(@"Invalid partial Lynx screen size %@ will fall back as a whole.",
+          NSStringFromCGSize(screenSize));
+  }
+  _screenSize = screenSize;
+}
+
+- (void)setScreenScale:(CGFloat)screenScale {
+  if (!std::isfinite(screenScale)) {
+    _LogE(@"Non-finite Lynx screen scale %f will fall back to the next configuration source.",
+          screenScale);
+  }
+  _screenScale = screenScale;
+}
+
 - (id)init {
   TRACE_EVENT(LYNX_TRACE_CATEGORY, LYNX_VIEW_BUILDER_INIT);
   self = [super init];

diff --git a/platform/darwin/ios/lynx/LynxRuntimeMetricsUnitTest.m b/platform/darwin/ios/lynx/LynxRuntimeMetricsUnitTest.m
@@ -0,0 +1,83 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+#import <Lynx/LynxScreenMetrics.h>
+#import <Lynx/LynxUIContext+Internal.h>
+#import <Lynx/LynxUIContext.h>
+#import <Lynx/LynxViewBuilder.h>
+#import <Lynx/LynxViewGroup.h>
+#import <Lynx/LynxViewportMetrics.h>
+#import <XCTest/XCTest.h>
+
+@interface LynxScreenMetricsUnitTest : XCTestCase
+@end
+
+@implementation LynxScreenMetricsUnitTest
+
+- (void)testBuilderScreenMetricsOverrideGroup {
+  LynxViewGroup* group = [[LynxViewGroup alloc] init];
+  group.screenSize = CGSizeMake(390, 844);
+  group.screenScale = 3;
+
+  LynxViewBuilder* builder = [[LynxViewBuilder alloc] init];
+  builder.lynxViewGroup = group;
+  XCTAssertTrue(CGSizeEqualToSize(builder.screenSize, CGSizeMake(390, 844)));
+  XCTAssertEqualWithAccuracy(builder.screenScale, 3, 0.001);
+
+  builder.screenSize = CGSizeMake(360, 800);
+  builder.screenScale = 2;
+  XCTAssertTrue(CGSizeEqualToSize(builder.screenSize, CGSizeMake(360, 800)));
+  XCTAssertEqualWithAccuracy(builder.screenScale, 2, 0.001);
+}
+
+- (void)testInvalidBuilderScreenMetricsFallBackToGroup {
+  LynxViewGroup* group = [[LynxViewGroup alloc] init];
+  group.screenSize = CGSizeMake(390, 844);
+  group.screenScale = 3;
+
+  LynxViewBuilder* builder = [[LynxViewBuilder alloc] init];
+  builder.lynxViewGroup = group;
+  builder.screenSize = CGSizeMake(360, 0);
+  builder.screenScale = NAN;
+
+  XCTAssertTrue(CGSizeEqualToSize(builder.screenSize, CGSizeMake(390, 844)));
+  XCTAssertEqualWithAccuracy(builder.screenScale, 3, 0.001);
+}
+
+- (void)testUIContextReplacesScreenMetricsSnapshot {
+  LynxScreenMetrics* initial = [[LynxScreenMetrics alloc] initWithScreenSize:CGSizeMake(390, 844)
+                                                                       scale:3];
+  LynxUIContext* context = [[LynxUIContext alloc] initWithScreenMetrics:initial];
+  LynxScreenMetrics* next = [[LynxScreenMetrics alloc] initWithScreenSize:CGSizeMake(360, 800)
+                                                                    scale:2];
+
+  [context updateScreenMetrics:next];
+
+  XCTAssertEqual(context.screenMetrics, next);
+  XCTAssertTrue(CGSizeEqualToSize(initial.screenSize, CGSizeMake(390, 844)));
+  XCTAssertEqualWithAccuracy(initial.scale, 3, 0.001);
+}
+
+- (void)testUIContextViewportMetricsLifecycle {
+  LynxScreenMetrics* screenMetrics =
+      [[LynxScreenMetrics alloc] initWithScreenSize:CGSizeMake(390, 844) scale:3];
+  LynxUIContext* context = [[LynxUIContext alloc] initWithScreenMetrics:screenMetrics];
+  XCTAssertNil(context.viewportMetrics);
+
+  LynxViewportMetrics* viewportMetrics =
+      [[LynxViewportMetrics alloc] initWithSize:CGSizeMake(320, 600)
+                                      widthMode:LynxViewSizeModeMax
+                                     heightMode:LynxViewSizeModeExact];
+  [context updateViewportMetrics:viewportMetrics];
+
+  XCTAssertEqual(context.viewportMetrics, viewportMetrics);
+  XCTAssertTrue(CGSizeEqualToSize(context.viewportMetrics.size, CGSizeMake(320, 600)));
+  XCTAssertEqual(context.viewportMetrics.widthMode, LynxViewSizeModeMax);
+  XCTAssertEqual(context.viewportMetrics.heightMode, LynxViewSizeModeExact);
+
+  [context updateViewportMetrics:nil];
+  XCTAssertNil(context.viewportMetrics);
+}
+
+@end