53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# 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. |
|