Spec — App safe-area / window-insets handling

Applicability

All Koder apps (mobile, desktop, TV, web PWA) — any surface where system chrome (status bar, navigation bar, display cutout, on-screen keyboard, title bar, task bar) can occlude rendered content.

Not applicable to CLIs, landing pages (static HTML with normal document flow), or pure server components.

Required behaviour

1. Always consume OS-reported insets. The OS knows the exact pixel dimensions of system chrome on the current device and updates them live (orientation change, gesture nav vs 3-button, keyboard open/close, foldable unfold, PiP resize). Apps must consume these values — never hard-code pixel margins.
2. No content occluded by system chrome at rest. Every interactive element — buttons, text fields, list items, sliders — must be fully tappable without fighting the nav bar, status bar, or cutout.
3. Text under the status bar is forbidden unless the design is deliberately edge-to-edge (splash screen, full-screen video, camera viewfinder) and the content is non-critical.
4. IME (on-screen keyboard) handling. Forms must resize or scroll so the focused field stays visible above the keyboard. Default to resizeToAvoidBottomInset: true (Flutter) / WindowInsets.ime (native Android) / keyboardShouldPersistTaps='handled' (Web).
5. Edge-to-edge on Android 15+ is the platform default. Apps targeting API ≥ 35 must handle insets explicitly; the OS no longer adds automatic padding.

Platform primitives

SDK widgets (approved implementations)

Apps must use the SDK-provided widget where available instead of re-implementing per edge. Using the SDK is the spec's deterministic compliance test.

Native Android Kotlin — inline pattern

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            KoderEyeTheme(...) {
                Surface(modifier = Modifier.fillMaxSize(), ...) {
                    Column(
                        modifier = Modifier
                            .fillMaxSize()
                            .safeDrawingPadding()     // ← consume all insets
                            .verticalScroll(...)
                            .padding(16.dp)
                    ) { ... }
                }
            }
        }
    }
}

Edge-to-edge opt-out (rare)

Apps with genuine edge-to-edge content (video players, splash screens, maps) pass safeArea: false on KoderApp and handle individual edges per screen — e.g. keep the video surface under the status bar but consume bottomPadding for playback controls.

Deterministic audit checks

/k-housekeep audit (ticket engines/sdk/koder_kit#003) grep-verifies:

1. Every Flutter app with koder_kit in pubspec.yaml imports KoderApp.
2. Every Scaffold(body: …) at the app entry point uses either SafeArea or KoderSafeScaffold. A raw Column / ListView / Stack at body: position triggers a warning.
3. Every landing / web app that ships koder-web-kit.js also references koder-web-kit.css (or equivalent providing --pad-top vars).
4. KoderApp(safeArea: false) presence triggers an info-level annotation: "edge-to-edge opt-in — verify manually that insets are consumed per screen".

Rationale

This spec exists because the pattern is rediscovered per-app, forgotten in half of them, and leads to clipped UI that is only caught in screenshot review. Encapsulating it in the SDK reduces the cost from every app re-reads this spec to every app imports one symbol, and the audit makes compliance verifiable without human review. See engines/sdk/koder_kit/docs/rfcs/RFC-001-spec-encapsulation-across-platforms.md §2.1 for the AI-token-savings argument.

Canonical reference

engines/sdk/koder_kit/lib/src/safe_scaffold.dart — Flutter reference. products/dev/eye/app/android/app/src/main/kotlin/dev/koder/eye/MainActivity.kt — native Kotlin reference pattern.

Related specs

• ../themes/light-dark.kmd — companion cross-cutting UI spec
• ../koder-app/behaviors.kmd — parent behaviors spec