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

package/README.md

@@ -33,6 +33,7 @@ import type {
   // Launch parameters
   LaunchParams,         // Host-injected params (authToken, contractVersion, etc.)
   Platform,             // 'ios' | 'android'
+  DisplayMode,          // 'standard' | 'fullscreen' | 'immersive'
 
   // Utilities
   Version,              // Semantic version string type
@@ -42,10 +43,11 @@ import type {
 ### Constants
 
 ```typescript
-import { PLATFORMS, releases } from '@alien_org/contract';
+import { DISPLAY_MODES, PLATFORMS, releases } from '@alien_org/contract';
 
-PLATFORMS  // ['ios', 'android']
-releases   // Record<Version, MethodName[]> - version to methods mapping
+PLATFORMS      // ['ios', 'android']
+DISPLAY_MODES  // ['standard', 'fullscreen', 'immersive']
+releases       // Record<Version, MethodName[]> - version to methods mapping
 ```
 
 ### Version Utilities
@@ -114,10 +116,22 @@ interface LaunchParams {
   platform: Platform | undefined;          // 'ios' | 'android'
   safeAreaInsets: SafeAreaInsets | undefined; // System UI insets (CSS px)
   startParam: string | undefined;          // Custom param (referrals, etc.)
-  isFullscreen: boolean | undefined;       // Launched in fullscreen mode
+  displayMode: DisplayMode;                 // 'standard' | 'fullscreen' | 'immersive'
 }
 ```
 
+### 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

@@ -4,6 +4,28 @@
 * Supported platforms for miniapps.
 */
 const PLATFORMS = ["ios", "android"];
+/**
+* Supported display modes for miniapps.
+*
+* - `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",
+	"fullscreen",
+	"immersive"
+];
 
 //#endregion
 //#region src/methods/versions/releases.ts
@@ -115,6 +137,7 @@ const WALLET_ERROR = {
 };
 
 //#endregion
+exports.DISPLAY_MODES = DISPLAY_MODES;
 exports.PLATFORMS = PLATFORMS;
 exports.WALLET_ERROR = WALLET_ERROR;
 exports.getMethodMinVersion = getMethodMinVersion;

package/dist/index.d.cts

@@ -320,6 +320,28 @@ declare const PLATFORMS: readonly ["ios", "android"];
  * Platform the miniapp is running on.
  */
 type Platform = (typeof PLATFORMS)[number];
+/**
+ * Supported display modes for miniapps.
+ *
+ * - `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"];
+/**
+ * Display mode for the miniapp webview.
+ */
+type DisplayMode = (typeof DISPLAY_MODES)[number];
 /**
  * Safe area insets in CSS pixels, injected by the host app.
  * Accounts for system UI (status bar, notch, home indicator, nav bar).
@@ -350,10 +372,11 @@ interface LaunchParams {
    */
   startParam: string | undefined;
   /**
-   * Whether the miniapp was launched in fullscreen mode.
+   * Display mode for the miniapp webview.
+   * Defaults to `'standard'` when not provided by the host app.
    * @since 1.0.0
    */
-  isFullscreen: boolean | undefined;
+  displayMode: DisplayMode;
 }
 //#endregion
 //#region src/methods/types/payload.d.ts
@@ -717,4 +740,4 @@ declare function isMethodSupported(method: MethodName, version: Version): boolea
  */
 declare function getMethodMinVersion(method: MethodName): Version | undefined;
 //#endregion
-export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type HapticImpactStyle, type HapticNotificationType, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type SafeAreaInsets, type SolanaChain, type SolanaCommitment, type Version, WALLET_ERROR, type WalletSolanaErrorCode, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
+export { type CreateEventPayload, type CreateMethodPayload, DISPLAY_MODES, type DisplayMode, type EventName, type EventPayload, type Events, type HapticImpactStyle, type HapticNotificationType, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type SafeAreaInsets, type SolanaChain, type SolanaCommitment, type Version, WALLET_ERROR, type WalletSolanaErrorCode, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/dist/index.d.mts

@@ -320,6 +320,28 @@ declare const PLATFORMS: readonly ["ios", "android"];
  * Platform the miniapp is running on.
  */
 type Platform = (typeof PLATFORMS)[number];
+/**
+ * Supported display modes for miniapps.
+ *
+ * - `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"];
+/**
+ * Display mode for the miniapp webview.
+ */
+type DisplayMode = (typeof DISPLAY_MODES)[number];
 /**
  * Safe area insets in CSS pixels, injected by the host app.
  * Accounts for system UI (status bar, notch, home indicator, nav bar).
@@ -350,10 +372,11 @@ interface LaunchParams {
    */
   startParam: string | undefined;
   /**
-   * Whether the miniapp was launched in fullscreen mode.
+   * Display mode for the miniapp webview.
+   * Defaults to `'standard'` when not provided by the host app.
    * @since 1.0.0
    */
-  isFullscreen: boolean | undefined;
+  displayMode: DisplayMode;
 }
 //#endregion
 //#region src/methods/types/payload.d.ts
@@ -717,4 +740,4 @@ declare function isMethodSupported(method: MethodName, version: Version): boolea
  */
 declare function getMethodMinVersion(method: MethodName): Version | undefined;
 //#endregion
-export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type HapticImpactStyle, type HapticNotificationType, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type SafeAreaInsets, type SolanaChain, type SolanaCommitment, type Version, WALLET_ERROR, type WalletSolanaErrorCode, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
+export { type CreateEventPayload, type CreateMethodPayload, DISPLAY_MODES, type DisplayMode, type EventName, type EventPayload, type Events, type HapticImpactStyle, type HapticNotificationType, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type SafeAreaInsets, type SolanaChain, type SolanaCommitment, type Version, WALLET_ERROR, type WalletSolanaErrorCode, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/dist/index.mjs

@@ -3,6 +3,28 @@
 * Supported platforms for miniapps.
 */
 const PLATFORMS = ["ios", "android"];
+/**
+* Supported display modes for miniapps.
+*
+* - `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",
+	"fullscreen",
+	"immersive"
+];
 
 //#endregion
 //#region src/methods/versions/releases.ts
@@ -114,4 +136,4 @@ const WALLET_ERROR = {
 };
 
 //#endregion
-export { PLATFORMS, WALLET_ERROR, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
+export { DISPLAY_MODES, PLATFORMS, WALLET_ERROR, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/package.json

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