@alien_org/contract 1.0.0-alpha.3 → 1.0.0-alpha.4

package/README.md

@@ -120,6 +120,18 @@ interface LaunchParams {
 }
 ```
 
+### DisplayMode
+
+Controls how the host app renders the miniapp webview.
+
+| Mode | Header | Close / Options | WebView area | Use case |
+| ---- | ------ | --------------- | ------------ | -------- |
+| `standard` | Visible (title, close, options) | In header | Below header | Default for most miniapps |
+| `fullscreen` | Hidden | Floating overlay | Entire screen | Games, media, maps |
+| `immersive` | Hidden | **None** | Entire screen | Custom UIs that provide their own exit (must call `app:close`) |
+
+In all modes the miniapp receives `safeAreaInsets` and should respect them for system UI (status bar, notch, home indicator).
+
 ## Adding New Methods/Events
 
 1. Define in `src/methods/definitions/methods.ts` or `src/events/definitions/events.ts`

package/dist/index.cjs

@@ -6,9 +6,20 @@
 const PLATFORMS = ["ios", "android"];
 /**
 * Supported display modes for miniapps.
-* - `standard` — standard webview with native chrome
-* - `fullscreen` — fullscreen webview, native controls still visible
-* - `immersive` — no native UI elements at all (no close button, options, etc.)
+*
+* - `standard` — Default. Native header with close button, options menu, and
+*   miniapp title is visible. WebView is inset below the header. Safe area
+*   insets account for the header height.
+*
+* - `fullscreen` — WebView occupies the entire screen. The native close button
+*   and options menu remain as floating overlays so the user can always exit.
+*   The miniapp must respect safe area insets for system UI (status bar, notch,
+*   home indicator).
+*
+* - `immersive` — WebView occupies the entire screen with zero native UI.
+*   No close button, no options menu, no header — the miniapp owns the full
+*   viewport. The miniapp is responsible for providing its own exit mechanism
+*   (e.g. calling `app:close`). Safe area insets still apply for system UI.
 */
 const DISPLAY_MODES = [
 	"standard",

package/dist/index.d.cts

@@ -322,9 +322,20 @@ declare const PLATFORMS: readonly ["ios", "android"];
 type Platform = (typeof PLATFORMS)[number];
 /**
  * Supported display modes for miniapps.
- * - `standard` — standard webview with native chrome
- * - `fullscreen` — fullscreen webview, native controls still visible
- * - `immersive` — no native UI elements at all (no close button, options, etc.)
+ *
+ * - `standard` — Default. Native header with close button, options menu, and
+ *   miniapp title is visible. WebView is inset below the header. Safe area
+ *   insets account for the header height.
+ *
+ * - `fullscreen` — WebView occupies the entire screen. The native close button
+ *   and options menu remain as floating overlays so the user can always exit.
+ *   The miniapp must respect safe area insets for system UI (status bar, notch,
+ *   home indicator).
+ *
+ * - `immersive` — WebView occupies the entire screen with zero native UI.
+ *   No close button, no options menu, no header — the miniapp owns the full
+ *   viewport. The miniapp is responsible for providing its own exit mechanism
+ *   (e.g. calling `app:close`). Safe area insets still apply for system UI.
  */
 declare const DISPLAY_MODES: readonly ["standard", "fullscreen", "immersive"];
 /**

package/dist/index.d.mts

@@ -322,9 +322,20 @@ declare const PLATFORMS: readonly ["ios", "android"];
 type Platform = (typeof PLATFORMS)[number];
 /**
  * Supported display modes for miniapps.
- * - `standard` — standard webview with native chrome
- * - `fullscreen` — fullscreen webview, native controls still visible
- * - `immersive` — no native UI elements at all (no close button, options, etc.)
+ *
+ * - `standard` — Default. Native header with close button, options menu, and
+ *   miniapp title is visible. WebView is inset below the header. Safe area
+ *   insets account for the header height.
+ *
+ * - `fullscreen` — WebView occupies the entire screen. The native close button
+ *   and options menu remain as floating overlays so the user can always exit.
+ *   The miniapp must respect safe area insets for system UI (status bar, notch,
+ *   home indicator).
+ *
+ * - `immersive` — WebView occupies the entire screen with zero native UI.
+ *   No close button, no options menu, no header — the miniapp owns the full
+ *   viewport. The miniapp is responsible for providing its own exit mechanism
+ *   (e.g. calling `app:close`). Safe area insets still apply for system UI.
  */
 declare const DISPLAY_MODES: readonly ["standard", "fullscreen", "immersive"];
 /**

package/dist/index.mjs

@@ -5,9 +5,20 @@
 const PLATFORMS = ["ios", "android"];
 /**
 * Supported display modes for miniapps.
-* - `standard` — standard webview with native chrome
-* - `fullscreen` — fullscreen webview, native controls still visible
-* - `immersive` — no native UI elements at all (no close button, options, etc.)
+*
+* - `standard` — Default. Native header with close button, options menu, and
+*   miniapp title is visible. WebView is inset below the header. Safe area
+*   insets account for the header height.
+*
+* - `fullscreen` — WebView occupies the entire screen. The native close button
+*   and options menu remain as floating overlays so the user can always exit.
+*   The miniapp must respect safe area insets for system UI (status bar, notch,
+*   home indicator).
+*
+* - `immersive` — WebView occupies the entire screen with zero native UI.
+*   No close button, no options menu, no header — the miniapp owns the full
+*   viewport. The miniapp is responsible for providing its own exit mechanism
+*   (e.g. calling `app:close`). Safe area insets still apply for system UI.
 */
 const DISPLAY_MODES = [
 	"standard",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alien_org/contract",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",