@alien_org/contract 1.1.1-alpha → 1.3.1-beta

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
@@ -63,7 +65,7 @@ isMethodSupported('payment:request', '0.0.9');   // false
 
 // Get minimum version that supports a method
 getMethodMinVersion('app:ready');         // '0.0.9'
-getMethodMinVersion('payment:request');   // '0.0.14'
+getMethodMinVersion('payment:request');   // '0.1.1'
 
 // Get version where a method was introduced
 getReleaseVersion('app:ready');           // '0.0.9'
@@ -74,17 +76,32 @@ getReleaseVersion('app:ready');           // '0.0.9'
 | Method | Since | Description |
 |--------|-------|-------------|
 | `app:ready` | 0.0.9 | Notify host that miniapp is ready |
-| `miniapp:close.ack` | 0.0.14 | Acknowledge close request |
-| `host.back.button:toggle` | 0.0.14 | Show/hide back button |
-| `payment:request` | 0.0.14 | Request payment |
+| `payment:request` | 0.1.1 | Request payment |
+| `clipboard:write` | 0.1.1 | Write text to clipboard |
+| `clipboard:read` | 0.1.1 | Read text from clipboard |
+| `link:open` | 0.1.3 | Open a URL |
+| `haptic:impact` | 0.2.4 | Trigger haptic impact feedback |
+| `haptic:notification` | 0.2.4 | Trigger haptic notification feedback |
+| `haptic:selection` | 0.2.4 | Trigger haptic selection feedback |
+| `wallet.solana:connect` | 1.0.0 | Request Solana wallet connection |
+| `wallet.solana:disconnect` | 1.0.0 | Disconnect from Solana wallet |
+| `wallet.solana:sign.transaction` | 1.0.0 | Sign a Solana transaction |
+| `wallet.solana:sign.message` | 1.0.0 | Sign a Solana message |
+| `wallet.solana:sign.send` | 1.0.0 | Sign and send a Solana transaction |
+| `app:close` | 1.0.0 | Request host to close the miniapp |
+| `host.back.button:toggle` | 1.0.0 | Show/hide back button |
 
 ## Available Events
 
 | Event | Since | Description |
 |-------|-------|-------------|
-| `miniapp:close` | 0.0.14 | Host is closing miniapp |
-| `host.back.button:clicked` | 0.0.14 | Back button was clicked |
-| `payment:response` | 0.0.14 | Payment result |
+| `host.back.button:clicked` | 1.0.0 | Back button was clicked |
+| `payment:response` | 0.1.1 | Payment result |
+| `clipboard:response` | 0.1.1 | Clipboard read result |
+| `wallet.solana:connect.response` | 1.0.0 | Wallet connection result |
+| `wallet.solana:sign.transaction.response` | 1.0.0 | Transaction signing result |
+| `wallet.solana:sign.message.response` | 1.0.0 | Message signing result |
+| `wallet.solana:sign.send.response` | 1.0.0 | Sign and send result |
 
 ## LaunchParams
 
@@ -92,14 +109,28 @@ Parameters injected by the host app:
 
 ```typescript
 interface LaunchParams {
-  authToken: string | undefined;        // JWT auth token
-  contractVersion: Version | undefined; // Host's contract version
-  hostAppVersion: string | undefined;   // Host app version
-  platform: Platform | undefined;       // 'ios' | 'android'
-  startParam: string | undefined;       // Custom param (referrals, etc.)
+  authToken: string | undefined;           // JWT auth token
+  contractVersion: Version | undefined;    // Host's contract version
+  hostAppVersion: string | undefined;      // Host app version
+  platform: Platform | undefined;          // 'ios' | 'android'
+  safeAreaInsets: SafeAreaInsets | undefined; // System UI insets (CSS px)
+  startParam: string | undefined;          // Custom param (referrals, etc.)
+  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

@@ -1,15 +1,35 @@
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/launch-params.ts
 /**
 * 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
 const releases = {
 	"0.0.9": ["app:ready"],
-	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"],
 	"0.1.1": [
 		"payment:request",
 		"clipboard:write",
@@ -26,11 +46,11 @@ const releases = {
 		"wallet.solana:disconnect",
 		"wallet.solana:sign.transaction",
 		"wallet.solana:sign.message",
-		"wallet.solana:sign.send"
-	],
-	"1.1.0": ["fullscreen:request", "fullscreen:exit"]
+		"wallet.solana:sign.send",
+		"app:close",
+		"host.back.button:toggle"
+	]
 };
-
 //#endregion
 //#region src/methods/versions/get-release-version.ts
 function getReleaseVersion(method, payload) {
@@ -43,7 +63,6 @@ function getReleaseVersion(method, payload) {
 		});
 	}) || null;
 }
-
 //#endregion
 //#region src/methods/versions/index.ts
 /**
@@ -90,7 +109,6 @@ function getMethodMinVersion(method) {
 		if (methods.some((m) => typeof m === "string" ? m === method : m.method === method)) return version;
 	}
 }
-
 //#endregion
 //#region src/utils.ts
 /**
@@ -113,11 +131,11 @@ const WALLET_ERROR = {
 	INTERNAL_ERROR: -32603,
 	REQUEST_EXPIRED: 8e3
 };
-
 //#endregion
+exports.DISPLAY_MODES = DISPLAY_MODES;
 exports.PLATFORMS = PLATFORMS;
 exports.WALLET_ERROR = WALLET_ERROR;
 exports.getMethodMinVersion = getMethodMinVersion;
 exports.getReleaseVersion = getReleaseVersion;
 exports.isMethodSupported = isMethodSupported;
-exports.releases = releases;
+exports.releases = releases;

package/dist/index.d.cts

@@ -87,14 +87,6 @@ type PaymentWebhookStatus = 'finalized' | 'failed';
  * @schema
  */
 type PaymentTestScenario = 'paid' | 'paid:failed' | 'cancelled' | `error:${PaymentErrorCode}`;
-/**
- * Fullscreen error codes.
- * Returned in `fullscreen:failed` event when fullscreen request fails.
- * - `ALREADY_FULLSCREEN`: Miniapp is already in fullscreen mode
- * @since 1.1.0
- * @schema
- */
-type FullscreenErrorCode = 'ALREADY_FULLSCREEN';
 /**
  * Haptic impact feedback styles.
  * Maps to UIImpactFeedbackGenerator styles on iOS
@@ -143,13 +135,9 @@ type WalletSolanaErrorCode = 5000 | -32602 | -32603 | 8000;
  * @since 1.0.0
  */
 declare const WALLET_ERROR: {
-  /** User rejected the request (cancelled approval screen). */
-  readonly USER_REJECTED: 5000;
-  /** Invalid params — transaction deserialization failed, malformed input. */
-  readonly INVALID_PARAMS: -32602;
-  /** Internal error — transaction broadcast failed, unexpected error. */
-  readonly INTERNAL_ERROR: -32603;
-  /** Request expired before the user responded. */
+  /** User rejected the request (cancelled approval screen). */readonly USER_REJECTED: 5000; /** Invalid params — transaction deserialization failed, malformed input. */
+  readonly INVALID_PARAMS: -32602; /** Internal error — transaction broadcast failed, unexpected error. */
+  readonly INTERNAL_ERROR: -32603; /** Request expired before the user responded. */
   readonly REQUEST_EXPIRED: 8000;
 };
 /**
@@ -182,15 +170,9 @@ interface CreateEventPayload<Payload = never> {
  * @schema
  */
 interface Events {
-  /**
-   * Miniapp close event, fired by the host app just before the miniapp is closed.
-   * @since 0.0.14
-   * @schema
-   */
-  'miniapp:close': CreateEventPayload<Empty>;
   /**
    * Host app's back button clicked event.
-   * @since 0.0.14
+   * @since 1.0.0
    * @schema
    */
   'host.back.button:clicked': CreateEventPayload<Empty>;
@@ -259,46 +241,14 @@ interface Events {
      */
     errorCode?: 'permission_denied' | 'unavailable';
   }>>;
-  /**
-   * Fullscreen state changed, fired by the host app
-   * after `fullscreen:request` or `fullscreen:exit`.
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:changed': CreateEventPayload<{
-    /**
-     * Whether the miniapp is currently in fullscreen mode.
-     * @since 1.1.0
-     * @schema
-     */
-    isFullscreen: boolean;
-  }>;
-  /**
-   * Fullscreen request failed.
-   * Fired by the host app when `fullscreen:request` cannot be fulfilled
-   * (e.g., the miniapp is already in fullscreen mode).
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:failed': CreateEventPayload<{
-    /**
-     * Error code indicating why the fullscreen request failed.
-     * @since 1.1.0
-     * @schema
-     */
-    error: FullscreenErrorCode;
-  }>;
   /**
    * Solana wallet connection response.
    * @since 1.0.0
    * @schema
    */
   'wallet.solana:connect.response': CreateEventPayload<WithReqId<{
-    /** Base58-encoded public key of the connected wallet */
-    publicKey?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base58-encoded public key of the connected wallet */publicKey?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
   /**
@@ -307,11 +257,8 @@ interface Events {
    * @schema
    */
   'wallet.solana:sign.transaction.response': CreateEventPayload<WithReqId<{
-    /** Base64-encoded signed transaction */
-    signedTransaction?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base64-encoded signed transaction */signedTransaction?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
   /**
@@ -320,13 +267,9 @@ interface Events {
    * @schema
    */
   'wallet.solana:sign.message.response': CreateEventPayload<WithReqId<{
-    /** Base58-encoded Ed25519 signature (64 bytes) */
-    signature?: string;
-    /** Base58-encoded public key that signed the message */
-    publicKey?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base58-encoded Ed25519 signature (64 bytes) */signature?: string; /** Base58-encoded public key that signed the message */
+    publicKey?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
   /**
@@ -335,11 +278,8 @@ interface Events {
    * @schema
    */
   'wallet.solana:sign.send.response': CreateEventPayload<WithReqId<{
-    /** Base58-encoded transaction signature */
-    signature?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base58-encoded transaction signature */signature?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
 }
@@ -357,6 +297,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).
@@ -387,10 +349,11 @@ interface LaunchParams {
    */
   startParam: string | undefined;
   /**
-   * Whether the miniapp was launched in fullscreen mode.
-   * @since 1.1.0
+   * 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
@@ -411,27 +374,27 @@ interface Methods {
   /**
    * Miniapp ready method.
    * Sent by the miniapp to notify the host app that it has loaded and is ready to be displayed.
-   * @since 0.0.1
+   * @since 0.0.9
    * @schema
    */
   'app:ready': CreateMethodPayload<Empty>;
   /**
-   * Miniapp close acknowledgment method.
-   * Sent by the miniapp to notify the host app that it has completed cleanup and is ready to be closed.
-   * Note that if the miniapp takes longer than 10 seconds to close, the host app will force close the miniapp.
-   * @since 0.0.14
+   * Close the miniapp.
+   * Sent by the miniapp to request the host app to close it.
+   * Fire-and-forget — no response expected.
+   * @since 1.0.0
    * @schema
    */
-  'miniapp:close.ack': CreateMethodPayload<Empty>;
+  'app:close': CreateMethodPayload<Empty>;
   /**
    * Toggle host app's back button visibility.
-   * @since 0.0.14
+   * @since 1.0.0
    * @schema
    */
   'host.back.button:toggle': CreateMethodPayload<{
     /**
      * Whether to show or hide the back button.
-     * @since 0.0.14
+     * @since 1.0.0
      * @schema
      */
     visible: boolean;
@@ -654,8 +617,7 @@ interface Methods {
    * @schema
    */
   'wallet.solana:sign.transaction': CreateMethodPayload<WithReqId<{
-    /** Base64-encoded serialized transaction (legacy or versioned) */
-    transaction: string;
+    /** Base64-encoded serialized transaction (legacy or versioned) */transaction: string;
   }>>;
   /**
    * Request Solana message signing.
@@ -664,8 +626,7 @@ interface Methods {
    * @schema
    */
   'wallet.solana:sign.message': CreateMethodPayload<WithReqId<{
-    /** Base58-encoded message bytes */
-    message: string;
+    /** Base58-encoded message bytes */message: string;
   }>>;
   /**
    * Request Solana transaction signing and sending.
@@ -675,8 +636,7 @@ interface Methods {
    * @schema
    */
   'wallet.solana:sign.send': CreateMethodPayload<WithReqId<{
-    /** Base64-encoded serialized transaction (legacy or versioned) */
-    transaction: string;
+    /** Base64-encoded serialized transaction (legacy or versioned) */transaction: string;
     /**
      * Target Solana cluster for broadcasting.
      * In bridge mode the host app can infer this from miniapp config,
@@ -685,12 +645,10 @@ interface Methods {
      * @since 1.0.0
      * @schema
      */
-    chain?: SolanaChain;
-    /** Optional send options */
+    chain?: SolanaChain; /** Optional send options */
     options?: {
       skipPreflight?: boolean;
-      preflightCommitment?: SolanaCommitment;
-      /** Desired commitment level for transaction confirmation. */
+      preflightCommitment?: SolanaCommitment; /** Desired commitment level for transaction confirmation. */
       commitment?: SolanaCommitment;
       /**
        * The minimum slot that the request can be evaluated at.
@@ -700,33 +658,11 @@ interface Methods {
       maxRetries?: number;
     };
   }>>;
-  /**
-   * Request fullscreen mode.
-   * Fire-and-forget — host app responds with `fullscreen:changed` or `fullscreen:failed` event.
-   *
-   * @example
-   * send('fullscreen:request', {});
-   *
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:request': CreateMethodPayload<Empty>;
-  /**
-   * Exit fullscreen mode.
-   * Fire-and-forget — host app responds with `fullscreen:changed` event.
-   *
-   * @example
-   * send('fullscreen:exit', {});
-   *
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:exit': CreateMethodPayload<Empty>;
 }
 //#endregion
 //#region src/methods/types/method-types.d.ts
 type MethodName = keyof Methods;
-type MethodPayload<M$1 extends MethodName> = Methods[M$1]['payload'];
+type MethodPayload<M extends MethodName> = Methods[M]['payload'];
 /**
  * Method names which have versioned payload.
  */
@@ -734,7 +670,7 @@ type MethodNameWithVersionedPayload = { [M in MethodName]: If<IsNever<Methods[M]
 /**
  * Method payload which appear only in the specific version.
  */
-type MethodVersionedPayload<M$1 extends MethodNameWithVersionedPayload> = Methods[M$1]['versionedPayload'];
+type MethodVersionedPayload<M extends MethodNameWithVersionedPayload> = Methods[M]['versionedPayload'];
 //#endregion
 //#region src/methods/versions/get-release-version.d.ts
 /**
@@ -743,7 +679,7 @@ type MethodVersionedPayload<M$1 extends MethodNameWithVersionedPayload> = Method
  * @param method - method name
  * @param param - method parameter
  */
-declare function getReleaseVersion<M$1 extends MethodNameWithVersionedPayload>(method: M$1, payload: MethodVersionedPayload<M$1>): Version | null;
+declare function getReleaseVersion<M extends MethodNameWithVersionedPayload>(method: M, payload: MethodVersionedPayload<M>): Version | null;
 declare function getReleaseVersion(method: MethodName): Version | null;
 //#endregion
 //#region src/methods/versions/releases.d.ts
@@ -776,4 +712,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 FullscreenErrorCode, 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

@@ -87,14 +87,6 @@ type PaymentWebhookStatus = 'finalized' | 'failed';
  * @schema
  */
 type PaymentTestScenario = 'paid' | 'paid:failed' | 'cancelled' | `error:${PaymentErrorCode}`;
-/**
- * Fullscreen error codes.
- * Returned in `fullscreen:failed` event when fullscreen request fails.
- * - `ALREADY_FULLSCREEN`: Miniapp is already in fullscreen mode
- * @since 1.1.0
- * @schema
- */
-type FullscreenErrorCode = 'ALREADY_FULLSCREEN';
 /**
  * Haptic impact feedback styles.
  * Maps to UIImpactFeedbackGenerator styles on iOS
@@ -143,13 +135,9 @@ type WalletSolanaErrorCode = 5000 | -32602 | -32603 | 8000;
  * @since 1.0.0
  */
 declare const WALLET_ERROR: {
-  /** User rejected the request (cancelled approval screen). */
-  readonly USER_REJECTED: 5000;
-  /** Invalid params — transaction deserialization failed, malformed input. */
-  readonly INVALID_PARAMS: -32602;
-  /** Internal error — transaction broadcast failed, unexpected error. */
-  readonly INTERNAL_ERROR: -32603;
-  /** Request expired before the user responded. */
+  /** User rejected the request (cancelled approval screen). */readonly USER_REJECTED: 5000; /** Invalid params — transaction deserialization failed, malformed input. */
+  readonly INVALID_PARAMS: -32602; /** Internal error — transaction broadcast failed, unexpected error. */
+  readonly INTERNAL_ERROR: -32603; /** Request expired before the user responded. */
   readonly REQUEST_EXPIRED: 8000;
 };
 /**
@@ -182,15 +170,9 @@ interface CreateEventPayload<Payload = never> {
  * @schema
  */
 interface Events {
-  /**
-   * Miniapp close event, fired by the host app just before the miniapp is closed.
-   * @since 0.0.14
-   * @schema
-   */
-  'miniapp:close': CreateEventPayload<Empty>;
   /**
    * Host app's back button clicked event.
-   * @since 0.0.14
+   * @since 1.0.0
    * @schema
    */
   'host.back.button:clicked': CreateEventPayload<Empty>;
@@ -259,46 +241,14 @@ interface Events {
      */
     errorCode?: 'permission_denied' | 'unavailable';
   }>>;
-  /**
-   * Fullscreen state changed, fired by the host app
-   * after `fullscreen:request` or `fullscreen:exit`.
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:changed': CreateEventPayload<{
-    /**
-     * Whether the miniapp is currently in fullscreen mode.
-     * @since 1.1.0
-     * @schema
-     */
-    isFullscreen: boolean;
-  }>;
-  /**
-   * Fullscreen request failed.
-   * Fired by the host app when `fullscreen:request` cannot be fulfilled
-   * (e.g., the miniapp is already in fullscreen mode).
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:failed': CreateEventPayload<{
-    /**
-     * Error code indicating why the fullscreen request failed.
-     * @since 1.1.0
-     * @schema
-     */
-    error: FullscreenErrorCode;
-  }>;
   /**
    * Solana wallet connection response.
    * @since 1.0.0
    * @schema
    */
   'wallet.solana:connect.response': CreateEventPayload<WithReqId<{
-    /** Base58-encoded public key of the connected wallet */
-    publicKey?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base58-encoded public key of the connected wallet */publicKey?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
   /**
@@ -307,11 +257,8 @@ interface Events {
    * @schema
    */
   'wallet.solana:sign.transaction.response': CreateEventPayload<WithReqId<{
-    /** Base64-encoded signed transaction */
-    signedTransaction?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base64-encoded signed transaction */signedTransaction?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
   /**
@@ -320,13 +267,9 @@ interface Events {
    * @schema
    */
   'wallet.solana:sign.message.response': CreateEventPayload<WithReqId<{
-    /** Base58-encoded Ed25519 signature (64 bytes) */
-    signature?: string;
-    /** Base58-encoded public key that signed the message */
-    publicKey?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base58-encoded Ed25519 signature (64 bytes) */signature?: string; /** Base58-encoded public key that signed the message */
+    publicKey?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
   /**
@@ -335,11 +278,8 @@ interface Events {
    * @schema
    */
   'wallet.solana:sign.send.response': CreateEventPayload<WithReqId<{
-    /** Base58-encoded transaction signature */
-    signature?: string;
-    /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
-    errorCode?: WalletSolanaErrorCode;
-    /** Human-readable error description */
+    /** Base58-encoded transaction signature */signature?: string; /** Numeric error code (WalletConnect-compatible). See {@link WalletSolanaErrorCode}. */
+    errorCode?: WalletSolanaErrorCode; /** Human-readable error description */
     errorMessage?: string;
   }>>;
 }
@@ -357,6 +297,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).
@@ -387,10 +349,11 @@ interface LaunchParams {
    */
   startParam: string | undefined;
   /**
-   * Whether the miniapp was launched in fullscreen mode.
-   * @since 1.1.0
+   * 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
@@ -411,27 +374,27 @@ interface Methods {
   /**
    * Miniapp ready method.
    * Sent by the miniapp to notify the host app that it has loaded and is ready to be displayed.
-   * @since 0.0.1
+   * @since 0.0.9
    * @schema
    */
   'app:ready': CreateMethodPayload<Empty>;
   /**
-   * Miniapp close acknowledgment method.
-   * Sent by the miniapp to notify the host app that it has completed cleanup and is ready to be closed.
-   * Note that if the miniapp takes longer than 10 seconds to close, the host app will force close the miniapp.
-   * @since 0.0.14
+   * Close the miniapp.
+   * Sent by the miniapp to request the host app to close it.
+   * Fire-and-forget — no response expected.
+   * @since 1.0.0
    * @schema
    */
-  'miniapp:close.ack': CreateMethodPayload<Empty>;
+  'app:close': CreateMethodPayload<Empty>;
   /**
    * Toggle host app's back button visibility.
-   * @since 0.0.14
+   * @since 1.0.0
    * @schema
    */
   'host.back.button:toggle': CreateMethodPayload<{
     /**
      * Whether to show or hide the back button.
-     * @since 0.0.14
+     * @since 1.0.0
      * @schema
      */
     visible: boolean;
@@ -654,8 +617,7 @@ interface Methods {
    * @schema
    */
   'wallet.solana:sign.transaction': CreateMethodPayload<WithReqId<{
-    /** Base64-encoded serialized transaction (legacy or versioned) */
-    transaction: string;
+    /** Base64-encoded serialized transaction (legacy or versioned) */transaction: string;
   }>>;
   /**
    * Request Solana message signing.
@@ -664,8 +626,7 @@ interface Methods {
    * @schema
    */
   'wallet.solana:sign.message': CreateMethodPayload<WithReqId<{
-    /** Base58-encoded message bytes */
-    message: string;
+    /** Base58-encoded message bytes */message: string;
   }>>;
   /**
    * Request Solana transaction signing and sending.
@@ -675,8 +636,7 @@ interface Methods {
    * @schema
    */
   'wallet.solana:sign.send': CreateMethodPayload<WithReqId<{
-    /** Base64-encoded serialized transaction (legacy or versioned) */
-    transaction: string;
+    /** Base64-encoded serialized transaction (legacy or versioned) */transaction: string;
     /**
      * Target Solana cluster for broadcasting.
      * In bridge mode the host app can infer this from miniapp config,
@@ -685,12 +645,10 @@ interface Methods {
      * @since 1.0.0
      * @schema
      */
-    chain?: SolanaChain;
-    /** Optional send options */
+    chain?: SolanaChain; /** Optional send options */
     options?: {
       skipPreflight?: boolean;
-      preflightCommitment?: SolanaCommitment;
-      /** Desired commitment level for transaction confirmation. */
+      preflightCommitment?: SolanaCommitment; /** Desired commitment level for transaction confirmation. */
       commitment?: SolanaCommitment;
       /**
        * The minimum slot that the request can be evaluated at.
@@ -700,33 +658,11 @@ interface Methods {
       maxRetries?: number;
     };
   }>>;
-  /**
-   * Request fullscreen mode.
-   * Fire-and-forget — host app responds with `fullscreen:changed` or `fullscreen:failed` event.
-   *
-   * @example
-   * send('fullscreen:request', {});
-   *
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:request': CreateMethodPayload<Empty>;
-  /**
-   * Exit fullscreen mode.
-   * Fire-and-forget — host app responds with `fullscreen:changed` event.
-   *
-   * @example
-   * send('fullscreen:exit', {});
-   *
-   * @since 1.1.0
-   * @schema
-   */
-  'fullscreen:exit': CreateMethodPayload<Empty>;
 }
 //#endregion
 //#region src/methods/types/method-types.d.ts
 type MethodName = keyof Methods;
-type MethodPayload<M$1 extends MethodName> = Methods[M$1]['payload'];
+type MethodPayload<M extends MethodName> = Methods[M]['payload'];
 /**
  * Method names which have versioned payload.
  */
@@ -734,7 +670,7 @@ type MethodNameWithVersionedPayload = { [M in MethodName]: If<IsNever<Methods[M]
 /**
  * Method payload which appear only in the specific version.
  */
-type MethodVersionedPayload<M$1 extends MethodNameWithVersionedPayload> = Methods[M$1]['versionedPayload'];
+type MethodVersionedPayload<M extends MethodNameWithVersionedPayload> = Methods[M]['versionedPayload'];
 //#endregion
 //#region src/methods/versions/get-release-version.d.ts
 /**
@@ -743,7 +679,7 @@ type MethodVersionedPayload<M$1 extends MethodNameWithVersionedPayload> = Method
  * @param method - method name
  * @param param - method parameter
  */
-declare function getReleaseVersion<M$1 extends MethodNameWithVersionedPayload>(method: M$1, payload: MethodVersionedPayload<M$1>): Version | null;
+declare function getReleaseVersion<M extends MethodNameWithVersionedPayload>(method: M, payload: MethodVersionedPayload<M>): Version | null;
 declare function getReleaseVersion(method: MethodName): Version | null;
 //#endregion
 //#region src/methods/versions/releases.d.ts
@@ -776,4 +712,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 FullscreenErrorCode, 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,12 +3,32 @@
 * 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
 const releases = {
 	"0.0.9": ["app:ready"],
-	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"],
 	"0.1.1": [
 		"payment:request",
 		"clipboard:write",
@@ -25,11 +45,11 @@ const releases = {
 		"wallet.solana:disconnect",
 		"wallet.solana:sign.transaction",
 		"wallet.solana:sign.message",
-		"wallet.solana:sign.send"
-	],
-	"1.1.0": ["fullscreen:request", "fullscreen:exit"]
+		"wallet.solana:sign.send",
+		"app:close",
+		"host.back.button:toggle"
+	]
 };
-
 //#endregion
 //#region src/methods/versions/get-release-version.ts
 function getReleaseVersion(method, payload) {
@@ -42,7 +62,6 @@ function getReleaseVersion(method, payload) {
 		});
 	}) || null;
 }
-
 //#endregion
 //#region src/methods/versions/index.ts
 /**
@@ -89,7 +108,6 @@ function getMethodMinVersion(method) {
 		if (methods.some((m) => typeof m === "string" ? m === method : m.method === method)) return version;
 	}
 }
-
 //#endregion
 //#region src/utils.ts
 /**
@@ -112,6 +130,5 @@ const WALLET_ERROR = {
 	INTERNAL_ERROR: -32603,
 	REQUEST_EXPIRED: 8e3
 };
-
 //#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.1.1-alpha",
+  "version": "1.3.1-beta",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -36,9 +36,9 @@
     "generate-schemas": "bun run scripts/generate-schemas.ts"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.5",
-    "@types/node": "^25.0.3",
-    "tsdown": "^0.18.1",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^25.3.5",
+    "tsdown": "^0.21.0",
     "typescript-json-schema": "^0.67.1"
   },
   "peerDependencies": {