Shell & Adapters

ShellPort is the seam between framework-free UI logic and the native shell.

import { createTauriShell } from "praisonai-mobile/adapters/tauri";

const shell = createTauriShell();
shell.haptic("selection");
await shell.share({ text: "My agent's answer", title: "PraisonAI" });

Quick Start

Read the insets synchronously

const { top, bottom } = shell.insets;

First paint places the composer above the home indicator, so insets are a synchronous snapshot, never a promise.

React to the keyboard

const off = shell.onKeyboardHeightChanged((px) => layout(px));

keyboardHeightPx is also a synchronous snapshot, so a warm resume with the keyboard already up lays out correctly on mount.

readKeyboardHeight is the single source of truth

One exported function computes the keyboard height, with the clamp and the zoom guard in one place.

export function readKeyboardHeight(view: Window): number {
  const viewport = view.visualViewport;
  if (viewport === null || viewport === undefined) return 0;
  if (viewport.scale > 1) return 0;
  return Math.max(0, view.innerHeight - viewport.height - viewport.offsetTop);
}

createWebShell seeds the snapshot at construction

keyboardHeightPx is seeded, not declared = 0.

export function createWebShell(view: Window = window): WebShell {
  let keyboardHeightPx = readKeyboardHeight(view); // seeded, not 0
  // ... the live handler calls the SAME readKeyboardHeight(view)
}

What The Shell Provides

These are the capabilities a phone needs but a desktop window does not.

Capability	Member	Note
Safe area	`insets`, `onInsetsChanged`	Synchronous snapshot + change events.
Keyboard	`keyboardHeightPx`, `onKeyboardHeightChanged`	`0` when hidden; fires through the transition.
Lifecycle	`onLifecycleChanged`	Background must stop the run loop and flush.
Back gesture	`onBackGesture`	Handlers are a stack; first to return `true` wins.
Haptics	`haptic(kind)`	`selection`, `impact`, `success`, `warning`, `error`.
Sharing	`share(payload)`	Hand text/URL to the OS share sheet.
Secure links	`openExternal(url)`	Allowlisted schemes only.

The Two Adapters

Adapter	Where	Backs
`web`	`adapters/src/web`	A plain browser window; secrets are process memory.
`tauri`	`adapters/src/tauri`	The native shell; keychain-backed secrets.

Only adapters/src/tauri may import @tauri-apps/*, and inside it only bridge.ts touches them. tools/depgraph.mjs enforces this, so a React Native port is one directory rather than an audit.

How It Works

The seed at construction and the live handler read through the same function, so the clamp-at-0 and the pinch-zoom guard cannot drift between the first frame and every frame after it.

Behaviour	Result	Why
`visualViewport` missing	`0`	A desktop browser with no software keyboard reports nothing.
`visualViewport.scale > 1`	`0`	Pinch-zoom shrinks the viewport exactly as a keyboard does; a software keyboard never changes `scale`.
otherwise	`Math.max(0, innerHeight − height − offsetTop)`	The gap between the layout and visual viewports, clamped so overscroll cannot make it negative.

The keyboardHeightPx snapshot is seeded at construction, so a component mounting during a warm resume, or with a hardware or floating keyboard already up, lays out correctly on its first frame.

Pinch-zoom shrinks the visual viewport just like a keyboard does. readKeyboardHeight guards this with viewport.scale > 1. If you re-implement the shell for a different platform, replicate this guard, or a zoomed webview will push the composer up by the wrong amount.

Secure External Links

openExternal must reject any scheme the allowlist rejects. In a webview, openExternal("javascript:...") is script execution in the app’s own origin — and the URL routinely comes from a model or a tool result.

export const OPENABLE_SCHEMES = ["http", "https", "mailto", "tel", "sms", "geo", "maps"];

The allowlist lives in the port, not in one adapter, so every shell is held to it by the contract suite. Never add a blocklist instead — the set of dangerous schemes is open-ended.

The native counterpart

On desktop and web-only builds, readKeyboardHeight(view) is the entire source of the keyboard height. On iOS and Android the keyboard height, safe-area insets, lifecycle, and back-press come from the Native Shell instead — four Tauri events the webview subscribes to by string. The two are complementary, not alternatives. The web shell’s keyboardHeightPx seed still runs at construction so the first frame lays out correctly; the native keyboard-height event feeds every update after it.

Executable Specification

Four conformance tests in adapters/src/conformance/contracts.test.ts pin the snapshot and the guard:

Test	Asserts
keyboard already up at construction	seeds a non-zero height on the first frame
no keyboard	reports `0`
zoom at construction	a page opened pinch-zoomed is not mistaken for a keyboard
zoom after construction	the live path applies the same guard, not just the seed

Common Patterns

The live handler and the seed share one function, so a hide is never swallowed.

const publishKeyboard = () => {
  const height = readKeyboardHeight(view);
  keyboardHeightPx = height;
  for (const cb of keyboardSubs) cb(height);
};
viewport.addEventListener("resize", publishKeyboard);
viewport.addEventListener("scroll", publishKeyboard);

Layout reads the synchronous snapshot at mount, then subscribes for changes.

screen.style.setProperty("--keyboard-height", `${platform.shell.keyboardHeightPx}px`);
platform.shell.onKeyboardHeightChanged(applyGeometry);

Best Practices

Seed the snapshot, do not start at 0

A property declared = 0 and only updated by an event reproduces the exact bug it was added to fix: one frame at the wrong height, then a jump. Seed from readKeyboardHeight(view) at construction.

Guard pinch-zoom in every shell you write

scale > 1 separates zoom from a keyboard. A shell that omits the guard reports a phantom keyboard the moment the user zooms — most visibly at construction, on a page opened already zoomed.

Read the height through one function

Keep the clamp and the guard in a single readKeyboardHeight. Duplicating the subtraction in the seed and the handler lets the two drift apart.

Store back handlers in an array

The most recently registered handler gets first refusal. A Set has no defined order and ships a modal that closes the wrong screen.

Never let insets become NaN

parseFloat("") is NaN, and calc(100vh - NaNpx) silently blanks the screen. Every inset path coerces unparseable input to 0.

Flush on background

iOS can kill a suspended app with no further callback, so anything unflushed when onLifecycleChanged reports background is lost.

Mobile Architecture

How the shell is injected at boot.

Capabilities & Gaps

The keyboard snapshot as a closed gap.

Native Shell

The Tauri events that feed the shell on iOS and Android.

Storage & Secrets

Where chats and API keys live.

The Two Seams

How the UI-shell seam is enforced.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

What The Shell Provides

The Two Adapters

How It Works

Secure External Links

The native counterpart

Executable Specification

Common Patterns

Best Practices

Mobile Architecture

Capabilities & Gaps

Native Shell

Storage & Secrets

The Two Seams

​Quick Start

​What The Shell Provides

​The Two Adapters

​How It Works

​Secure External Links

​The native counterpart

​Executable Specification

​Common Patterns

​Best Practices

​Related

Mobile Architecture

Capabilities & Gaps

Native Shell

Storage & Secrets

The Two Seams

Quick Start

What The Shell Provides

The Two Adapters

How It Works

Secure External Links

The native counterpart

Executable Specification

Common Patterns

Best Practices

Related