@erkamyaman/capacitor-foldable 8.2.0 → 8.3.1

package/ErkamyamanCapacitorFoldable.podspec

@@ -11,6 +11,7 @@ Pod::Spec.new do |s|
   s.author = package['author']
   s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
   s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.resource_bundles = { 'ErkamyamanCapacitorFoldablePrivacy' => ['ios/Sources/FoldablePlugin/Resources/PrivacyInfo.xcprivacy'] }
   s.ios.deployment_target = '14.0'
   s.dependency 'Capacitor'
   s.swift_version = '5.1'

package/Package.swift

@@ -19,7 +19,8 @@ let package = Package(
                 .product(name: "Capacitor", package: "capacitor-swift-pm"),
                 .product(name: "Cordova", package: "capacitor-swift-pm")
             ],
-            path: "ios/Sources/FoldablePlugin"),
+            path: "ios/Sources/FoldablePlugin",
+            resources: [.copy("Resources/PrivacyInfo.xcprivacy")]),
         .testTarget(
             name: "FoldablePluginTests",
             dependencies: ["FoldablePlugin"],

package/README.md

@@ -37,7 +37,7 @@ const { state, hingeOrientation } = await Foldable.getFoldState();
 
 | Platform | Status | Minimum |
 | -------- | ------ | ------- |
-| Android  | Supported | API 24, `compileSdk` 34 |
+| Android  | Supported | API 24, `compileSdk` 36 |
 | iOS      | Size classes everywhere; fold, hinge and bar placement on iPhone Duo with Capacitor 8.5+, Xcode 27.1+ and iOS 27.1+ | iOS 15 |
 | Web      | Stub, returns `flat` | |
 
@@ -53,6 +53,8 @@ Web views already resize with the window, so a responsive layout that pads with
 - **Where iPhone Duo puts native bars**, so your HTML tab bar can follow. For Ionic's `ion-tabs` there's a ready-made stylesheet, plus a fix for the tab bar disappearing when you fold.
 - **The outer display on Android foldables**: rear display and dual screen.
 
+Google's [adaptive app quality guidelines](https://developer.android.com/develop/adaptive-apps/quality-guidelines/adaptive-app-quality) make posture support a Tier 1 check and size-class-driven layouts a Tier 2 one, and Apple's [iPhone Duo guidance](https://developer.apple.com/design/human-interface-guidelines/designing-for-iphone-duo) asks for layouts that adapt to the fold rather than to a device. This plugin reports what both are about.
+
 ## Installation
 
 ```bash
@@ -123,6 +125,26 @@ Using Ionic's `ion-tabs`? `import '@erkamyaman/capacitor-foldable/ionic-tabs.css
 - **[examples](examples)** in this repo is a catalogue of one-file demos, one per API, laid out as two pages around the crease on iPhone Duo.
 - **[example-app](example-app)** is the plain single-screen app that shows every value the plugin reports at once.
 
+## Store review
+
+The plugin is built to give store review nothing to object to.
+
+**iOS.** Public APIs only, UIKit and Capacitor, with no dynamic lookup or private symbols. It touches none of Apple's [required reason APIs](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api), collects nothing and tracks nobody, and it ships a `PrivacyInfo.xcprivacy` saying exactly that, which Xcode folds into your app's privacy report. Nothing it uses needs a purpose string in `Info.plist`. The iOS 27.1 code is behind a compile-time SDK check, so any Xcode that Capacitor 8 supports builds fine.
+
+**Android.** The plugin adds no permissions and no `uses-feature` to your app, so it changes nothing about which devices can install it. Its own manifest is empty; Jetpack WindowManager merges two optional `<uses-library>` entries, which are how it binds to the OEM window extensions and filter nothing. The hinge angle comes from `TYPE_HINGE_ANGLE`, which needs no permission, and rear display and dual screen go through `WindowAreaController`, also permission free. `minSdk` is 24, the same as Capacitor's own default, and `targetSdk` follows your project.
+
+**Data safety and privacy labels.** Everything stays on the device: the plugin has no network code and stores nothing. There is no entry for it to add to Play's Data safety form or to your App Store privacy label.
+
+## Skill for coding agents
+
+The repo ships an agent skill, so Claude Code and other agents know how to use the plugin instead of guessing at the API:
+
+```bash
+npx skills add erkamyaman/capacitor-foldable@capacitor-foldable
+```
+
+It is one skill with the platform detail split out: laying out around the crease in CSS, the full API, Ionic specifics, iPhone Duo, Android foldables, and how to test on both. It is beta, so tell me if any of it steers you wrong. It also ships inside the npm package under [`skills/`](skills/capacitor-foldable), so an agent working in a project that depends on the plugin can find it in `node_modules`.
+
 ## Guides
 
 - [Examples](docs/examples.md)

package/android/src/main/kotlin/io/github/erkamyaman/foldable/DisplayModes.kt

@@ -3,6 +3,7 @@ package io.github.erkamyaman.foldable
 import android.app.Activity
 import android.content.Context
 import android.view.View
+import android.webkit.WebView
 import androidx.core.content.ContextCompat
 import androidx.window.area.WindowAreaCapability
 import androidx.window.area.WindowAreaController
@@ -31,6 +32,7 @@ class DisplayModes(private val activity: Activity) {
     private var rearDisplayArea: WindowAreaInfo? = null
     private var rearDisplaySession: WindowAreaSession? = null
     private var dualScreenSession: WindowAreaSessionPresenter? = null
+    private var dualScreenContent: WebView? = null
 
     fun statuses(): Flow<DisplayModeStatuses> =
         controller.windowAreaInfos
@@ -72,7 +74,7 @@ class DisplayModes(private val activity: Activity) {
 
     fun startDualScreen(createContent: (Context) -> View, onStarted: () -> Unit, onEnded: (Throwable?) -> Unit) {
         dualScreenSession?.let { session ->
-            session.setContentView(createContent(session.context))
+            replaceContent(session, createContent)
             onStarted()
             return
         }
@@ -86,11 +88,12 @@ class DisplayModes(private val activity: Activity) {
             object : WindowAreaPresentationSessionCallback {
                 override fun onSessionStarted(session: WindowAreaSessionPresenter) {
                     dualScreenSession = session
-                    session.setContentView(createContent(session.context))
+                    replaceContent(session, createContent)
                     onStarted()
                 }
 
                 override fun onSessionEnded(t: Throwable?) {
+                    destroyContent()
                     dualScreenSession = null
                     onEnded(t)
                 }
@@ -101,10 +104,27 @@ class DisplayModes(private val activity: Activity) {
     }
 
     fun stopDualScreen() {
+        destroyContent()
         dualScreenSession?.close()
         dualScreenSession = null
     }
 
+    /** A web view left alive keeps its timers and connections running. */
+    private fun replaceContent(session: WindowAreaSessionPresenter, createContent: (Context) -> View) {
+        destroyContent()
+        val content = createContent(session.context)
+        dualScreenContent = content as? WebView
+        session.setContentView(content)
+    }
+
+    private fun destroyContent() {
+        dualScreenContent?.apply {
+            loadUrl("about:blank")
+            destroy()
+        }
+        dualScreenContent = null
+    }
+
     private fun statusOf(area: WindowAreaInfo?, operation: WindowAreaCapability.Operation): String =
         when (area?.getCapability(operation)?.status) {
             WindowAreaCapability.Status.WINDOW_AREA_STATUS_ACTIVE -> "active"

package/android/src/main/kotlin/io/github/erkamyaman/foldable/FoldablePlugin.kt

@@ -216,13 +216,15 @@ class FoldablePlugin : Plugin() {
     @PluginMethod
     fun startDualScreen(call: PluginCall) {
         val url = call.getString("url") ?: return call.reject("url is required.")
+        val target = resolveUrl(url)
+            ?: return call.reject("url must be a page in this app, or a data: URL you built yourself.")
         val displayModes = this.displayModes ?: return call.unavailable("Dual-screen mode needs an activity.")
 
         scope.launch {
             when (lastDisplayModes?.dualScreen) {
                 "available", "active" -> {
                     val settle = Settle(call, "Dual-screen mode")
-                    displayModes.startDualScreen({ context -> dualScreenWebView(context, url) }, settle::started, settle::ended)
+                    displayModes.startDualScreen({ context -> dualScreenWebView(context, target) }, settle::started, settle::ended)
                 }
                 else -> call.unavailable("Dual-screen mode is not available on this device right now.")
             }
@@ -294,12 +296,32 @@ class FoldablePlugin : Plugin() {
         webViewClient = object : WebViewClient() {
             override fun shouldInterceptRequest(view: WebView, request: WebResourceRequest): WebResourceResponse? =
                 bridge.localServer.shouldInterceptRequest(request)
+
+            override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean =
+                !isAppUrl(request.url.toString())
         }
-        loadUrl(resolveUrl(url))
+        loadUrl(url)
+    }
+
+    /**
+     * The page on the other display shares the app's web view profile, so it is
+     * kept to the app's own origin: anything else is refused rather than loaded.
+     */
+    private fun resolveUrl(url: String): String? {
+        if (url.startsWith("//")) return null
+
+        val scheme = Uri.parse(url).scheme
+        if (scheme == null) return URL(URL(bridge.appUrl), url).toString().takeIf(::isAppUrl)
+        if (!scheme.equals("http", true) && !scheme.equals("https", true) && scheme != "data") return null
+
+        return url.takeIf { scheme == "data" || isAppUrl(it) }
     }
 
-    private fun resolveUrl(url: String): String =
-        if (Uri.parse(url).scheme != null) url else URL(URL(bridge.appUrl), url).toString()
+    private fun isAppUrl(url: String): Boolean {
+        val app = Uri.parse(bridge.appUrl)
+        val target = Uri.parse(url)
+        return target.scheme == app.scheme && target.host == app.host && target.port == app.port
+    }
 
     private inner class Settle(private val call: PluginCall, private val mode: String) {
         private var settled = false

package/ionic-tabs-ios26.css

@@ -52,3 +52,12 @@ html.ios:not(.vertical-bars-leading):not(.vertical-bars-trailing) ion-tab-button
     background: rgba(255, 255, 255, 0.1);
   }
 }
+
+@media (prefers-reduced-transparency: reduce), (prefers-contrast: more), (forced-colors: active) {
+  html.ios ion-tab-bar {
+    background: Canvas;
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+    border: 1px solid CanvasText;
+  }
+}

package/ionic-tabs.css

@@ -4,7 +4,7 @@
   bottom: var(--vertical-tab-bar-bottom, 24px);
   z-index: 10;
   flex-direction: column;
-  width: 45px;
+  width: 52px;
   height: auto;
   padding: 3px 2px;
   border: none;
@@ -13,6 +13,7 @@
   background: rgba(255, 255, 255, 0.78);
   -webkit-backdrop-filter: blur(12px) saturate(180%);
   backdrop-filter: blur(12px) saturate(180%);
+  --color-selected: #0071e3;
   box-shadow:
     inset 0 0 0 0.5px rgba(0, 0, 0, 0.2),
     inset 0 0 8px rgba(0, 0, 0, 0.04),
@@ -37,14 +38,27 @@
   --padding-end: 0;
   flex: 0 0 auto;
   width: 100%;
+  min-width: 44px;
   max-width: none;
   height: 54px;
+  min-height: 48px;
   border-radius: 22px;
 }
 
+/* Hidden to the eye, still there for VoiceOver and TalkBack: `display: none`
+   would take the tab's name out of the accessibility tree. */
 .vertical-bars-leading ion-tab-button ion-label,
 .vertical-bars-trailing ion-tab-button ion-label {
-  display: none;
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
 }
 
 .vertical-bars-leading ion-tab-button.tab-selected,
@@ -85,3 +99,15 @@ ion-tab-bar[hidden] {
     background: rgba(255, 255, 255, 0.1);
   }
 }
+
+/* Reduced transparency, higher contrast, forced colours: drop the blur and
+   give the pill an opaque background so the icons stay legible. */
+@media (prefers-reduced-transparency: reduce), (prefers-contrast: more), (forced-colors: active) {
+  .vertical-bars-leading ion-tab-bar,
+  .vertical-bars-trailing ion-tab-bar {
+    background: Canvas;
+    -webkit-backdrop-filter: none;
+    backdrop-filter: none;
+    border: 1px solid CanvasText;
+  }
+}

package/ios/Sources/FoldablePlugin/Resources/PrivacyInfo.xcprivacy

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSPrivacyTracking</key>
+	<false/>
+	<key>NSPrivacyTrackingDomains</key>
+	<array/>
+	<key>NSPrivacyCollectedDataTypes</key>
+	<array/>
+	<key>NSPrivacyAccessedAPITypes</key>
+	<array/>
+</dict>
+</plist>

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "@erkamyaman/capacitor-foldable",
-  "version": "8.2.0",
+  "version": "8.3.1",
   "description": "Fold-state and dual-display APIs for foldable devices in Capacitor apps",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
   "unpkg": "dist/plugin.js",
   "files": [
+    "android/build.gradle",
+    "android/src/main/",
+    "dist/",
     "ErkamyamanCapacitorFoldable.podspec",
     "ionic-tabs-ios26.css",
     "ionic-tabs.css",
+    "ios/Sources",
+    "ios/Tests",
     "LICENSE",
     "Package.swift",
-    "android/build.gradle",
-    "android/src/main/",
-    "dist/",
-    "ios/Sources",
-    "ios/Tests"
+    "skills/"
   ],
   "author": "Erkam Yaman <erkamyaman35@gmail.com>",
   "license": "MIT",

package/skills/capacitor-foldable/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: capacitor-foldable
+description: Build Capacitor apps that adapt to foldable devices, iPhone Duo and Android foldables, with @erkamyaman/capacitor-foldable. Trigger when laying out around the crease or fold, reading the hinge angle or posture, using window size classes, polyfilling the Device Posture and Viewport Segments APIs, telling the outer display from the inner one, using rear display or dual screen on an Android foldable, moving an Ionic tab bar where iPhone Duo puts native bars, or testing on the iPhone Duo simulator or a foldable emulator.
+license: MIT
+metadata:
+  author: erkamyaman
+  version: '0.1'
+  status: beta
+  checked: 2026-09, against Xcode 27.1, Capacitor 8.5, Play target API 36
+---
+
+# Capacitor Foldable
+
+Guidance for [`@erkamyaman/capacitor-foldable`](https://github.com/erkamyaman/capacitor-foldable), which reports the fold to a Capacitor web view: where the crease is, the hinge angle, the posture, and which display the app is on.
+
+This skill is new. Everything in it was checked against the plugin source and measured on the iPhone Duo simulator, but it has not been through much real use yet, so [report anything that misleads you](https://github.com/erkamyaman/capacitor-foldable/issues).
+
+## Install
+
+```bash
+npm install @erkamyaman/capacitor-foldable
+npx cap sync
+```
+
+Capacitor 8 uses the current major. **If you are on Capacitor 7 and building with Xcode 27, upgrade to 8.5 or later before anything else**: those apps crash at launch, because iOS 27 needs the scene lifecycle that only 8.5 adopted, and a crash on launch is an automatic App Review rejection. Capacitor 7 apps can install `@erkamyaman/capacitor-foldable@7` and build with Xcode 26, which reports the fold on Android and size classes everywhere but has no iPhone Duo support. That route closes when Apple requires the iOS 27 SDK in April 2027. The 7.x line also predates the `--fold-*` variables (8.1.0) and the Ionic tab stylesheets, so the CSS below needs Capacitor 8.
+
+## Start here: CSS before JavaScript
+
+Install the polyfill once at startup, then lay out with CSS. Most foldable work needs no JavaScript at all.
+
+```typescript
+import { Foldable, installFoldablePolyfill } from '@erkamyaman/capacitor-foldable';
+
+await installFoldablePolyfill();
+```
+
+Whenever the device reports a fold, that sets `--fold-left`, `--fold-top`, `--fold-width`, `--fold-height` and `--fold-margin-*` on `<html>`, and adds `fold-vertical` or `fold-horizontal`. It also sets the `vertical-bars-*` classes the Ionic stylesheet needs, and fills in the standard Viewport Segments and Device Posture APIs, which Safari and Android's WebView do not provide.
+
+Prefer the `--fold-*` variables over the polyfilled segment variables for layout: the segments only split when the fold actually separates the window, which on iPhone Duo means half open, while the fold variables are there when it is open flat too.
+
+```css
+.fold-vertical .reader { position: fixed; inset: 0; }
+
+.fold-vertical .reader .page {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  padding: 14px;
+  box-sizing: border-box;
+}
+
+.fold-vertical .reader .page:first-child { left: 0; width: var(--fold-left); }
+.fold-vertical .reader .page:last-child { left: calc(var(--fold-left) + var(--fold-width)); right: 0; }
+```
+
+On a phone with no fold there are no `--fold-*` variables and no `fold-*` class, so write the flat layout first and let these rules refine it. The install is also a no-op off native, so nothing appears in a desktop browser: iterate in the simulator or on a device.
+
+Handle both orientations. On iPhone Duo the crease is vertical in landscape and horizontal in portrait, so a layout that only styles `.fold-vertical` flattens when the phone is turned.
+
+Reach for the plugin's methods when CSS cannot answer the question: the hinge angle, the posture, which display you are on, or where the system put its bars.
+
+## When to consult these references
+
+- **Laying out around the crease** (variables, classes, worked layouts): [css-layout.md](references/css-layout.md)
+- **The API** (methods, events, and what is platform specific): [api.md](references/api.md)
+- **Ionic apps** (`ion-tabs` on the side, the keyboard event a fold fires, Angular's CSS rule): [ionic.md](references/ionic.md)
+- **iPhone Duo specifics** (reserved regions, vertical bars, safe areas, what the hinge status gets wrong): [iphone-duo.md](references/iphone-duo.md)
+- **Android foldables** (postures, rear display, dual screen): [android.md](references/android.md)
+- **Testing** (iPhone Duo simulator, foldable emulator, driving the hinge from the terminal): [testing.md](references/testing.md)
+
+## Hard rules
+
+- ✅ **Split on `var(--fold-left)`, never on 50%.** The variables give the band's leading edge, not its centre, and the coordinates are measured against the web view, so any inset moves them off the viewport midpoint. On iPhone Duo the fold is a 40 point band, so a halfway split also lands inside the part the system wants kept clear.
+- ✅ **Treat `--fold-width` as the keep-clear band.** The margins are *inside* it, so `--fold-margin-*` tells you how much of the band is margin rather than physical crease. Do not add them on top of it. They are iOS only and read `0px` on Android, where a seamless fold also reports zero width, so keep your own minimum clearance: `max(12px, var(--fold-width, 0px))`, with the fallback because the variable does not exist at all on a phone with no fold.
+- ✅ **Expect the fold when the device is fully open, not just half.** The position is reported flat as well as folded, so a layout can line up with the crease before anyone bends anything. A *closed* device reports `state: 'flat'` and no `hingeBounds`, because the plugin drops the fold below 20 degrees.
+- ✅ **Let the layout expand; do not design a screen per pose.** Apple: "Don't reinvent your app when it resizes; allow the existing layout to expand based on the available space instead", and "Avoid extreme layout changes as people fold the device." Google's equivalent is to adapt to window size classes rather than device type, and to consider whether controls and text should avoid the hinge space.
+- ❌ **Do not use `setVerticalBarBehavior({ behavior: 'disabled' })` to avoid adapting.** Apple's HIG asks you not to override bar placement. UIKit's own reference gives the exception: disable it only for interfaces better served by horizontal bars, "such as a fullscreen video player with toolbar controls or a non-scrolling layout like a calculator". It returns the bars to horizontal; it does not hand you the full display.
+- ❌ **Do not poll `getFoldState()` on a timer** when `foldStateChange` will tell you. The exception is the moment the app moves between displays, where iOS pauses the web view: see [iphone-duo.md](references/iphone-duo.md).
+- ❌ **Do not confuse "this device folds" with "there is a fold on this screen".** `isDeviceFoldable()` answers the first, though it can answer `false` on an Android foldable that advertises no tabletop posture and no hinge sensor. The presence of `hingeBounds`, or `--fold-left` in CSS, answers the second, and is what layout should key on. For the *outer screen*, neither is the gate: use `getDisplayModes()` and `displayModeChange`, since rear display and dual screen are Android only and read `unsupported` on iPhone Duo even though it folds. Every *read* method answers safely on any device; `startRearDisplay()` and `startDualScreen()` reject when the mode is unavailable.
+
+## Before reporting done
+
+```bash
+npm run build      # or the app's build
+npx cap sync
+```
+
+Then run it open flat, half open and closed, and fold it shut and open again, which suspends and resumes the web view on iOS. Do one pass at the largest system text size and one with VoiceOver or TalkBack on, since a layout that splits at the crease is exactly where reading order and target sizes go wrong. On iPhone Duo the posture picks the display, so that covers both screens; on Android the outer display needs rear display mode. [testing.md](references/testing.md) has the commands.

package/skills/capacitor-foldable/references/android.md

@@ -0,0 +1,54 @@
+# Android foldables
+
+Backed by Jetpack WindowManager, so the fold comes from whatever the device reports: Pixel Fold, Galaxy Z Fold and Flip, and the foldable emulators.
+
+## Postures
+
+`getFoldState()` reports `posture` as `flat`, `tabletop` or `book`, and `foldStateChange` fires as the device moves. Tabletop is half open with a horizontal hinge, which is the laptop pose: content above the crease, controls below. Book is half open with a vertical hinge.
+
+`isSeparating` says whether the fold actually splits the window into two areas. A flat *foldable* still reports `hingeBounds`, which is what lets a layout line up with the crease before anyone folds it. A device with no fold reports `posture: 'flat'` and no `hingeBounds`, which is the difference worth testing for. It still reports `cameraBounds` from the display cutouts.
+
+`hingeMargins`, `activeDisplay` and the hinge `status` are iOS only and never appear here. `cameraBounds` and `occludedBounds` do: the cutouts, and the fold's own bounds when it fully occludes content. To tell the cover screen from the inner one, lean on `getSizeClass()`, where the outer display shows up as a compact width, keeping in mind it describes the window rather than the panel, so rotation and multi-window move it too.
+
+## The hinge angle
+
+Only devices with a hinge sensor report an angle, and only on Android 11 and later; everything else answers `null`, and the fold state still works, since it comes from WindowManager rather than the sensor. The plugin registers at the normal sensor rate, so it needs no permission and is nowhere near the 200 Hz threshold that would require `HIGH_SAMPLING_RATE_SENSORS`.
+
+## Rear display: move the app to the outer screen
+
+```typescript
+const { rearDisplay } = await Foldable.getDisplayModes();
+if (rearDisplay === 'available') await Foldable.startRearDisplay();
+await Foldable.stopRearDisplay();
+```
+
+Statuses are `active`, `available`, `unavailable` and `unsupported`. The classic use is a selfie with the main camera, previewing on the outer screen. The system asks the user to confirm before the app moves.
+
+The status the `start` methods check comes from a background collector rather than from `getDisplayModes()`, so immediately after launch a positive check can still be rejected. Listen for `displayModeChange` before offering the button, or retry.
+
+## Dual screen: a second window on the other display
+
+```typescript
+await Foldable.startDualScreen({ url: 'cover.html' });
+await Foldable.stopDualScreen();
+```
+
+**Load only content you control.** The plugin refuses anything that is not a page of your own app or a `data:` URL, and keeps the second web view on your origin once it is loaded, because that view shares the app's cookies and storage. Never pass a URL that came from a server, a deep link, a push payload or a user.
+
+A `data:` URL is the easier route for dynamic content and is what the plugin's own example uses, but note two things. It gets an **opaque origin**, so `localStorage` and friends throw there and it cannot read the app's storage: put what the page needs into the document. And `encodeURIComponent` is URL encoding, not HTML escaping, so interpolating a name or a message into `data:text/html,...` is an injection into a page that has JavaScript on. Escape it for HTML first, or ship a static page and pass values in the fragment for its own script to insert with `textContent`.
+
+Treat it as a presentation surface: a plain web view with no Capacitor bridge, so no plugin API inside it. Calling `startDualScreen` again replaces the page rather than messaging it.
+
+Both modes share one window area behind the scenes, and both stop when the activity goes away.
+
+Both modes report through `displayModeChange`, and both are Android only. On iOS and web they read `unsupported`, and the `start` methods reject.
+
+Emulators do not offer dual screen at all, and a Z Flip only in Flex mode, so `unsupported` there is the emulator rather than a bug in your app.
+
+## Permissions
+
+None. The plugin's manifest is empty and adds nothing to your app.
+
+## Quality guidelines
+
+Google's adaptive app quality guidelines make posture support a Tier 1 check and adaptive layouts driven by window size classes a Tier 2 one. Keeping controls and text off the fold is separate fold-aware design guidance rather than a quality check: "Don't place UI controls too close to a fold or hinge when `isSeparating` is true." `posture`, `getSizeClass()` and the fold variables are what all three ask for.

package/skills/capacitor-foldable/references/api.md

@@ -0,0 +1,114 @@
+# The API, and when each part is the right tool
+
+Every **read** method resolves safely on any device, foldable or not. `startRearDisplay()` and `startDualScreen()` reject when the mode is not available; the `stop` methods always resolve.
+
+Platform note up front: `hingeMargins`, `activeDisplay` and the hinge `status` are iOS only; `occludedBounds` is Android only. `cameraBounds` is reported on both, and on iOS it carries every active occlusion, which includes the vertical status bar strip as well as the camera.
+
+Import both the plugin and the polyfill from the package root:
+
+```typescript
+import { Foldable, installFoldablePolyfill } from '@erkamyaman/capacitor-foldable';
+```
+
+## Ask once
+
+```typescript
+const { foldable, supportsTabletop } = await Foldable.isDeviceFoldable();
+```
+
+`supportsTabletop` is a real check on Android (the system advertises the posture). On iOS it mirrors `foldable`, so it is not an independent signal there.
+
+Do not gate layout on this: an Android foldable that advertises no tabletop posture and has no hinge sensor answers `false` while still reporting a fold. For "is there a fold on this screen", test for `hingeBounds`, remembering a closed device has none. For the outer screen on Android, gate on `getDisplayModes()` instead.
+
+## The fold
+
+```typescript
+const fold = await Foldable.getFoldState();
+// state: 'flat' | 'half-opened' | 'closed'   ('closed' is never emitted today)
+// posture: 'flat' | 'tabletop' | 'book'
+// isSeparating, hingeOrientation, hingeBounds
+// cameraBounds                (both: cutouts on Android, active occlusions on iOS)
+// occludedBounds              (Android only, when the fold fully occludes content)
+// hingeMargins, activeDisplay (iOS only)
+```
+
+Use `posture` for layout decisions rather than the raw angle. On iOS it is a threshold on the angle at 20 and 160 degrees with no hysteresis, so avoid designs that flip hard exactly at the boundary; on Android it comes straight from WindowManager's own fold state.
+
+`activeDisplay` tells the outer display from the inner one, but only on iOS. On Android use `getSizeClass()` for the same job.
+
+Listen with `foldStateChange` rather than polling. On Android the very first call can time out after a second and answer `flat`, so treat the first event as the real answer rather than a boot-time read.
+
+## The hinge angle
+
+```typescript
+const { angle, status } = await Foldable.getHingeAngle();
+// angle: degrees, 0 shut and 180 flat, or null without a hinge sensor
+// status: 'closed' | 'partiallyOpen' | 'fullyOpen' | null   (iOS only)
+```
+
+`hingeAngleChange` fires as it moves, carrying the angle alone: call `getHingeAngle()` if you also need the status. On iOS the system's `status` updates lazily and can disagree with the angle; the plugin trusts the angle, and returns both so you can see it. Android reports no status at all.
+
+Good for effects and continuous interactions, not for deciding layout.
+
+## Reserved regions (iOS 27.1)
+
+```typescript
+const { regions } = await Foldable.getReservedRegions();
+// kind: 'division' | 'occlusion', isActive, x/y/width/height, margins
+```
+
+Everything the system reserves on the current display: the fold, the camera, and the strip the vertical status bar occupies. Inactive regions are included, which is how the fold is reported while the device is open flat. Returns `[]` on Android, on web, and on iOS before 27.1.
+
+These coordinates come from the view controller's view, while `hingeBounds` is measured against the web view, so do not mix the two if your web view is inset.
+
+## Size classes
+
+```typescript
+const { horizontal, vertical, widthClass, heightClass } = await Foldable.getSizeClass();
+```
+
+Apple's compact and regular plus Material's window classes. On iOS the first pair are real UIKit traits; on Android and web they are breakpoints on the window size. Either way it is the portable way to tell a small screen from a large one, rather than measuring pixels yourself. `sizeClassChange` fires when it changes.
+
+## Where the system put its bars
+
+```typescript
+const { verticalBarEdge } = await Foldable.getBarPlacement(); // 'leading' | 'trailing' | null
+```
+
+`null` means no vertical bar edge is reported: bars are horizontal, or the platform cannot say, which is always the case on Android, web and iOS before 27.1. On iPhone Duo the bar also arrives as a safe-area inset, so simple layouts need nothing beyond `env(safe-area-inset-*)`. Use this when positioning your own chrome to match. `barPlacementChange` fires when it moves.
+
+```typescript
+await Foldable.setVerticalBarBehavior({ behavior: 'disabled' });  // everything horizontal
+await Foldable.setVerticalBarBehavior({ behavior: 'automatic' }); // system default
+```
+
+Needs `FoldableBridgeViewController`, and resolves `{ applied: false }` when that is missing, on Android, and on web. On iOS any other string rejects, while a missing one falls back to `automatic`; Android and web resolve without validating. Apple asks you not to override bar placement, so keep this for immersive interfaces.
+
+## While the hinge moves
+
+```typescript
+await Foldable.addListener('foldingChange', ({ folding }) => { /* pause heavy work */ });
+```
+
+Only fires where a hinge angle is available: an Android foldable with a hinge sensor, or iPhone Duo on iOS 27.1.
+
+## Android display modes
+
+```typescript
+const { rearDisplay, dualScreen } = await Foldable.getDisplayModes();
+// each: 'active' | 'available' | 'unavailable' | 'unsupported'
+
+if (rearDisplay === 'available') await Foldable.startRearDisplay();
+if (dualScreen === 'available') await Foldable.startDualScreen({ url: 'cover.html' });
+
+await Foldable.stopRearDisplay();
+await Foldable.stopDualScreen();
+```
+
+`startRearDisplay()` shows a system confirmation first, and `startDualScreen()` rejects outright without a `url`. Both accept `available` or `active`.
+
+`displayModeChange` reports both modes together. Relative URLs resolve against the app's own URL, so `cover.html` has to be a page you ship in the web build, which for a bundler means adding it as an extra entry point. A `data:` URL works too, and is the easier route for dynamic content.
+
+The page must be content you wrote: the plugin rejects any other origin, and `encodeURIComponent` is URL encoding rather than HTML escaping, so escape anything you interpolate into a `data:text/html` document. See [android.md](android.md). That page runs in its own web view with no access to Capacitor plugins, and calling `startDualScreen` again replaces it.
+
+Android only; both read as `unsupported` on iOS and web, where the `start` methods reject. See [android.md](android.md).

package/skills/capacitor-foldable/references/css-layout.md

@@ -0,0 +1,145 @@
+# Laying out around the crease
+
+After `installFoldablePolyfill()` on a native platform, the plugin keeps these on `<html>`.
+
+| | |
+| --- | --- |
+| Direction, while a fold is reported | `.fold-vertical` (crease runs down the screen), `.fold-horizontal` (across) |
+| Position and size of the fold band | `var(--fold-left)`, `var(--fold-top)`, `var(--fold-width)`, `var(--fold-height)` |
+| How much of the band is margin (iOS only) | `var(--fold-margin-top)`, `--fold-margin-right`, `--fold-margin-bottom`, `--fold-margin-left` |
+| While the hinge moves | `.folding` |
+| Where native bars went | `.vertical-bars-leading`, `.vertical-bars-trailing`, `var(--vertical-tab-bar-bottom)` |
+| Standard APIs, polyfilled | `.horizontal-viewport-segments-2`, `.vertical-viewport-segments-2`, `.device-posture-folded`, `.device-posture-continuous`, `var(--viewport-segment-*)` |
+
+Three things to know before using them:
+
+- **They are viewport coordinates**, measured against the web view. A grid built from `--fold-left` only lines up if the element's own content box starts at viewport 0. Subtract your own insets otherwise, as the examples app does.
+- **`--fold-width` can be `0px`.** A seamless fold, the kind with no physical gap, reports zero thickness whatever the state, and `--fold-margin-*` is iOS only and reads `0px` on Android. Keep your own minimum gutter, `max(12px, var(--fold-width, 0px))`, rather than relying on the band for visual separation. The fallback matters: on a phone with no fold the variable does not exist, and a bare `var()` with no fallback makes the whole declaration invalid.
+- **`.fold-horizontal` means the hinge is horizontal, not that the device is in tabletop.** It is set while flat too. The tabletop and book postures have no class of their own: read `posture` from `getFoldState()`. (The `.device-posture-*` classes in the table are the Device Posture API's folded and continuous, which is a different thing.)
+
+What is conditional: the `--fold-*` variables, `.fold-*`, `.vertical-bars-*`, `.folding` and the `-viewport-segments-2` classes. What is always set once installed: a `device-posture` class (`continuous` unless half opened), the first segment's `--viewport-segment-*-0-0` variables, and `--vertical-tab-bar-bottom`.
+
+For safe areas, write `var(--safe-area-inset-top, env(safe-area-inset-top))`. Capacitor injects those variables on **Android** from 8.3 with `insetsHandling: 'css'`, where `env()` is unreliable before WebView 140; on iOS nothing sets them and the `env()` fallback is what resolves.
+
+## Two pages, one either side
+
+```css
+.reader { display: grid; gap: 12px; }
+
+.fold-vertical .reader {
+  position: fixed;
+  inset: auto 0 0 0;
+  top: calc(var(--safe-area-inset-top, env(safe-area-inset-top)) + 56px);
+  display: block;
+  border: 0;
+}
+
+.fold-vertical .reader .page {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  padding: 14px;
+  box-sizing: border-box;
+  overflow: auto;
+}
+
+.fold-vertical .reader .page:first-child { left: 0; width: var(--fold-left); }
+.fold-vertical .reader .page:last-child { left: calc(var(--fold-left) + var(--fold-width)); right: 0; }
+```
+
+`position: fixed` with `inset` is what makes the viewport coordinates line up, and `top`/`bottom` on the pages is what makes them fill the container. Keep a border off the container: unlike padding, a border shrinks the containing block and shifts both pages off the fold. The pages carry their own padding, with `box-sizing: border-box` so it eats into the width instead of overflowing the crease.
+
+## A grid whose gutter is the crease
+
+Give the crease its own column, so the normal gutter survives when `--fold-width` is zero, and pin the tiles to the columns either side. Do not rely on a `::before` to reserve the crease column: with no explicit rows, `grid-row: 1 / -1` spans row 1 only, and auto-placement drops tiles into the crease from row 2 down.
+
+```css
+.grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px; }
+
+.fold-vertical .grid {
+  --grid-inset: 16px; /* viewport left edge to this element's content box */
+  grid-template-columns: calc(var(--fold-left) - var(--grid-inset)) var(--fold-width) 1fr;
+  column-gap: 0;
+}
+
+.fold-vertical .grid > *:nth-child(odd) { grid-column: 1; }
+.fold-vertical .grid > *:nth-child(even) { grid-column: 3; }
+.fold-vertical .grid > * { margin: 0 8px; }
+```
+
+The crease is always the middle track, so the pinning selectors have to skip it. `nth-child(odd)` and `nth-child(even)` is the two column special case; with four columns the tracks become
+
+```css
+.fold-vertical .grid {
+  grid-template-columns:
+    repeat(2, calc((var(--fold-left) - var(--grid-inset)) / 2))
+    var(--fold-width)
+    repeat(2, 1fr);
+}
+
+.fold-vertical .grid > *:nth-child(4n + 1) { grid-column: 1; }
+.fold-vertical .grid > *:nth-child(4n + 2) { grid-column: 2; }
+.fold-vertical .grid > *:nth-child(4n + 3) { grid-column: 4; }
+.fold-vertical .grid > *:nth-child(4n) { grid-column: 5; }
+```
+
+Apple asks for an even number of columns so content divides cleanly. Either way the tracks left of the crease must add up to `--fold-left` minus your inset, so use explicit widths there rather than `1fr`.
+
+## Controls below the crease in tabletop
+
+Tabletop is a posture, so it comes from JavaScript. Set a class yourself and let CSS follow:
+
+```typescript
+const apply = ({ posture }: { posture: string }) =>
+  document.documentElement.classList.toggle('tabletop', posture === 'tabletop');
+
+apply(await Foldable.getFoldState());
+const handle = await Foldable.addListener('foldStateChange', apply);
+// later: await handle.remove();
+```
+
+```css
+.tabletop .stage {
+  position: fixed;
+  inset: 0;
+  display: grid;
+  grid-template-rows: var(--fold-top) 1fr;
+  row-gap: max(12px, var(--fold-height));
+}
+```
+
+`position: fixed; inset: 0` matters here too: `--fold-top` is measured from the top of the viewport, and a `.stage` sitting under a header is not.
+
+## Pause work while the hinge moves
+
+```css
+.folding .spinner { animation-play-state: paused; }
+```
+
+`animation-play-state` is not inherited and only affects elements that carry a CSS animation, so put it on the animated element itself. For a chart or anything driven by JavaScript, listen to `foldingChange` and stop redrawing instead. The class appears as the hinge starts moving and goes half a second after it stops, and only on devices that report a hinge angle: an Android foldable without a hinge sensor never gets it.
+
+## Accessibility
+
+The crease is exactly where reading order and target sizes go wrong, so four rules:
+
+- **Keep source order equal to visual order.** The `nth-child` pinning above works only while it is. Re-order the markup rather than moving things visually, or a screen reader reads the pages in the wrong sequence.
+- **Name each page and let the keyboard reach it.** Both panes scroll independently, so give them `role="region"` with an `aria-label`, and `tabindex="0"` on the scroll container.
+- **Use `rem` for your own gutters and insets**, not pixels. Android scales web view text with the system font size while iOS does not unless you opt in, so fixed pixel padding drifts in one direction and never moves in the other. Grid items pinned to a fixed track also need `min-width: 0`, or long words push them into the crease.
+- **Targets stay at least 44 pt, or 48 dp on Android**, which matters most for anything sitting beside the fold.
+
+`prefers-reduced-motion` is a separate concern from `.folding`: the class is a device signal that comes and goes with the hinge, so honour the media query independently, and use `animation: none` there rather than pausing on an arbitrary frame.
+
+Right to left needs its own arm, because the fold variables are physical viewport coordinates while `:first-child` is not:
+
+```css
+[dir='rtl'] .fold-vertical .reader .page:first-child { left: calc(var(--fold-left) + var(--fold-width)); right: 0; width: auto; }
+[dir='rtl'] .fold-vertical .reader .page:last-child { left: 0; width: var(--fold-left); }
+```
+
+## What not to do
+
+- Splitting at `50%`. The coordinates are relative to the web view, and on iPhone Duo the band has width.
+- Relying on `--fold-width` for visual separation. It is `0px` on a seamless fold.
+- Treating `.fold-horizontal` as tabletop, or writing a separate layout per posture. Let one layout expand, and move only what must move.
+- Styling only `.fold-vertical`. iPhone Duo's crease is vertical in landscape and horizontal in portrait, so both need an arm or the layout flattens when the phone turns.
+- Building layout on the polyfilled `--viewport-segment-*` variables. They only describe two segments while the fold actually separates the window, so an open-flat device gives you one segment; the `--fold-*` variables are there either way.

package/skills/capacitor-foldable/references/ionic.md

@@ -0,0 +1,54 @@
+# Ionic apps
+
+## The tab bar belongs on the side
+
+On iPhone Duo the system moves native toolbars and tab bars to the side of the display as a floating pill. Ionic's `ion-tabs` is HTML, so it stays a full width bar at the bottom, next to a status bar that has already moved.
+
+```typescript
+import '@erkamyaman/capacitor-foldable/ionic-tabs.css';
+```
+
+That turns `ion-tabs` into a side pill exactly where native bars go, and only where the system actually puts bars there. It keys on the `vertical-bars-leading` and `vertical-bars-trailing` classes, which `installFoldablePolyfill()` sets, so the stylesheet does nothing on its own. There is also `ionic-tabs-ios26.css`, which gives the horizontal bar iOS 26's floating look on every iPhone.
+
+**Angular cannot import CSS from TypeScript.** That is TypeScript's error rather than Angular's: a side-effect import of a `.css` file has no type declarations, which TypeScript 6 reports as TS2882 (`noUncheckedSideEffectImports` is on by default there) and older versions as TS2307. Angular's `styles` array in `angular.json` is the other normal route. Put it in `src/global.scss` instead, and **as the first rule in the file**, because Sass rejects `@use` after any other rule, including the `@import` lines a stock Ionic `global.scss` starts with:
+
+```scss
+@use '@erkamyaman/capacitor-foldable/ionic-tabs.css';
+
+@import "@ionic/angular/css/core.css";
+// ...the rest of the Ionic imports
+```
+
+React and Vue import it from the entry file as usual, since their bundlers ship type shims for CSS.
+
+## A fold fires a keyboard event
+
+iPhone Duo sends a keyboard event when the device folds. Ionic's keyboard controller measures the app container's height the first time the keyboard opens and caches it, then waits for that exact height before showing the tab bar again. After a fold the height no longer matches, so the bar never comes back. Opt in to the fix:
+
+```typescript
+await installFoldablePolyfill({ ionicKeyboard: true });
+```
+
+It swallows Capacitor's raw keyboard events in the capture phase and puts a `foldable-keyboard-open` class on `<html>` only when something is genuinely focused. That class does nothing on its own: `ionic-tabs.css` carries the rule that hides the bar while the keyboard is up, so take both or neither. The `ios26` stylesheet does not carry that rule. Off by default, since it takes over those events.
+
+## Two views of one screen
+
+If your app has two modes that are really one screen, swap the view in place rather than routing between tabs. Routing mounts a lazy page on every tap, which shows as a blank frame, and Ionic's page transition then slides the new page in sideways, which is very visible on a wide inner display.
+
+```typescript
+readonly mode = signal<'game' | 'meter'>('game');
+```
+
+```html
+@if (mode() === 'game') { <app-game /> } @else { <app-meter /> }
+```
+
+If you do route, `provideIonicAngular({ animated: false })` removes the slide, but be aware it disables every Ionic animation app-wide, including modals and ripples.
+
+## Apple's rules for the side bar
+
+The vertical bar has an order: primary navigation at the top, then prominent actions. Apple also asks you to prefer a symbol over text there, since anything with a label stays in a horizontal bar. The stylesheet hides the labels visually for that reason but keeps them for VoiceOver, so leave them in your markup.
+
+## Styling gotcha
+
+`ion-tab-bar` ships `contain: strict`, which brings size containment with it. The moment you let either dimension come from its contents, it lays out as if empty and collapses: height in the side pill, width in the iOS 26 variant. Both shipped stylesheets set `contain: none` for that reason.

package/skills/capacitor-foldable/references/iphone-duo.md

@@ -0,0 +1,54 @@
+# iPhone Duo
+
+Needs iOS 27.1 and Xcode 27.1 or later. Older versions compile and simply report no fold.
+
+## Measured geometry
+
+Inner display 951 x 669 points in landscape, outer 466 x 678. The fold arrives in JavaScript as `hingeBounds` of x 456, width 40, and a separate `hingeMargins` of 20 points left and right. Those margins are *inside* the band rather than extra to it, so the crease itself is the zero width centre and the whole 40 points is the keep-clear area.
+
+UIKit reports the region on a half point, and the plugin rounds to whole CSS pixels.
+
+## The fold is inactive when flat
+
+A fully open iPhone Duo still has a fold, but the system marks that region inactive. The plugin always asks for inactive regions, which is why `--fold-left` is set whether the device is open flat or half folded. Below 20 degrees the plugin drops the fold, so a closed device reports no `hingeBounds` and no `--fold-*` on the outer display, even though `getReservedRegions()` still lists the region.
+
+Writing native code beside the plugin, the same call needs it spelled out:
+
+```swift
+if #available(iOS 27.1, *) {
+    let regions = view.reservedRegions(kind: .division, options: .includeInactive)
+}
+```
+
+## The hinge status lags the angle
+
+Apple's header suggests preferring `status` when you only need open, closed or partly open. In practice it updates lazily, so the two disagree while the device moves, which is this plugin's own observation rather than documented behaviour. The plugin decides the fold state from the angle whenever a fold region exists, falling back to the status otherwise, and `getHingeAngle()` returns both so you can see the disagreement yourself.
+
+## Vertical bars and safe areas
+
+The system moves bars to the side, and the web view's safe areas follow. Measured on the simulator: with bars on the side, the strip arrives as `env(safe-area-inset-right)` of 84 points on both displays. Calling `setVerticalBarBehavior({ behavior: 'disabled' })` moves it to `env(safe-area-inset-top)` of 82 and drops the right inset to zero, live and without a reload.
+
+So for most layouts, padding with the safe-area insets is enough, and `getBarPlacement()` is for when you are positioning your own chrome to match the system's.
+
+The opt-out needs the plugin's view controller in `ios/App/App/SceneDelegate.swift`:
+
+```swift
+import Capacitor
+import FoldablePlugin
+
+window?.rootViewController = FoldableBridgeViewController()
+```
+
+`FoldablePlugin` is the module name for a Swift Package install, which is what `npx cap add ios` sets up for a new Capacitor 8 app. On a CocoaPods install the module is `ErkamyamanCapacitorFoldable`. Older apps that build the controller in `Main.storyboard` set the class there instead.
+
+## The web view pauses between displays
+
+When the app moves between the outer and inner display, the web view stops running: timers freeze and events queued during the fold arrive late. That is this project's own observation from the simulator rather than documented behaviour, but it is consistent and worth designing around. If your app reads the hinge continuously, refresh state on `visibilitychange`, `focus` and `resize` after a fold, and keep a slow poll as a safety net.
+
+The window can also report its previous size for a moment after a fold. The polyfill already measures again on the next frame and once more shortly after, so CSS variables settle by themselves.
+
+## What crosses the crease
+
+Keep interactive and readable content out of the fold band; continuous visual content such as a photo, a map or a drawing canvas can cross it, and so can scrolling content.
+
+Apple's own fold guidance is to prefer a layout container that adapts by itself, to "prefer an even number of columns so content divides cleanly" in a grid, to "use the `ReservedRegion` API to keep important elements clear of the center if the system doesn't move them automatically", and to favour small adjustments over rearrangement as the device folds.

package/skills/capacitor-foldable/references/testing.md

@@ -0,0 +1,53 @@
+# Testing a foldable layout
+
+## iPhone Duo simulator
+
+Needs the iOS 27.1 runtime, which the device type refuses to go below, and Xcode 27.1 to build against the 27.1 SDK. Build against the 27.0 SDK and the app fills more of the inner display but still leaves gaps; build against anything older and it runs in compatibility mode inside a black border with no fold reported. In Xcode 27 the simulator lives inside **DeviceHub.app**, not `Simulator.app`.
+
+```bash
+open "$(dirname "$(xcode-select -p)")/Applications/DeviceHub.app"
+npx cap run ios     # pick the iPhone Duo
+```
+
+If several Xcodes are installed, check `xcode-select -p` first, or set `DEVELOPER_DIR` to the 27.1 one for the build, or the app compiles against the wrong SDK and reports no fold.
+
+Fold it with the hinge slider in DeviceHub; hold Option for finer control. The inner and outer displays are separate windows.
+
+Screenshots from the terminal, where display 1 is the outer screen and display 3 the inner. The ids are not guaranteed, so `xcrun simctl io <udid> enumerate` lists them:
+
+```bash
+xcrun simctl io <udid> screenshot --display=3 inner.png
+```
+
+Driving the hinge from the terminal is far more repeatable than dragging the slider, using [`hinge`](https://github.com/artemnovichkov/hinge):
+
+```bash
+hinge -d <udid> sweep 180 60 2   # 180 to 60 degrees over 2 seconds
+hinge -d <udid> get
+```
+
+Sweep rather than jumping: an instant change can confuse the simulator's display switching.
+
+Known limitation: taps and key input do not land on the Duo simulator through automation ([XcodeBuildMCP #537](https://github.com/getsentry/XcodeBuildMCP/issues/537)), so scripted UI tests cannot drive it yet. Screenshots work from the terminal with an explicit `--display`; through tooling that cannot pass one, a folded screenshot comes back black because it always targets the inner panel.
+
+## Android foldable emulator
+
+Create a Pixel 9 Pro Fold or 7.6" foldable AVD, then fold it from the extended controls, or:
+
+```bash
+adb emu fold                             # folded
+adb emu unfold                           # unfolded
+adb shell cmd device_state print-states  # this device's state ids
+adb shell cmd device_state state <id>    # force one, ids differ per device
+adb shell cmd device_state state reset   # release the override
+adb emu sensor set hinge-angle0 90       # a specific angle
+```
+
+`adb emu` only talks to an emulator; `cmd device_state` works on real devices too. The state ids are device specific, so print them rather than guessing.
+
+## What to actually check
+
+- Open flat, half open, and closed, so you see **both displays**. These are hands-on checks in DeviceHub, since scripted drivers cannot tap the Duo. A layout only ever seen flat has not been tested.
+- Nothing interactive sits inside the fold band: `var(--fold-width)` wide from `var(--fold-left)`, or `var(--fold-height)` tall from `var(--fold-top)` for a horizontal fold.
+- The app survives being folded shut and opened again, which on iOS suspends and resumes the web view.
+- Text stays readable when the window is short and wide (the inner display held sideways, 951 x 669) and when it is tall and narrow (the outer display upright, 466 x 678). Both panels rotate, so check the other orientation of each.