@blotch/angular-lynx-native 22.2.2 → 22.2.3

package/README.md

@@ -14,20 +14,25 @@ An ejected project (`ios/` or `android/` with a `.angular-lynx-ejected` marker,
 
 ## The shells
 
-Both are one full-screen `LynxView` running `main.lynx.bundle`; Angular Router does all navigation inside it. Bundles and assets load from inside the app, so RSpeedy's default asset prefix (`/static/...`) works with no configuration. See [`templates/android/README.md`](templates/android/README.md) for the Android shell's details.
+Both are one full-screen `LynxView` running `main.lynx.bundle`; Angular Router does all navigation inside it. Bundles and assets load from inside the app, so RSpeedy's default asset prefix (`/static/...`) works with no configuration. The `LynxView` sits inside the safe area, so CSS `env(safe-area-inset-*)` is 0 in it.
 
-|                  | iOS                                             | Android                                                  |
-| ---------------- | ----------------------------------------------- | -------------------------------------------------------- |
-| Language         | Swift, scene lifecycle                          | Kotlin                                                   |
-| Lynx             | 4.1.0, prebuilt XCFrameworks (below)            | 4.1.0 AARs from Maven Central                            |
-| Toolchain        | Xcode 27, iOS 15+                               | AGP 9.4, Gradle 9.6, JDK 17+, SDK 36, minSdk 24          |
-| Generated config | `Config/App.xcconfig`, `App/Info.plist` markers | `angular-lynx.properties`, `AndroidManifest.xml` markers |
+Both send the same global props, which the runtime's services read: `platform`, `theme` (again whenever the phone switches between light and dark), `appLocale` (the phone's language as a BCP 47 tag), `isNotchScreen`, and the safe-area insets `safeAreaTop`, `safeAreaBottom`, `safeAreaLeft` and `safeAreaRight`. Lynx Explorer sends `theme` and `isNotchScreen` too, but no `appLocale`. See [`templates/android/README.md`](templates/android/README.md) for the Android shell's details.
+
+Both link Lynx's XElement library, which holds `<input>`, `<textarea>`, `<overlay>`, `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the `<scroll-coordinator>` family, `<webview>` and `<video>`. Lynx's core doesn't include these, and a host that doesn't register them renders nothing for those tags (on Android, nothing after them either). XElement's AnimaX and Markdown elements are left out: the runtime doesn't support them.
+
+|                  | iOS                                                  | Android                                                  |
+| ---------------- | ---------------------------------------------------- | -------------------------------------------------------- |
+| Language         | Swift, scene lifecycle                               | Kotlin                                                   |
+| Lynx             | 4.1.0, prebuilt XCFrameworks (below)                 | 4.1.0 AARs from Maven Central                            |
+| XElement         | Linked and registered (`App/XElementRegistry.swift`) | Linked and registered (`XElementBehaviors`)              |
+| Toolchain        | Xcode 27, iOS 15+                                    | AGP 9.4, Gradle 9.6, JDK 17+, SDK 36, minSdk 24          |
+| Generated config | `Config/App.xcconfig`, `App/Info.plist` markers      | `angular-lynx.properties`, `AndroidManifest.xml` markers |
 
 ## Lynx for iOS
 
-Lynx publishes iOS only as source pods, which take minutes to compile and need CocoaPods (and so Ruby). `scripts/build-lynx-ios-frameworks.sh` compiles them once into XCFrameworks (about 24 MB zipped, with debug symbols in a separate zip). The builder downloads the zip pinned in `src/ios/frameworks.ts` (URL and SHA-256) on first use and caches it in `~/.cache/angular-lynx/lynx-ios/<version>`.
+Lynx publishes iOS only as source pods, which take minutes to compile and need CocoaPods (and so Ruby). `scripts/build-lynx-ios-frameworks.sh` compiles them once into XCFrameworks (about 26 MB zipped, with debug symbols in a separate zip): Lynx, PrimJS, XElement and their dependencies. The builder downloads the zip pinned in `src/ios/frameworks.ts` (URL and SHA-256) on first use and caches it in `~/.cache/angular-lynx/lynx-ios/<version>-<build>`.
 
-The zip for Lynx 4.1.0 is the [`lynx-ios-4.1.0` release](https://github.com/Blotch-Smart-Frames/AngularLynx/releases/tag/lynx-ios-4.1.0). For a new Lynx version, bump the versions in the script, run the **Lynx iOS frameworks** workflow with `publish` (or the script locally), and pin the new zip's URL and SHA-256. To test a locally built folder before publishing it:
+The zip for Lynx 4.1.0 is the [`lynx-ios-4.1.0-2` release](https://github.com/Blotch-Smart-Frames/AngularLynx/releases/tag/lynx-ios-4.1.0-2). The build number counts rebuilds of one Lynx version whose frameworks changed (2 added XElement), and is part of the cache folder, so machines with an older zip download the new one. For a new Lynx version, bump the versions in the script and reset `BUILD` to 1; to change the frameworks of the same version, bump `BUILD` (in the script and in `LYNX_IOS`). Then run the **Lynx iOS frameworks** workflow with `publish` (or the script locally), and pin the new zip's URL and SHA-256. To test a locally built folder before publishing it:
 
 ```sh
 npm run build:lynx-ios-frameworks -w packages/native   # needs Xcode, and Ruby >= 2.7 with Bundler for CocoaPods

package/dist/ios/frameworks.d.ts

@@ -9,7 +9,14 @@
  */
 export declare const LYNX_IOS: {
     readonly version: "4.1.0";
-    readonly url: "https://github.com/Blotch-Smart-Frames/AngularLynx/releases/download/lynx-ios-4.1.0/lynx-ios-4.1.0.zip";
+    /**
+     * Counts rebuilds of one Lynx version whose frameworks changed (2 added
+     * XElement); BUILD in the script. It's part of the cache folder, so a
+     * machine that cached an older zip downloads the new one instead of
+     * linking frameworks the shell no longer matches.
+     */
+    readonly build: 2;
+    readonly url: "https://github.com/Blotch-Smart-Frames/AngularLynx/releases/download/lynx-ios-4.1.0-2/lynx-ios-4.1.0-2.zip";
     readonly sha256: string | undefined;
 };
 /**
@@ -17,7 +24,7 @@ export declare const LYNX_IOS: {
  * scripts/generate-ios-project.ts) and the frameworks build both read this
  * list, so it is the only place to change it.
  */
-export declare const LYNX_IOS_FRAMEWORKS: readonly ["Lynx", "LynxBase", "LynxServiceAPI", "LynxService", "PrimJS", "SDWebImage", "SDWebImageWebPCoder", "libwebp"];
+export declare const LYNX_IOS_FRAMEWORKS: readonly ["Lynx", "LynxBase", "LynxServiceAPI", "LynxService", "PrimJS", "SDWebImage", "SDWebImageWebPCoder", "libwebp", "XElement", "ServalSVG", "MJRefresh"];
 /**
  * Overrides the download with a local folder of XCFrameworks, e.g. the
  * `out/LynxFrameworks` folder build-lynx-ios-frameworks.sh writes. For testing

package/dist/ios/frameworks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frameworks.d.ts","sourceRoot":"","sources":["../../src/ios/frameworks.ts"],"names":[],"mappings":"AAcA;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ;;;qBAIf,MAAM,GACN,SAAS;CACL,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,0HAStB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,cAAc,gCAAgC,CAAC;AAS5D,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAChC,SAAS,MAAM,EACf,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,KAC7B,OAAO,CAAC,MAAM,CAmDhB,CAAC;AAaF,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAM5D,CAAC"}
+{"version":3,"file":"frameworks.d.ts","sourceRoot":"","sources":["../../src/ios/frameworks.ts"],"names":[],"mappings":"AAcA;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ;;IAEnB;;;;;OAKG;;;qBAIC,MAAM,GACN,SAAS;CACL,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,gKAYtB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,cAAc,gCAAgC,CAAC;AAS5D,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAChC,SAAS,MAAM,EACf,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,KAC7B,OAAO,CAAC,MAAM,CAmDhB,CAAC;AAaF,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAM5D,CAAC"}

package/dist/ios/frameworks.js

@@ -14,8 +14,15 @@ import { run } from "../process.js";
  */
 export const LYNX_IOS = {
     version: '4.1.0',
-    url: 'https://github.com/Blotch-Smart-Frames/AngularLynx/releases/download/lynx-ios-4.1.0/lynx-ios-4.1.0.zip',
-    sha256: '8f00fbd9eddc885175ea526136197222b5a8bd892c6b4d97e131abf88b9a39f4',
+    /**
+     * Counts rebuilds of one Lynx version whose frameworks changed (2 added
+     * XElement); BUILD in the script. It's part of the cache folder, so a
+     * machine that cached an older zip downloads the new one instead of
+     * linking frameworks the shell no longer matches.
+     */
+    build: 2,
+    url: 'https://github.com/Blotch-Smart-Frames/AngularLynx/releases/download/lynx-ios-4.1.0-2/lynx-ios-4.1.0-2.zip',
+    sha256: '88d0bbea842da734c3513df2a14e641d85cac645d3f432781af0da7c035e4646',
 };
 /**
  * The frameworks in the zip. The template project (APP_PROJECT in
@@ -31,6 +38,9 @@ export const LYNX_IOS_FRAMEWORKS = [
     'SDWebImage',
     'SDWebImageWebPCoder',
     'libwebp',
+    'XElement',
+    'ServalSVG',
+    'MJRefresh',
 ];
 /**
  * Overrides the download with a local folder of XCFrameworks, e.g. the
@@ -46,7 +56,7 @@ export const resolveLynxFrameworks = async (logFile, log) => {
         assertComplete(override, `${FRAMEWORKS_ENV} (${override})`);
         return path.resolve(override);
     }
-    const dir = path.join(cacheRoot(), LYNX_IOS.version);
+    const dir = path.join(cacheRoot(), `${LYNX_IOS.version}-${LYNX_IOS.build}`);
     const frameworks = path.join(dir, 'LynxFrameworks');
     if (existsSync(path.join(dir, '.complete'))) {
         return frameworks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx-native",
-  "version": "22.2.2",
+  "version": "22.2.3",
   "description": "Builds AngularLynx apps into iOS and Android binaries",
   "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
   "bugs": {

package/templates/android/README.md

@@ -26,17 +26,19 @@ Build commands and outputs (no flavors, so the names are fixed):
 ## How the shell loads the app
 
 - **Bundles** come from `assets/` (`ResourceFetchers.kt`, `BundleAssets.kt`). A URL without a scheme (`/static/…`, `static/…`), `asset:///…` and `file:///android_asset/…` all mean "the file at that path in `assets/`", so the bundle works with Rspeedy's default asset prefix (`/`) and doesn't need a platform-specific one. Absolute `http(s)` URLs are fetched with OkHttp.
+- **`fetch()` and `XMLHttpRequest`** go through Lynx's HTTP service (`LynxHttpService`, registered in `ShellApplication.kt`), which uses OkHttp. Plain HTTP is allowed to `localhost` and `127.0.0.1` only (`res/xml/network_security_config.xml`), for a server on the device or one on your machine through `adb reverse`; every other host needs HTTPS, Android's default.
 - **Images** are loaded by Fresco. The media fetcher rewrites bundled image URLs to `asset:///…`, which Fresco reads from the APK.
 - **Lazy routes** need nothing extra: the build plugin keeps each lazy chunk inside `main.lynx.bundle` (see `split-chunks.ts` in the build plugin). Bundles requested by URL at runtime still go through the template resource fetcher.
 
 ## Back button
 
-Back is off by default, so it leaves the app like any root screen. The runtime turns it on while the Router has history by calling `NativeModules.AngularLynxShell.setBackHandlerEnabled(true)` (from the background thread, where `NativeModules` lives). While it's on, a back press sends the global event `angularLynxBack` instead, which the runtime turns into a Router back navigation. The app has to say beforehand because Android decides synchronously, at the start of the gesture, whether an app handles back (predictive back animates differently).
+Back is off by default, so it leaves the app like any root screen. The runtime turns it on while the Router has history by calling `NativeModules.AngularLynxShell.setBackHandlerEnabled(true)`, and off again on the first screen (`LynxBackButton` in `packages/runtime/src/lib/router/lynx-back-button.ts`, which `provideRouter()` starts; the call goes through the background thread, where `NativeModules` lives). While it's on, a back press sends the global event `angularLynxBack` instead, which the runtime turns into `Location.back()`. The app has to say beforehand because Android decides synchronously, at the start of the gesture, whether an app handles back (predictive back animates differently). Layer 6's `native/back-button.yaml` checks both ends.
 
 ## Versions
 
 Pinned in `app/build.gradle.kts`, `build.gradle.kts` and `gradle/wrapper/gradle-wrapper.properties`:
 
 - Lynx 4.1.0 and PrimJS 4.1.1 (Maven Central), Fresco 2.3.0 (the version Lynx's image service is built against), OkHttp 4.12.
+- Lynx's XElement 4.1.0 (`<input>`, `<textarea>`, `<overlay>`, `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the `<scroll-coordinator>` family, `<webview>`, `<video>`), without its AnimaX and Markdown modules, which the runtime doesn't support. `MainActivity` registers the elements with `XElementBehaviors`. XElement depends on appcompat and material 1.0.0, whose vectordrawable libraries share a namespace that AGP 9 rejects, so appcompat 1.7.1 and material 1.12.0 are pinned.
 - AGP 9.4.1 with its built-in Kotlin, Gradle 9.6.1 (AGP 9.4's minimum), JDK 17 or newer.
 - `compileSdk` and `targetSdk` 36, `minSdk` 24. Google Play raises its target API requirement every August; bump `targetSdk` with it.

package/templates/android/app/build.gradle.kts

@@ -137,4 +137,22 @@ dependencies {
     implementation("com.facebook.fresco:webpsupport:$frescoVersion")
     implementation("com.facebook.fresco:animated-base:$frescoVersion")
     implementation("com.squareup.okhttp3:okhttp:4.12.0")
+
+    // XElement: <input>, <textarea>, <overlay>, <svg>, <blur-view>,
+    // <viewpager>, <refresh>, the <scroll-coordinator> family, <webview> and
+    // <video>. They aren't in Lynx's core, and without them those tags render
+    // nothing. MainActivity registers them with XElementBehaviors. The
+    // umbrella artifact depends on one module per element; AnimaX and
+    // Markdown are elements the runtime doesn't support, and AnimaX alone
+    // adds about 5 MB of native code per ABI.
+    implementation("org.lynxsdk.lynx:xelement:$lynxVersion") {
+        exclude(group = "org.lynxsdk.lynx", module = "xelement-animax")
+        exclude(group = "org.lynxsdk.lynx", module = "xelement-markdown")
+    }
+    // XElement's modules depend on appcompat and material 1.0.0, which bring
+    // vectordrawable 1.0.0 and vectordrawable-animated 1.0.0. Those two share
+    // the namespace androidx.vectordrawable, and AGP 9's manifest merger
+    // fails the build on that; newer versions give them distinct namespaces.
+    implementation("androidx.appcompat:appcompat:1.7.1")
+    implementation("com.google.android.material:material:1.12.0")
 }

package/templates/android/app/src/main/AndroidManifest.xml

@@ -10,6 +10,7 @@
         android:allowBackup="true"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:supportsRtl="true"
         android:theme="@style/Theme.AngularLynxShell">
         <!--

package/templates/android/app/src/main/java/dev/angularlynx/shell/MainActivity.kt

@@ -1,11 +1,14 @@
 package dev.angularlynx.shell
 
+import android.content.res.Configuration
 import android.os.Bundle
 import android.util.Log
 import android.widget.FrameLayout
 import androidx.activity.ComponentActivity
 import androidx.activity.OnBackPressedCallback
 import androidx.activity.enableEdgeToEdge
+import androidx.core.graphics.Insets
+import androidx.core.os.ConfigurationCompat
 import androidx.core.view.ViewCompat
 import androidx.core.view.WindowInsetsCompat
 import com.lynx.react.bridge.JavaOnlyArray
@@ -14,6 +17,7 @@ import com.lynx.tasm.LynxError
 import com.lynx.tasm.LynxView
 import com.lynx.tasm.LynxViewBuilder
 import com.lynx.tasm.LynxViewClient
+import com.lynx.xelement.XElementBehaviors
 
 /**
  * The whole app: one full-screen LynxView running the Angular app. Angular
@@ -22,6 +26,11 @@ import com.lynx.tasm.LynxViewClient
 class MainActivity : ComponentActivity(), ShellModule.Host {
     private lateinit var lynxView: LynxView
 
+    // The system bar and cutout insets, and whether the screen has a cutout,
+    // as the window last reported them. Sent in the global props.
+    private var safeArea = Insets.NONE
+    private var hasCutout = false
+
     // Disabled until the Angular app enables it (see ShellModule), so by
     // default back leaves the app like any other root screen.
     private val backHandler = object : OnBackPressedCallback(false) {
@@ -43,6 +52,10 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
             setEnableGenericResourceFetcher(LynxBooleanOption.TRUE)
             setGenericResourceFetcher(AssetGenericResourceFetcher(this@MainActivity))
             registerModule(ShellModule.NAME, ShellModule::class.java, this@MainActivity)
+            // Lynx's core has no <input>, <overlay>, <svg>, <blur-view> etc.;
+            // these come from XElement (see app/build.gradle.kts). Lynx
+            // Explorer registers them the same way.
+            addBehaviors(XElementBehaviors().create())
         }.build(this)
         lynxView.addLynxViewClient(object : LynxViewClient() {
             override fun onReceivedError(error: LynxError?) {
@@ -51,7 +64,9 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
         })
 
         // Keep the app inside the safe area (status bar, navigation bar and
-        // camera cutout) until the runtime exposes the insets to CSS.
+        // camera cutout). Lynx has no way to give CSS env(safe-area-inset-*)
+        // values on Android, so they're 0, which is right for a page that's
+        // already inside the safe area. The iOS shell matches.
         val container = FrameLayout(this)
         container.addView(lynxView, FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT)
         ViewCompat.setOnApplyWindowInsetsListener(container) { view, insets ->
@@ -61,11 +76,24 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
                     WindowInsetsCompat.Type.ime(),
             )
             view.setPadding(safe.left, safe.top, safe.right, safe.bottom)
+            // The keyboard isn't part of the safe area, as on iOS.
+            val bars = insets.getInsets(
+                WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout(),
+            )
+            val cutout = insets.displayCutout != null
+            if (bars != safeArea || cutout != hasCutout) {
+                safeArea = bars
+                hasCutout = cutout
+                lynxView.updateGlobalProps(globalProps(resources.configuration))
+            }
             WindowInsetsCompat.CONSUMED
         }
         setContentView(container)
 
         onBackPressedDispatcher.addCallback(this, backHandler)
+        // Sent before the bundle loads, so the app starts with the theme and
+        // the language. The insets follow once the window reports them.
+        lynxView.updateGlobalProps(globalProps(resources.configuration))
         lynxView.renderTemplateUrl(BundleAssets.MAIN_BUNDLE, "")
     }
 
@@ -73,6 +101,38 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
         backHandler.isEnabled = enabled
     }
 
+    // The manifest's configChanges keeps the activity, and the running app,
+    // through a dark mode switch, so the new theme is sent from here. A
+    // language change still restarts the activity, which sends the new
+    // appLocale: Angular reads LOCALE_ID only once.
+    override fun onConfigurationChanged(newConfig: Configuration) {
+        super.onConfigurationChanged(newConfig)
+        lynxView.updateGlobalProps(globalProps(newConfig))
+    }
+
+    /**
+     * The global props the runtime reads: `theme` (LynxTheme), `isNotchScreen`
+     * (LynxSafeArea) and `appLocale` (LynxLocale), plus the safe-area insets
+     * in dp. The iOS shell sends the same keys, and Lynx Explorer sends theme
+     * and isNotchScreen too.
+     */
+    private fun globalProps(config: Configuration): Map<String, Any> {
+        val density = resources.displayMetrics.density
+        val night = config.uiMode and Configuration.UI_MODE_NIGHT_MASK == Configuration.UI_MODE_NIGHT_YES
+        val props = mutableMapOf<String, Any>(
+            "platform" to "android",
+            "theme" to if (night) "Dark" else "Light",
+            "isNotchScreen" to hasCutout,
+            "safeAreaTop" to safeArea.top / density,
+            "safeAreaBottom" to safeArea.bottom / density,
+            "safeAreaLeft" to safeArea.left / density,
+            "safeAreaRight" to safeArea.right / density,
+        )
+        // The user's language as a BCP 47 tag, such as "fr-FR".
+        ConfigurationCompat.getLocales(config)[0]?.let { props["appLocale"] = it.toLanguageTag() }
+        return props
+    }
+
     // Lynx pauses timers and animations in the background and fires the
     // page's visibility events from these.
     override fun onResume() {

package/templates/android/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Allows plain HTTP to this device's own loopback address, and nowhere else.
+  Loopback traffic never leaves the device, so there's nothing to intercept:
+  it reaches a server on the device itself, or one on the development machine
+  through `adb reverse`. Every other host keeps Android's default, which
+  blocks cleartext. Without this, fetch() to http://localhost failed with
+  "CLEARTEXT communication not permitted", which Lynx reports as status 499.
+-->
+<network-security-config>
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">localhost</domain>
+        <domain includeSubdomains="false">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>

package/templates/ios/App/AppDelegate.swift

@@ -13,6 +13,7 @@ final class AppDelegate: UIResponder, UIApplicationDelegate {
     _ application: UIApplication,
     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
   ) -> Bool {
+    XElementRegistry.register()
     let config = LynxConfig(provider: BundleResourceFetcher.shared)
     LynxEnv.sharedInstance().prepareConfig(config)
     // LynxService's image service decodes through SDWebImage, which only

package/templates/ios/App/LynxViewController.swift

@@ -30,6 +30,25 @@ final class LynxViewController: UIViewController {
     layoutLynxView()
     lynxView.updateGlobalProps(with: globalProps())
     lynxView.loadTemplate(fromURL: "main.lynx.bundle", initData: nil)
+
+    // Send the new theme when the phone switches between light and dark
+    // while the app is open. Before iOS 17, traitCollectionDidChange does.
+    if #available(iOS 17.0, *) {
+      registerForTraitChanges([UITraitUserInterfaceStyle.self]) {
+        (controller: LynxViewController, _: UITraitCollection) in
+        controller.lynxView?.updateGlobalProps(with: controller.globalProps())
+      }
+    }
+  }
+
+  @available(iOS, deprecated: 17.0, message: "registerForTraitChanges in viewDidLoad replaces it")
+  override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
+    super.traitCollectionDidChange(previousTraitCollection)
+    if #unavailable(iOS 17.0),
+      traitCollection.hasDifferentColorAppearance(comparedTo: previousTraitCollection)
+    {
+      lynxView?.updateGlobalProps(with: globalProps())
+    }
   }
 
   override func viewDidLayoutSubviews() {
@@ -39,7 +58,13 @@ final class LynxViewController: UIViewController {
 
   /// Keeps the LynxView inside the safe area, so a freshly generated app
   /// doesn't draw under the notch or the home indicator. The insets are also
-  /// passed as global props for apps that want to draw edge to edge later.
+  /// passed as global props for apps that want to know them.
+  ///
+  /// CSS env(safe-area-inset-*) is 0 on every side, which is right for a page
+  /// that's already inside the safe area, and matches Android, where Lynx
+  /// never sets it. Lynx reads it from the key window when a LynxView is
+  /// created, and viewDidLoad runs before SceneDelegate makes the window key.
+  /// Creating the LynxView later would make env() add the insets a second time.
   private func layoutLynxView() {
     guard let lynxView else { return }
     let frame = view.bounds.inset(by: view.safeAreaInsets)
@@ -54,15 +79,30 @@ final class LynxViewController: UIViewController {
     lynxView.triggerLayout()
   }
 
+  /// The global props the runtime reads: `theme` (LynxTheme), `isNotchScreen`
+  /// (LynxSafeArea) and `appLocale` (LynxLocale), plus the safe-area insets.
+  /// The Android shell sends the same keys, and Lynx Explorer sends theme and
+  /// isNotchScreen too.
   private func globalProps() -> LynxTemplateData {
     let insets = view.safeAreaInsets
-    return LynxTemplateData(dictionary: [
+    var props: [String: Any] = [
       "platform": "ios",
       "safeAreaTop": insets.top,
       "safeAreaBottom": insets.bottom,
       "safeAreaLeft": insets.left,
       "safeAreaRight": insets.right,
+      // Lynx Explorer's test: anything beyond a plain 20pt status bar, as on
+      // iPhones with a notch or Dynamic Island.
+      "isNotchScreen": insets.top > 20 || insets.bottom > 0 || insets.left > 0
+        || insets.right > 0,
       "theme": traitCollection.userInterfaceStyle == .dark ? "Dark" : "Light",
-    ])
+    ]
+    // The user's first language as a BCP 47 tag, such as "fr-FR". iOS
+    // restarts the app when the language changes, so there's no update to send.
+    if let language = Locale.preferredLanguages.first {
+      props["appLocale"] = language
+    }
+    // Without useBoolLiterals, Lynx turns a Bool into 1 or 0.
+    return LynxTemplateData(dictionary: props, useBoolLiterals: true)
   }
 }

package/templates/ios/App/XElementRegistry.swift

@@ -0,0 +1,51 @@
+import Lynx
+import XElement
+
+/// Registers XElement's elements: `<input>`, `<textarea>`, `<overlay>`,
+/// `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the
+/// `<scroll-coordinator>` family, `<webview>` and `<video>`. Lynx's core
+/// doesn't include them, and a tag nothing is registered for renders nothing.
+///
+/// Lynx Explorer gets these registrations from XElement's `Behavior` subspec,
+/// but that subspec also links Markdown, an element the runtime doesn't
+/// support, so the frameworks build leaves it out
+/// (scripts/build-lynx-ios-frameworks.sh) and the shell registers the same
+/// classes under the same names here, before the first LynxConfig or LynxView
+/// exists.
+enum XElementRegistry {
+  static func register() {
+    let elements: [(String, AnyClass)] = [
+      ("input", LynxUIInput.self),
+      ("textarea", LynxUITextArea.self),
+      ("overlay", LynxUIOverlay.self),
+      ("svg", LynxUISVG.self),
+      ("blur-view", LynxUIBlurView.self),
+      ("viewpager", LynxUIViewPager.self),
+      ("viewpager-item", LynxUIViewPagerItem.self),
+      ("refresh", LynxUIRefresh.self),
+      ("refresh-header", LynxUIRefreshHeader.self),
+      ("scroll-coordinator", LynxUIScrollCoordinator.self),
+      ("scroll-coordinator-header", LynxUIScrollCoordinatorHeader.self),
+      ("scroll-coordinator-slot", LynxUIScrollCoordinatorSlot.self),
+      ("scroll-coordinator-slot-drag", LynxUIScrollCoordinatorSlotDrag.self),
+      ("scroll-coordinator-toolbar", LynxUIScrollCoordinatorToolbar.self),
+      ("webview", LynxUIWebView.self),
+      ("video", LynxUIVideo.self),
+    ]
+    for (name, ui) in elements {
+      LynxComponentRegistry.registerUI(ui, withName: name)
+    }
+    // The elements whose size comes from their content (a text field's
+    // text, an overlay's screen, a refresh's header) also measure themselves
+    // in layout, through a shadow node.
+    let shadowNodes: [(String, AnyClass)] = [
+      ("input", LynxUIInputShadowNode.self),
+      ("textarea", LynxUITextAreaShadowNode.self),
+      ("overlay", LynxUIOverlayShadowNode.self),
+      ("refresh", LynxUIRefreshShadowNode.self),
+    ]
+    for (name, node) in shadowNodes {
+      LynxComponentRegistry.registerShadowNode(node, withName: name)
+    }
+  }
+}

package/templates/ios/App.xcodeproj/project.pbxproj

@@ -11,10 +11,14 @@
 		0E3870431039EBF246629EDC /* LynxBase.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 03FA19016485E5D5DFE1595F /* LynxBase.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		24F6F7C0ED16226B5F4CEC64 /* libwebp.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 22AE3F7CF67B188787336BFA /* libwebp.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		3222B5E4F829B616E7F195E6 /* LynxService.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 59F6406B1F8C89E22DDE0B86 /* LynxService.xcframework */; };
+		333153D6D20AE3F4F4F0F232 /* XElement.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = CA3E9DB48B8E7102AFB3F9D3 /* XElement.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		3C05B6061112B7F48C5D3539 /* LynxServiceAPI.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 1DB5C3D66078CC41360F16AF /* LynxServiceAPI.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
+		481B830F1B162EF6665B22C7 /* ServalSVG.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 1555CF4C65B98EB4D3757A5B /* ServalSVG.xcframework */; };
 		4C8131B26C3C8894FC77643D /* LynxService.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 59F6406B1F8C89E22DDE0B86 /* LynxService.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		4CFD715805AA40F2DF9A81AF /* LynxServiceAPI.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 1DB5C3D66078CC41360F16AF /* LynxServiceAPI.xcframework */; };
 		52C2300A66557A4A04A633FD /* SDWebImage.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 0CDAE1A45DE3FB3C238352B1 /* SDWebImage.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
+		55C00449AF3D55EB900A1B9A /* MJRefresh.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = A479BE709FC284B487B4B3EE /* MJRefresh.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
+		5D986CA1D5DAB3B9F6D299F5 /* ServalSVG.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 1555CF4C65B98EB4D3757A5B /* ServalSVG.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		5F80D1C6C1436E9CB4F93155 /* PrimJS.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 6B827DF13C44D4B05B7DAE8C /* PrimJS.xcframework */; };
 		7F265E09F76C87AD1CB5DECB /* LynxBundle in Resources */ = {isa = PBXBuildFile; fileRef = D84EC48E5D673EC745AF0F7D /* LynxBundle */; };
 		8BCF0DFFF316AA01FC859C29 /* Lynx.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 06FE05FCCC1F0C34FAAAAE10 /* Lynx.xcframework */; };
@@ -23,7 +27,9 @@
 		C153F098EA734F20BDC0E7F1 /* libwebp.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 22AE3F7CF67B188787336BFA /* libwebp.xcframework */; };
 		C92615D6F55A8C1D8D6489E7 /* PrimJS.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 6B827DF13C44D4B05B7DAE8C /* PrimJS.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		CF3E40650CC18BF7B0B1AB22 /* SDWebImage.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 0CDAE1A45DE3FB3C238352B1 /* SDWebImage.xcframework */; };
+		E0F04E5FF5F7548B94615806 /* MJRefresh.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = A479BE709FC284B487B4B3EE /* MJRefresh.xcframework */; };
 		ED8182CEA14283E4D2AB28E9 /* SDWebImageWebPCoder.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = 938799E9025522AF0DB08F41 /* SDWebImageWebPCoder.xcframework */; };
+		F9F12589EAE493E887916AB0 /* XElement.xcframework in Frameworks */ = {isa = PBXBuildFile; fileRef = CA3E9DB48B8E7102AFB3F9D3 /* XElement.xcframework */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXCopyFilesBuildPhase section */
@@ -41,6 +47,9 @@
 				52C2300A66557A4A04A633FD /* SDWebImage.xcframework in Embed Frameworks */,
 				96D79D9E007FEA2813F7072F /* SDWebImageWebPCoder.xcframework in Embed Frameworks */,
 				24F6F7C0ED16226B5F4CEC64 /* libwebp.xcframework in Embed Frameworks */,
+				333153D6D20AE3F4F4F0F232 /* XElement.xcframework in Embed Frameworks */,
+				5D986CA1D5DAB3B9F6D299F5 /* ServalSVG.xcframework in Embed Frameworks */,
+				55C00449AF3D55EB900A1B9A /* MJRefresh.xcframework in Embed Frameworks */,
 			);
 			name = "Embed Frameworks";
 			runOnlyForDeploymentPostprocessing = 0;
@@ -51,6 +60,7 @@
 		03FA19016485E5D5DFE1595F /* LynxBase.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = LynxBase.xcframework; sourceTree = "<group>"; };
 		06FE05FCCC1F0C34FAAAAE10 /* Lynx.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = Lynx.xcframework; sourceTree = "<group>"; };
 		0CDAE1A45DE3FB3C238352B1 /* SDWebImage.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = SDWebImage.xcframework; sourceTree = "<group>"; };
+		1555CF4C65B98EB4D3757A5B /* ServalSVG.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = ServalSVG.xcframework; sourceTree = "<group>"; };
 		15B4BAB9D017652EC88BA5A1 /* App.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = App.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		1DB5C3D66078CC41360F16AF /* LynxServiceAPI.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = LynxServiceAPI.xcframework; sourceTree = "<group>"; };
 		22AE3F7CF67B188787336BFA /* libwebp.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = libwebp.xcframework; sourceTree = "<group>"; };
@@ -58,6 +68,8 @@
 		59F6406B1F8C89E22DDE0B86 /* LynxService.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = LynxService.xcframework; sourceTree = "<group>"; };
 		6B827DF13C44D4B05B7DAE8C /* PrimJS.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = PrimJS.xcframework; sourceTree = "<group>"; };
 		938799E9025522AF0DB08F41 /* SDWebImageWebPCoder.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = SDWebImageWebPCoder.xcframework; sourceTree = "<group>"; };
+		A479BE709FC284B487B4B3EE /* MJRefresh.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = MJRefresh.xcframework; sourceTree = "<group>"; };
+		CA3E9DB48B8E7102AFB3F9D3 /* XElement.xcframework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; path = XElement.xcframework; sourceTree = "<group>"; };
 		D84EC48E5D673EC745AF0F7D /* LynxBundle */ = {isa = PBXFileReference; lastKnownFileType = folder; path = LynxBundle; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
@@ -95,6 +107,9 @@
 				CF3E40650CC18BF7B0B1AB22 /* SDWebImage.xcframework in Frameworks */,
 				ED8182CEA14283E4D2AB28E9 /* SDWebImageWebPCoder.xcframework in Frameworks */,
 				C153F098EA734F20BDC0E7F1 /* libwebp.xcframework in Frameworks */,
+				F9F12589EAE493E887916AB0 /* XElement.xcframework in Frameworks */,
+				481B830F1B162EF6665B22C7 /* ServalSVG.xcframework in Frameworks */,
+				E0F04E5FF5F7548B94615806 /* MJRefresh.xcframework in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -131,6 +146,9 @@
 				0CDAE1A45DE3FB3C238352B1 /* SDWebImage.xcframework */,
 				938799E9025522AF0DB08F41 /* SDWebImageWebPCoder.xcframework */,
 				22AE3F7CF67B188787336BFA /* libwebp.xcframework */,
+				CA3E9DB48B8E7102AFB3F9D3 /* XElement.xcframework */,
+				1555CF4C65B98EB4D3757A5B /* ServalSVG.xcframework */,
+				A479BE709FC284B487B4B3EE /* MJRefresh.xcframework */,
 			);
 			path = Frameworks;
 			sourceTree = "<group>";