Resizable Windows for Capacitor iOS Apps

A Capacitor app is a full-window WKWebView in CAPBridgeViewController. The web view follows its window. The work is to make the web layout respond to width changes, and to remove native code (app, custom code, plugins) that assumes one full-screen window.

When to Use

TRIGGER when:

• Preparing an app for iPad multitasking, Stage Manager, windowed iPad apps, the foldable iPhone, or external displays
• The layout breaks or does not update when the window is resized
• A native overlay from a plugin (scanner, camera preview, custom sheet) is the wrong size or position in split view
• Xcode or App Store Connect warns about UIRequiresFullScreen, missing iPad orientations, or launch screen requirements
• The user asks to remove UIScreen.main, userInterfaceIdiom, interfaceOrientation or AppDelegate lifecycle use

Do not use:

• CSS env(safe-area-inset-*) setup and notch padding only: safe-area-handling
• Moving AppDelegate to SceneDelegate: capacitor-uiscene-migration (prerequisite for Xcode 27)
• Keyboard overlap: capacitor-keyboard
• Tailwind breakpoints only: tailwind-capacitor

Facts that drive the plan

• iOS 27 ignores UIRequiresFullScreen and resizes the scene anyway (TN3192). Never delete the key silently: deleting it makes the app resizable at once on current iOS. Never add UIRequiresFullScreenIgnoredStartingWithVersion on your own: its value decides which releases keep the old behavior. Both are the user's call, after testing.
• The iOS 27 SDK requires a launch screen declaration. Without one the upload is rejected with ITMS-90870. Capacitor templates set UILaunchStoryboardName; keep it.
• Xcode 27 requires the scene lifecycle. Capacitor 8.5 templates ship SceneDelegate.swift. Without it, AppDelegate lifecycle methods are the only signal, which is wrong in multi-window. Run capacitor-uiscene-migration first if UIApplicationSceneManifest is missing.
• Keep UIApplicationSupportsMultipleScenes = false. Each scene would create its own CAPBridgeViewController, with a second WebView and plugin set. Capacitor added scene-scoped notifications in 8.5 so plugins can prepare, but multi-window is not supported in the templates. Resizing works with a single scene.
• CAPBridgeViewController builds supportedInterfaceOrientations from the iPhone key UISupportedInterfaceOrientations only, not from UISupportedInterfaceOrientations~ipad (Capacitor 8.5 source). An iPad that declares all four orientations can still be locked by the bridge mask. Report it; override supportedInterfaceOrientations in a bridge subclass only if the user wants different iPad behavior.
• The web layer gets resize events for free. WKWebView resizes with the window and fires resize. Breakage comes from layout code that reads the device instead of the viewport.
• Plugins are third-party code. Edits to node_modules are lost on install. Report plugin findings, upgrade the plugin, open an issue upstream, or use patch-package only as a stopgap, with user approval.

References

Only load a reference when its topic is in play.

Script: scripts/scan-legacy-apis.sh scans ios/App/App and every node_modules/**/ios folder and prints the resize-related Info.plist keys. Read-only.

Workflow

1. Prerequisites (read-only)

Read ios/App/App/Info.plist, AppDelegate.swift, SceneDelegate.swift, the @capacitor/ios version, and the TARGETED_DEVICE_FAMILY build setting (1,2 = iPhone and iPad). Report:

2. Scan

bash <skill>/scripts/scan-legacy-apis.sh .

Also scan the web code (references/web-layer.md):

grep -rnE 'screen\.(width|height|availWidth)|window\.orientation|orientationchange|\b100vh\b|navigator\.userAgent.*(iPad|iPhone)|isPlatform\(.(ipad|tablet|iphone)|innerWidth' src --include='*.{ts,tsx,js,jsx,vue,svelte,css,scss}'

Make a TODO list with one entry per file. Large projects: process files in batches of 3 to 5. Every file in the list gets a change or a written reason for no change.

3. Report, then ask

Group the findings into: app web code, app native code, plugins (by package), Info.plist. For each, state the fix. Ask the user before:

• changing UIRequiresFullScreen, orientation keys or the orientation mask,
• changing a public method signature in shared native code,
• patching a plugin in node_modules.

4. Fix

• Web layer first. It is usually the whole fix: references/web-layer.md.
• App native code: references/native-replacements.md. Only edit lines that contain the target API. Keep every if/else branch and #available guard. Never replace a dynamic value with a literal, and never replace one global (UIScreen.main) with another (UIApplication.shared, UITraitCollection.current, UIDevice.current).
• Empty template stubs (applicationDidBecomeActive and friends with only comments) are harmless. Move them only if they contain code.
• Plugins: references/plugin-audit.md.

5. Verify

npx cap sync ios
xcrun simctl list devices available | grep -i ipad
npx cap run ios --target <iPad-simulator-UDID>

• On the iPad simulator (iPadOS 26+), switch the app to a window and drag its corner. Check narrow, medium and wide sizes. Also try Split View with another app.
• Rotate during each size. Open and close the keyboard in a narrow window.
• Check native overlays from plugins (scanner, camera preview, pickers) at a narrow width.
• Background and foreground the app. JS pause / resume must fire.
• If Xcode offers a foldable iPhone simulator, test fold and unfold the same way.
• Re-run the scan. Remaining hits must each have a written reason (non-layout use such as camera capture orientation or analytics).

Error Handling

Related Skills

• safe-area-handling: CSS env() variables and the status bar overlay
• capacitor-uiscene-migration: SceneDelegate adoption, the prerequisite for scene-aware fixes
• tailwind-capacitor: responsive breakpoints in Tailwind
• capacitor-testing: simulator and device verification loop
• capacitor-plugin-upgrade-v8-to-v9: when a plugin fix needs a new major version