@rdlabo/ionic-theme-ios27 1.2.0-0 → 1.2.0-2

package/ios/Sources/IonicNativeUIShellPlugin/IonicNativeUIShellPlugin.swift

@@ -8,9 +8,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
     public let jsName = "IonicNativeUIShell"
     public let pluginMethods: [CAPPluginMethod] = [
         CAPPluginMethod(name: "configure", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "getDeviceLayout", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "startDeviceLayoutMonitoring", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "stopDeviceLayoutMonitoring", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getWebViewMetrics", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "update", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise)
     ]
@@ -27,16 +25,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
     private var pendingTabExpiryWorks: [String: DispatchWorkItem] = [:]
     private var restoreTopEdge: (() -> Void)?
     private var observers: [NSObjectProtocol] = []
-    private var lastVerticalBarEdge: String?
-    private var lastVerticalBarInset: CGFloat = 0
-    private var verticalBarPlacementObserved = false
-    private weak var observedVerticalBarView: UIView?
-    private var unregisterVerticalBarObservation: (() -> Void)?
-    private weak var observedHingeView: UIView?
-    private var hingeInteraction: UIInteraction?
-    private var hingeStatus: String?
-    private var deviceLayoutMonitoring = 0
-    private var lastDeviceLayout: String?
+    private var lastWebViewRadius: Double?
 
     public override func load() {
         for name in [UIApplication.didEnterBackgroundNotification, UIResponder.keyboardWillChangeFrameNotification, UIResponder.keyboardWillHideNotification,
@@ -68,7 +57,6 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                     }
                 } else if name == UIDevice.orientationDidChangeNotification {
                     self.notifyWebViewMetricsChange()
-                    self.notifyVerticalBarPlacementChange()
                 }
             })
         }
@@ -78,8 +66,6 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                 if name == UIResponder.keyboardDidHideNotification { self?.keyboardVisible = false }
                 self?.bridge?.triggerWindowJSEvent(eventName: "nativeUIShellRefresh", data: name == UIApplication.didBecomeActiveNotification ? "{\"retireSearch\":true}" : "{}")
                 if name == UIApplication.didBecomeActiveNotification { self?.notifyWebViewMetricsChange() }
-                if name == UIApplication.didBecomeActiveNotification { self?.notifyVerticalBarPlacementChange() }
-                if name == UIApplication.didBecomeActiveNotification { self?.refreshHingeStatus() }
             })
         }
     }
@@ -88,17 +74,6 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
         observers.forEach(NotificationCenter.default.removeObserver)
     }
 
-    private func stopDeviceLayoutObservation() {
-        unregisterVerticalBarObservation?()
-        unregisterVerticalBarObservation = nil
-        observedVerticalBarView = nil
-        if let interaction = hingeInteraction {
-            observedHingeView?.removeInteraction(interaction)
-        }
-        hingeInteraction = nil
-        observedHingeView = nil
-    }
-
     private func webViewMetrics() -> JSObject? {
         guard #available(iOS 26.0, *), let webView = bridge?.webView else { return nil }
         webView.layoutIfNeeded()
@@ -106,158 +81,21 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
     }
 
     private func notifyWebViewMetricsChange() {
-        notifyDeviceLayoutChange()
-    }
-
-    private func deviceLayout() -> JSObject {
-        var layout: JSObject = ["placement": verticalBarPlacement(),
-                                "webViewMetrics": webViewMetrics() ?? ["radius": 0]]
-        layout["hingeStatus"] = hingeStatus ?? NSNull()
-        return layout
-    }
-
-    private func notifyDeviceLayoutChange() {
-        guard deviceLayoutMonitoring > 0 else { return }
-        let layout = deviceLayout()
-        let fingerprint = "\(verticalBarEdge() ?? "none"):\(verticalBarInset(for: verticalBarEdge())):\(hingeStatus ?? "none"):\(webViewMetrics()?["radius"] ?? 0)"
-        guard fingerprint != lastDeviceLayout else { return }
-        lastDeviceLayout = fingerprint
-        notifyListeners("deviceLayoutChange", data: layout)
-    }
-
-    @objc func getDeviceLayout(_ call: CAPPluginCall) {
-        DispatchQueue.main.async { [weak self] in
-            self?.observeVerticalBarPlacement()
-            self?.observeHingeStatus()
-            self?.refreshHingeStatus()
-            DispatchQueue.main.async {
-                call.resolve(self?.deviceLayout() ?? ["placement": ["edge": NSNull(), "inset": 0], "hingeStatus": NSNull(), "webViewMetrics": ["radius": 0]])
-                if self?.deviceLayoutMonitoring == 0 { self?.stopDeviceLayoutObservation() }
-            }
-        }
+        let metrics = webViewMetrics() ?? ["radius": 0]
+        let radius = metrics["radius"] as? Double ?? 0
+        guard radius != lastWebViewRadius else { return }
+        lastWebViewRadius = radius
+        notifyListeners("webViewMetricsChange", data: metrics)
     }
 
-    @objc func startDeviceLayoutMonitoring(_ call: CAPPluginCall) {
+    @objc func getWebViewMetrics(_ call: CAPPluginCall) {
         DispatchQueue.main.async { [weak self] in
-            self?.deviceLayoutMonitoring += 1
-            self?.lastDeviceLayout = nil
-            self?.observeVerticalBarPlacement()
-            self?.observeHingeStatus()
-            self?.refreshHingeStatus()
-            call.resolve()
-        }
-    }
-
-    @objc func stopDeviceLayoutMonitoring(_ call: CAPPluginCall) {
-        DispatchQueue.main.async { [weak self] in
-            if let self, self.deviceLayoutMonitoring > 0 {
-                self.deviceLayoutMonitoring -= 1
-                if self.deviceLayoutMonitoring == 0 {
-                    self.lastDeviceLayout = nil
-                    self.stopDeviceLayoutObservation()
-                }
-            }
-            call.resolve()
+            call.resolve(self?.webViewMetrics() ?? ["radius": 0])
         }
     }
 
-    // Logical edge in the reading direction, matching UIVerticalBarEdge.
-    private func verticalBarEdge() -> String? {
-        #if canImport(UIKit, _underlyingVersion: 9127.0.85) && !targetEnvironment(macCatalyst)
-        if #available(iOS 27.1, *), let webView = bridge?.webView {
-            switch webView.traitCollection.verticalBarEdge {
-            case .leading: return "leading"
-            case .trailing: return "trailing"
-            default: break
-            }
-        }
-        #endif
-        // Toolchains older than the verticalBarEdge trait still expose the rail
-        // as a deep safe-area inset on the physical edge (iPhone Duo reserves
-        // ~80pt; ordinary iPhones stay below 70pt even in landscape).
-        guard let webView = bridge?.webView else { return nil }
-        webView.layoutIfNeeded()
-        let rtl = webView.effectiveUserInterfaceLayoutDirection == .rightToLeft
-        if webView.safeAreaInsets.right >= 70 { return rtl ? "leading" : "trailing" }
-        if webView.safeAreaInsets.left >= 70 { return rtl ? "trailing" : "leading" }
-        return nil
-    }
-
-    private func verticalBarInset(for edge: String?) -> CGFloat {
-        guard let edge, let webView = bridge?.webView else { return 0 }
-        webView.layoutIfNeeded()
-        let rtl = webView.effectiveUserInterfaceLayoutDirection == .rightToLeft
-        let physicalRight = (edge == "trailing") != rtl
-        return physicalRight ? webView.safeAreaInsets.right : webView.safeAreaInsets.left
-    }
-
-    private func verticalBarPlacement() -> JSObject {
-        if let edge = verticalBarEdge() { return ["edge": edge, "inset": Double(verticalBarInset(for: edge))] }
-        return ["edge": NSNull(), "inset": 0]
-    }
-
-    private func notifyVerticalBarPlacementChange() {
-        let edge = verticalBarEdge()
-        let inset = verticalBarInset(for: edge)
-        guard !verticalBarPlacementObserved || edge != lastVerticalBarEdge || abs(inset - lastVerticalBarInset) > 0.5 else { return }
-        verticalBarPlacementObserved = true
-        lastVerticalBarEdge = edge
-        lastVerticalBarInset = inset
-        notifyDeviceLayoutChange()
-    }
-
-    private func observeVerticalBarPlacement() {
-        #if canImport(UIKit, _underlyingVersion: 9127.0.85) && !targetEnvironment(macCatalyst)
-        if #available(iOS 27.1, *), let webView = bridge?.webView, observedVerticalBarView !== webView {
-            unregisterVerticalBarObservation?()
-            observedVerticalBarView = webView
-            let traits: [UITrait] = [UITraitLayoutDirection.self] + UITraitCollection.systemTraitsAffectingVerticalBarEdge
-            let registration = webView.registerForTraitChanges(traits) { [weak self] (_: UIView, _: UITraitCollection) in
-                self?.notifyVerticalBarPlacementChange()
-            }
-            unregisterVerticalBarObservation = { [weak webView] in webView?.unregisterForTraitChanges(registration) }
-        }
-        #endif
-        notifyVerticalBarPlacementChange()
-    }
-
-    private func observeHingeStatus() {
-        #if canImport(UIKit, _underlyingVersion: 9127.0.85) && !targetEnvironment(macCatalyst)
-        if #available(iOS 27.1, *), let webView = bridge?.webView, observedHingeView !== webView {
-            if let interaction = hingeInteraction {
-                observedHingeView?.removeInteraction(interaction)
-            }
-            observedHingeView = webView
-            let interaction = UIHingeInteraction { [weak self] _, update in
-                let status: String?
-                switch update.hinge?.status {
-                case .closed: status = "closed"
-                case .partiallyOpen: status = "partiallyOpen"
-                case .fullyOpen: status = "fullyOpen"
-                default: status = nil
-                }
-                guard status != self?.hingeStatus else { return }
-                self?.hingeStatus = status
-                self?.notifyDeviceLayoutChange()
-            }
-            hingeInteraction = interaction
-            webView.addInteraction(interaction)
-        }
-        #endif
-    }
-
-    private func refreshHingeStatus() {
-        #if canImport(UIKit, _underlyingVersion: 9127.0.85) && !targetEnvironment(macCatalyst)
-        if #available(iOS 27.1, *), let interaction = hingeInteraction as? UIHingeInteraction {
-            interaction.isEnabled = false
-            interaction.isEnabled = true
-        }
-        #endif
-    }
-
     @objc func configure(_ call: CAPPluginCall) {
         DispatchQueue.main.async { [weak self] in
-            self?.observeVerticalBarPlacement()
             // A new JS context starts revision numbering again (live reload / navigation).
             self?.restoreTopEdge?()
             self?.restoreTopEdge = nil
@@ -352,6 +190,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
             guard let snapshot = try? call.decode(ShellSnapshot.self), snapshot.isValid else {
                 call.reject("Invalid control snapshot"); return
             }
+            self.notifyWebViewMetricsChange()
             let duration = ShellCrossfade.duration(snapshot.transitionDuration)
             let existing = Set(self.controls.keys)
             let verticalBars = snapshot.controls.filter { $0.placement == .verticalBars }
@@ -379,6 +218,11 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                 let rail = self.verticalBars ?? ShellVerticalBarsController(activate: { [weak self] id in self?.activate(id) })
                 self.verticalBars = rail
                 rail.attach(to: owner, in: owner.view)
+                if let frame = snapshot.verticalBarFrame {
+                    rail.view.frame = webView.convert(frame.rect.applying(CGAffineTransform(scaleX: scale, y: scale)), to: owner.view)
+                } else {
+                    rail.view.frame = owner.view.bounds
+                }
                 rail.apply(verticalBars, rendering: self.rendering, edge: snapshot.verticalBarEdge ?? "right")
                 rail.view.isHidden = false
             } else {

package/ios/Sources/IonicNativeUIShellPlugin/Shared/ShellSnapshot.swift

@@ -11,11 +11,13 @@ struct ShellSnapshot: Decodable {
     let revision: Int
     let transitionDuration: Double?
     let viewportWidth: Double
+    let verticalBarFrame: ShellFrame?
     let verticalBarEdge: String?
     let controls: [ShellControl]
 
     var isValid: Bool {
         revision >= 0 && (transitionDuration.map { $0.isFinite && $0 >= 0 && $0 <= 500 } ?? true) && viewportWidth.isFinite && viewportWidth > 0 && controls.count <= 100 &&
+        (verticalBarFrame.map { $0.isValid } ?? true) &&
         (verticalBarEdge == nil || verticalBarEdge == "left" || verticalBarEdge == "right") &&
         Set(controls.map(\.id)).count == controls.count && controls.allSatisfy(\.isValid)
     }
@@ -105,6 +107,9 @@ struct ShellItemContent: Decodable, Equatable {
     let fontSize: Double
     let fontWeight: Double
     let color: String
+    let backgroundColor: String?
+    let borderColor: String?
+    let borderWidth: CGFloat?
     let badge: ShellBadge?
     var icon: String?
     var iconWidth: Double?

package/ios/Tests/IonicNativeUIShellPluginTests/ShellSnapshotTests.swift

@@ -22,6 +22,18 @@ final class ShellSnapshotTests: XCTestCase {
         try JSValueDecoder().decode(ShellSnapshot.self, from: ["revision": 1, "viewportWidth": width, "controls": controls])
     }
 
+    func testModalRailFrameIsOptionalAndRequiresPositiveBounds() throws {
+        var payload: JSObject = ["revision": 1, "viewportWidth": 466.0, "controls": [control()]]
+        let page = try JSValueDecoder().decode(ShellSnapshot.self, from: payload)
+        XCTAssertNil(page.verticalBarFrame)
+        for height in [339.0, 0.0, -1.0] {
+            payload["verticalBarFrame"] = ["x": 0.0, "y": 339.0, "width": 466.0, "height": height]
+            let modal = try JSValueDecoder().decode(ShellSnapshot.self, from: payload)
+            XCTAssertEqual(modal.isValid, height > 0)
+            XCTAssertEqual(modal.verticalBarFrame?.y, 339)
+        }
+    }
+
     @MainActor func testTabTypographyPreservesCSSWeightsAndSize() throws {
         let weights: [UIFont.Weight] = [.ultraLight, .thin, .light, .regular, .medium, .semibold, .bold, .heavy, .black]
         let tab = UITabBarItem()
@@ -37,6 +49,24 @@ final class ShellSnapshotTests: XCTestCase {
         }
     }
 
+    @MainActor func testVerticalBarsPreserveButtonAppearance() throws {
+        guard #available(iOS 26.0, *) else { throw XCTSkip("Requires SwiftUI adaptive controls") }
+        let controls = try decode([control(["kind": "ion-buttons", "items": [
+            item(["backgroundColor": "rgb(0, 122, 255)"]),
+            item(["id": "outline", "borderColor": "rgb(255, 0, 0)", "borderWidth": 2.0])
+        ]])]).controls
+        XCTAssertEqual(controls.first?.items.first?.content.backgroundColor, "rgb(0, 122, 255)")
+        let model = ShellVerticalBarsModel()
+        model.apply(controls, rendering: ShellRendering())
+        XCTAssertNotNil(model.groups.first?.items.first?.background)
+        XCTAssertNotNil(model.groups.first?.items.last?.borderColor)
+        XCTAssertEqual(model.groups.first?.items.last?.borderWidth, 2)
+        model.apply(try decode([control(["kind": "ion-button"])]).controls, rendering: ShellRendering())
+        XCTAssertNil(model.groups.first?.items.first?.background)
+        XCTAssertNil(model.groups.first?.items.first?.borderColor)
+        XCTAssertEqual(model.groups.first?.items.first?.borderWidth, 0)
+    }
+
     @MainActor func testVerticalBarsTabOptimismWaitsForWebAndRollsBackWhenStale() throws {
         guard #available(iOS 26.0, *) else { throw XCTSkip("Requires SwiftUI adaptive tabs") }
         func tabs(_ selected: String, includeRight: Bool = true) throws -> [ShellControl] {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "1.2.0-0",
+  "version": "1.2.0-2",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/index.ts

@@ -8,6 +8,7 @@ export {
 export * from './tab-bar-searchable';
 export * from './searchbar';
 export * from './transition/ios.transition';
+export { withNativeUIShellTransition } from './native-integration/transition';
 export { registerSegmentEffect } from './segment';
 
 export const registerTabBarEffect = (targetElement: HTMLElement): registeredEffect | undefined => {
@@ -16,24 +17,55 @@ export const registerTabBarEffect = (targetElement: HTMLElement): registeredEffe
   const reducedMotion = win.matchMedia('(prefers-reduced-motion: reduce)');
   const verticalBarsRoot = targetElement.closest('ion-app');
   let effect: registeredEffect | undefined;
+  let placement: 'disabled' | 'horizontal' | 'left' | 'right' | undefined;
   const update = () => {
-    effect?.destroy();
     const isVertical =
-      !!verticalBarsRoot?.classList.contains('ios-theme-vertical-bars') && !targetElement.closest('ion-menu, ion-modal, ion-popover');
-    effect =
-      reducedMotion.matches || isVertical
-        ? undefined
-        : registerEffect(targetElement, 'ion-tab-button', 'tab-selected', {
+      !!verticalBarsRoot?.classList.contains('ios-theme-vertical-bars') &&
+      targetElement.matches('ion-tabs > ion-tab-bar:not(.ios-theme-disabled, .ios26-disabled)') &&
+      !targetElement.closest('ion-menu, ion-modal, ion-popover');
+    const disabled = reducedMotion.matches || !targetElement.matches('.ios:not(.ios-theme-disabled, .ios26-disabled)');
+    const nextPlacement = disabled
+      ? 'disabled'
+      : isVertical
+        ? verticalBarsRoot?.classList.contains('ios-theme-vertical-bars-left')
+          ? 'left'
+          : 'right'
+        : 'horizontal';
+    // Gesture/activation classes also change during interaction. Rebuild only when
+    // eligibility or placement changes, retaining cancellation when the rail changes sides.
+    if (placement === nextPlacement) return;
+    placement = nextPlacement;
+    effect?.destroy();
+    effect = disabled
+      ? undefined
+      : registerEffect(
+          targetElement,
+          'ion-tab-button',
+          'tab-selected',
+          {
             small: 'scale(1.1, 1)',
             medium: 'scale(1.2)',
             large: 'scale(1.15, 1.4)',
             xlarge: 'scale(1.3)',
-          });
+          },
+          isVertical,
+        );
   };
   update();
   reducedMotion.addEventListener('change', update);
-  const placementObserver = new win.MutationObserver(update);
-  if (verticalBarsRoot) placementObserver.observe(verticalBarsRoot, { attributes: true, attributeFilter: ['class'] });
+  const placementObserver = new win.MutationObserver((records) => {
+    if (
+      records.some((record) =>
+        record.type === 'attributes'
+          ? record.target === targetElement || record.target === verticalBarsRoot
+          : [...Array.from(record.addedNodes), ...Array.from(record.removedNodes)].some((node) => node.contains(targetElement)),
+      )
+    )
+      update();
+  });
+  if (verticalBarsRoot)
+    placementObserver.observe(verticalBarsRoot, { attributes: true, attributeFilter: ['class'], childList: true, subtree: true });
+  placementObserver.observe(targetElement, { attributes: true, attributeFilter: ['class'] });
   return {
     destroy: () => {
       reducedMotion.removeEventListener('change', update);

package/src/native/components/index.ts

@@ -31,7 +31,12 @@ export const isVerticalBarsCandidate = isVerticalBarsSource;
 
 export const readCandidate = (element: HTMLElement, id: Identify): Candidate | undefined => {
   const verticalBars = isVerticalBarsCandidate(element);
-  if ((!element.classList.contains('ios') && !verticalBars) || !visible(element, verticalBars) || element.closest('ion-modal, ion-popover'))
+  if (
+    (!element.classList.contains('ios') && !verticalBars) ||
+    !visible(element, verticalBars) ||
+    element.closest('ion-popover') ||
+    (element.closest('ion-modal') && !verticalBars)
+  )
     return;
   const style = getComputedStyle(element);
   if (

package/src/native/components/ion-button.ts

@@ -1,3 +1,4 @@
+import { modalUsesVerticalBars } from '../shared/modal';
 import { createCandidate, appendItem } from '../shared/candidate';
 import type { Candidate, Identify } from '../shared/candidate';
 import { inFixedToolbar, isVerticalBarsToolbarAction, isVerticalBarsToolbarGroup } from '../shared/dom';
@@ -6,15 +7,15 @@ export const tag = 'ion-button';
 
 export const read = (element: HTMLElement, id: Identify): Candidate | undefined => {
   const button = element as HTMLIonButtonElement;
-  const verticalBars = !element.closest('ion-menu, ion-modal, ion-popover') && !!element.closest('ion-app.ios-theme-vertical-bars');
+  const verticalBars =
+    !element.closest('ion-menu, ion-popover') && modalUsesVerticalBars(element) && !!element.closest('ion-app.ios-theme-vertical-bars');
   if (verticalBars && element.parentElement && isVerticalBarsToolbarGroup(element.parentElement)) return;
   const fill = button.fill ?? 'default';
   if (
     !inFixedToolbar(element) ||
     (verticalBars && !isVerticalBarsToolbarAction(element)) ||
     (!verticalBars && fill !== 'default') ||
-    (verticalBars && !['default', 'clear'].includes(fill)) ||
-    button.classList.contains('ion-color')
+    (!verticalBars && button.classList.contains('ion-color'))
   )
     return;
   const candidate = createCandidate(element, tag, id);

package/src/native/components/ion-buttons.ts

@@ -1,3 +1,4 @@
+import { modalUsesVerticalBars } from '../shared/modal';
 import { createCandidate, appendItem } from '../shared/candidate';
 import type { Candidate, Identify } from '../shared/candidate';
 import { childElements, verticalBarsToolbarActions, inFixedToolbar, isVerticalBarsToolbarGroup } from '../shared/dom';
@@ -10,7 +11,8 @@ export const read = (element: HTMLElement, id: Identify): Candidate | undefined
   if (!inFixedToolbar(element)) return;
   let children = childElements(element);
   if (children.length === 1) return menuButton.read(element, id);
-  const verticalBars = !element.closest('ion-menu, ion-modal, ion-popover') && !!element.closest('ion-app.ios-theme-vertical-bars');
+  const verticalBars =
+    !element.closest('ion-menu, ion-popover') && modalUsesVerticalBars(element) && !!element.closest('ion-app.ios-theme-vertical-bars');
   if (verticalBars && !isVerticalBarsToolbarGroup(element)) return;
   if (verticalBars) children = verticalBarsToolbarActions(element);
   if (
@@ -19,7 +21,7 @@ export const read = (element: HTMLElement, id: Identify): Candidate | undefined
       (child) =>
         !child.matches(`${menuButton.tag}${verticalBars ? '' : '.ios'}`) &&
         (!child.matches(`ion-button${verticalBars ? '' : '.ios.button-clear'}`) ||
-          !(verticalBars ? ['default', 'clear'] : ['clear']).includes((child as HTMLIonButtonElement).fill ?? 'default')),
+          (!verticalBars && (child as HTMLIonButtonElement).fill !== 'clear')),
     )
   )
     return;

package/src/native/definitions.ts

@@ -44,14 +44,10 @@ export type VerticalBarEdge = 'leading' | 'trailing' | null;
 
 export interface VerticalBarPlacement {
   edge: VerticalBarEdge;
-  /** UIKit safe-area inset on the vertical-bar edge, in points. */
-  inset: number;
-}
-
-export enum HingeStatus {
-  Closed = 'closed',
-  PartiallyOpen = 'partiallyOpen',
-  FullyOpen = 'fullyOpen',
+  /** Explicit rail width in CSS pixels; omitted to use the stylesheet's safe-area rules. */
+  inset?: number;
+  /** Native logical edge reported by the application's device plugin. Null or an unregistered edge uses a Web rail in verticalBarsOnly mode, or the ordinary Native UI Shell layout otherwise. Omission keeps the last supplied value. */
+  nativeEdge?: VerticalBarEdge;
 }
 
 export interface VerticalControlAreaHandle extends NativeUIShellHandle {
@@ -86,6 +82,9 @@ export interface ShellItem extends Frame {
   fontSize: number;
   fontWeight: number;
   color: string;
+  backgroundColor?: string;
+  borderColor?: string;
+  borderWidth?: number;
   badge?: ShellBadge;
   icon?: string;
   iconWidth?: number;
@@ -144,6 +143,8 @@ export interface ShellSnapshot {
   viewportWidth: number;
   /** Physical side the native rail is drawn on; the runtime resolves the logical edge through the document direction. */
   verticalBarEdge?: 'left' | 'right';
+  /** Visible foreground modal bounds; omitted for the full page. */
+  verticalBarFrame?: Frame;
   controls: ShellControl[];
 }
 
@@ -158,21 +159,12 @@ export interface WebViewMetrics {
   radius: number;
 }
 
-export interface DeviceLayout {
-  placement: VerticalBarPlacement;
-  /** Fold hinge posture, or `null` when the device reports no hinge. */
-  hingeStatus: HingeStatus | null;
-  webViewMetrics: WebViewMetrics;
-}
-
 export interface NativeUIShellPlugin {
   configure(options?: { verticalBarsOnly?: boolean }): Promise<{ supported: boolean }>;
-  getDeviceLayout(): Promise<DeviceLayout>;
-  startDeviceLayoutMonitoring(): Promise<void>;
-  stopDeviceLayoutMonitoring(): Promise<void>;
+  getWebViewMetrics(): Promise<WebViewMetrics>;
   update(snapshot: ShellSnapshot): Promise<{ revision: number; rejectedSearches?: string[]; rejectedControls?: string[] }>;
   clear(options: { revision: number }): Promise<void>;
   addListener(name: 'activate', listener: (event: ShellActivation) => void): Promise<PluginListenerHandle>;
   addListener(name: 'search', listener: (event: ShellSearchEvent) => void): Promise<PluginListenerHandle>;
-  addListener(name: 'deviceLayoutChange', listener: (event: DeviceLayout) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
 }