tai/research/tui-framework-design/mini-apps-docs-viewport.md

Mini Apps SDK docs — viewport, safe areas, fullscreen

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	tui-framework-design
Document type	Source Dossier
Tier	1
Source title	Viewport documentation (Telegram Mini Apps SDK docs)
Source URL	https://docs.telegram-mini-apps.com/platform/viewport
Source publisher / author	Telegram Mini Apps community (docs.telegram-mini-apps.com, over the official protocol)
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-11
Researched by	tai (agent), model: Muse Spark, on behalf of retoor
Research method	direct page fetch
Confidence	Medium
Status	Active

Summary

Community SDK documentation for the Mini App viewport: mobile apps open in a draggable bottom sheet, fullscreen removes the top and bottom bars, layout must pad for both the device safe area and Telegram's content safe area, and bottom-pinned UI must use the animation-stable height.

Key findings

• Mobile Mini Apps open in a draggable BottomSheet; fullscreen mode removes the top and bottom bars.
• Layout must pad for both safeAreaInset (notch, system navigation) and contentSafeAreaInset (Telegram's own chrome), especially in fullscreen.
• Bottom-pinned UI must use viewportStableHeight; viewportHeight is animation-unsafe.
• Apps must subscribe to viewportChanged, safeAreaChanged, and contentSafeAreaChanged rather than caching geometry.
• The design baseline is mobile-first at 320-480px widths.

Pros / strengths

• The only source found that separates the two insets (device vs Telegram chrome) with concrete padding guidance.
• The stable-vs-live height distinction is an exact implementable rule for bottom-pinned elements.

Cons / limitations / caveats

• Community docs over the official protocol; mobile-centric, with desktop viewport behavior thin.
• Pixel and sheet metaphors do not transfer literally to a terminal; only the inset/rounding principles carry over.

Relevance to tai

Supplies the chrome-padding discipline tai's scenes should mirror (reserve space for frame chrome, never draw under it, re-read geometry on resize events) and the stable-height rule behind tai's bottom-pinned status line.

Changelog

Date	Change
2026-10-11	Initial dossier created.