Skip to content

[web] Document viewport-fit=cover SafeArea support, URL percent-encoding preservation, and clean up web overview docs for Flutter 3.50 #13962

Description

@kevmoo

Page URL

Describe the problem

Flutter 3.50 includes two web platform behavior changes (viewport-fit=cover SafeArea support and URL percent-encoding preservation) plus several outdated/broken web architecture statements on docs.flutter.dev (cc @parlough @sfshaza2):

  1. viewport-fit=cover SafeArea support & layout breaking change: In Flutter 3.50 (flutter/flutter#191647), Flutter Web respects viewport-fit=cover in <meta name="viewport"> and populates FlutterView.viewPadding / MediaQuery.paddingOf / SafeArea from CSS env(safe-area-inset-*). Existing web apps that already had viewport-fit=cover in web/index.html (previously stripped by the engine) will now render edge-to-edge under notches and home indicators unless wrapped in SafeArea.
  2. Browser history URL percent-encoding preservation: URLs passed to SystemNavigator.routeInformationUpdated are no longer percent-decoded before being written to browser history (flutter/flutter#189835), preserving %2F, %26, %23, and %20 across page refreshes.
  3. Outdated 2019 HTML renderer prose & broken [hot reload behind a flag][] link: sites/docs/src/content/platform-integration/web/index.md#L30-L41 still describes the removed Dart-implemented HTML drawing layer, and sites/docs/src/content/resources/architectural-overview.md#L1084 contains an unresolved [hot reload behind a flag][] reference link.
Detailed page breakdown & affected targets (AI-assisted)

Expected fix

1. sites/docs/src/content/deployment/web.md & sites/docs/src/content/release/breaking-changes/

  • Edge-to-edge mobile web rendering (viewport-fit=cover):
    • Document how adding viewport-fit=cover to <meta name="viewport"> in web/index.html (now included as a commented-out option in flutter create templates) enables full-bleed edge-to-edge rendering on iOS and Android browsers and populates FlutterView.viewPadding / SafeArea via CSS env(safe-area-inset-*) (flutter/flutter#191647).
    • Add a breaking-change / migration note for Flutter 3.50 warning that existing web apps that already had viewport-fit=cover in web/index.html will now render under device cutouts/notches unless UI content is wrapped in SafeArea (or viewport-fit=cover is removed).
  • Browser history percent-encoding:
    • Note that BrowserHistory no longer calls Uri.decodeComponent on URLs passed to SystemNavigator.routeInformationUpdated (flutter/flutter#189835), preventing loss of percent-encoded delimiters (%2F, %26, %23, %20) in route paths and query parameters.

2. sites/docs/src/content/platform-integration/web/index.md (https://docs.flutter.dev/platform-integration/web)

  • Rewrite ## How it works (L30-L41) to remove 2019 HTML-renderer prose ("We implemented the core drawing layer completely in Dart and used Dart's optimized JavaScript compiler...") and accurately describe compilation to JavaScript (dart2js / ddc) or WebAssembly (dart2wasm) paired with hardware-accelerated WebGL/WebGPU rendering via CanvasKit and Skwasm.

3. sites/docs/src/content/resources/architectural-overview.md (https://docs.flutter.dev/resources/architectural-overview)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    a.rn.breaking-changesRelates to breaking changes on a Flutter releasea.rn.release-notesRelates to Flutter release notes found on docs.flutter.devd.enhancementImproves docs with specific askdev.deploymentRelates to deploying Flutter app section of Flutter.devdev.integrationRelates to platform integratione1-hoursEffort: < 8 hrsfrom.teamReported by Dash docs team memberp1-highMajor but not urgent concern: Resolve in months. Update each month.target.webTarget apps on the web platform

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions