@rdlabo/capacitor-native-ui 2.0.0-2 → 2.0.0-3

package/docs/ionic-vertical-bars.md

@@ -14,7 +14,7 @@ Read [how projection works](../README.md#how-projection-works) for the relations
 | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | Ionic components with your own theme, Ionic's default styles, or another theme | [Ionic setup below](#try-it-in-your-existing-ionic-app)                                                                           | Foldable device placement, standalone rail CSS and the Ionic Native UI adapter. Keep your existing theme. |
 | No Ionic components (plain HTML, React, Vue, Angular, etc.)                    | [HTML setup](framework-independent.md), then its [device rail setup](framework-independent.md#device-placement-for-vertical-bars) | `@rdlabo/capacitor-native-ui/core` and Foldable. Your app supplies the rail layout; no theme package.     |
-| Already using the iOS 27 theme and Native UI                                   | [Connect device placement](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable)                           | Reuse your existing runtime. Do not start another one.                                                    |
+| Already using the iOS 27 theme and Native UI                                   | [Connect device placement](vertical-bars.md#use-with-capacitor-foldable)                                                          | Reuse your existing runtime. Do not start another one.                                                    |
 
 **Without Ionic, follow the HTML guide instead of the steps below.** You do not need `@rdlabo/ionic-theme-ios27`, `vertical-bars.css`, `ion-app`, or Ionic navigation animations. Explicitly marked HTML buttons and back buttons are supported; arbitrary HTML tabs are not automatically converted. A browser preview requires an application-styled `webHost`; native rail presentation also requires supported iOS hardware and software.
 
@@ -26,7 +26,7 @@ iPhone Duo support and Vertical Bars are stable starting with version 2.0.0.
 
 ### 1. Install and load the standalone stylesheet
 
-Start with your existing Ionic app (Ionic `>=8.8.1 <10`, Capacitor 8.5 or later). Install Native UI, the layout stylesheet package and the required device-state plugin together:
+Start with your existing Ionic app (Ionic `>=8.8.1 <10`, Capacitor 8.5 or later). Existing Foldable installations must meet the [placement API requirement](vertical-bars.md#use-with-capacitor-foldable): version 8.3.3 or later within version 8. Install Native UI, the layout stylesheet package and the required device-state plugin together:
 
 ```bash
 npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
@@ -125,6 +125,12 @@ await rail.destroy();
 
 If Native UI is already active, keep that runtime and add only the placement subscription. Do not start a second runtime. For shared configuration and application-owned CSS, see [Foldable integration](vertical-bars.md#use-with-capacitor-foldable).
 
+### Initial layout timing
+
+Run step 3 from your application root as soon as `ion-app` is mounted; do not wait for a routed page's data requests. `setVerticalBarsLayout()` needs that element to exist and does not save placement supplied before mounting. Keep startup and cleanup with the same application owner, as described in [the framework lifecycle examples](setup.md#place-startup-in-your-frameworks-app-root).
+
+Native startup, device placement and control rendering are asynchronous. Resolving `enableNativeUI()` gives you the runtime handle, not a guarantee that controls have already been projected. Starting promptly avoids application-added waiting, but the initial Web layout may still be visible before native projection.
+
 ### 4. Build, sync and run on iPhone Duo
 
 Build your application's Web assets, then sync the native project:

package/docs/native-ui.md

@@ -323,7 +323,7 @@ Native projection resumes only after every overlay requiring Web rendering close
 
 During retirement, the source is restored and allowed to paint before its native cover is removed. During acquisition, the source is hidden only after a successful, current native response. Delayed responses are revalidated per control: existing eligible controls retain their native cover while content updates catch up. Only removed or ineligible sources return to Web; newly acquired sources require an exact acknowledgement. Ordinary page mutations never call the global clear operation. UIKit tab instances and items are retained, and equal frames/selections are not reapplied. Duplicate/stale activations are discarded. WebKit and UIKit still render separately: the implementation avoids an intentional blank frame, but does not provide an OS-level atomic compositing guarantee. Validate custom transitions and overlays on the app's supported simulators before rollout; unknown overlay systems are outside the automatic integration contract.
 
-If a bridge update fails or times out, the runtime stops and restores Web rendering. It does not automatically reconnect. `getStatus()` reports `stopped` and the reason; to retry deliberately, call `destroy()` on that handle and then `enableNativeUI()` again.
+If a bridge update fails or times out, native projection stops and Web rendering is restored. It does not automatically reconnect. `getStatus().reason` reports the failure; while the Web fallback remains active, the public handle reports `state: 'web'`, not `stopped`. To retry deliberately, call `destroy()` on that handle and then `enableNativeUI()` again.
 
 Failures or timeouts in required startup bridge calls return a Web fallback handle. Optional WebView metrics may fail without disabling native controls. `destroy()` waits for teardown; repeated calls share its completion. A new activation requested while teardown is running waits for it, including when the application calls `destroy()` without awaiting it. Await these promises when the next application operation depends on cleanup, and handle any rejection.
 

package/docs/vertical-bars.md

@@ -10,7 +10,7 @@ Choose your setup before using this reference:
 
 - **Ionic with a custom or default theme:** [Ionic rail setup](ionic-vertical-bars.md#try-it-in-your-existing-ionic-app).
 - **No Ionic:** [HTML setup](framework-independent.md) and its [device rail setup](framework-independent.md#device-placement-for-vertical-bars). Use `/core` and your own layout; the Ionic setup below does not apply.
-- **Existing iOS 27 theme and Native UI:** [Connect device placement](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable) using your existing runtime.
+- **Existing iOS 27 theme and Native UI:** [Connect device placement](#use-with-capacitor-foldable) using your existing runtime.
 
 This page covers device-plugin integration, control eligibility, native appearance and runtime options. For posture-driven Ionic split panes, see [Device layout and split panes](../../theme-ios27/docs/vertical-bars-layout.md).
 
@@ -44,6 +44,8 @@ The [theme's optional rail stylesheet](https://github.com/rdlabo-dev/ionic-theme
 
 [`@erkamyaman/capacitor-foldable`](https://github.com/erkamyaman/capacitor-foldable) is required in the standard Vertical Bars setup. Install it with Native UI as shown above, and connect its device placement to your Web layout. Native UI does not subscribe to Foldable automatically.
 
+The placement examples require Foldable **8.3.3 or later within version 8**, which includes `BarPlacement.inset`. If your app already uses an older version, update it with `npm install @erkamyaman/capacitor-foldable@^8.3.3`, then sync and rebuild the native app.
+
 | Owner                | Responsibility                                                                              |
 | -------------------- | ------------------------------------------------------------------------------------------- |
 | Foldable             | Report initial device state and subsequent placement/posture changes.                       |

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0-2",
+  "version": "2.0.0-3",
   "author": "Masahiko Sakakibara <sakakibara@rdlabo.jp>",
   "license": "MIT",
   "repository": {
@@ -86,6 +86,6 @@
     }
   },
   "dependencies": {
-    "@rdlabo/ionic-theme-utils": "0.1.4"
+    "@rdlabo/ionic-theme-utils": "0.1.5"
   }
 }