fix(build): honor [tool.flet.app].hide_window_on_start in Windows runner (#6562)

* fix(build): honor [tool.flet.app].hide_window_on_start in Windows runner

The packaged Windows app showed its window on startup even when
`hide_window_on_start = true` was set in pyproject.toml. The Dart-side
`setupDesktop()` correctly skipped its own `windowManager.show()`, but
the native Win32 runner (flutter_window.cpp) only consulted the
`FLET_HIDE_WINDOW_ON_START` env var and unconditionally called `Show()`
on the first frame, so the pyproject toggle had no effect.

Templatize the runner with the same `tool.flet.<platform>.app.hide_window_on_start`
/ `tool.flet.app.hide_window_on_start` lookup already used by main.dart,
and OR the baked-in value with the env-var check so either source hides
the window at startup.

* docs(linux): document build prerequisites and Wayland window positioning

Add a Prerequisites section listing the apt packages required to build Flet
Linux apps (matching linux_deps.py), noting that lld is required and that the
GStreamer/mpv packages are for the Audio service and Video control.

Also document that programmatic window positioning (Page.window.center(),
left/top, move) is a no-op on Wayland (compositor-controlled) and works on
X11/XWayland, with the GDK_BACKEND=x11 workaround.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FeodorFitsner

sdk/python/templates/build/{{cookiecutter.out_dir}}/windows/runner/flutter_window.cpp

@@ -1,3 +1,5 @@
+{%- set hide_window_on_start = get_pyproject("tool.flet." ~ cookiecutter.options.config_platform ~ ".app.hide_window_on_start")
+                        or get_pyproject("tool.flet.app.hide_window_on_start") -%}
 #include "flutter_window.h"
 
 #include <optional>
@@ -29,6 +31,7 @@ bool FlutterWindow::OnCreate() {
   SetChildContent(flutter_controller_->view()->GetNativeWindow());
 
   const bool hide_window_on_start =
+      {{ "true" if hide_window_on_start else "false" }} ||
       HasEnvironmentVariable(L"FLET_HIDE_WINDOW_ON_START");
   flutter_controller_->engine()->SetNextFrameCallback([this,
                                                        hide_window_on_start]() {

website/docs/publish/linux.md

@@ -9,10 +9,89 @@ This guide provides detailed Linux-specific information.
 Complementary and more general information is available [here](index.md).
 :::
 
+## Prerequisites
+
+Flet uses [Flutter](https://flutter.dev) to build Linux apps. Compiling the app
+and its native plugins links against GTK and a number of system libraries, so
+these must be installed before running `flet build linux`.
+
+On Debian/Ubuntu-based distributions, install the required packages with `apt`:
+
+```bash
+sudo apt update
+sudo apt install -y \
+  binutils clang cmake llvm lld ninja-build pkg-config \
+  libgtk-3-dev libsecret-1-0 libsecret-1-dev libunwind-dev \
+  gstreamer1.0-alsa gstreamer1.0-gl gstreamer1.0-gtk3 gstreamer1.0-libav \
+  gstreamer1.0-plugins-bad gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
+  gstreamer1.0-plugins-ugly gstreamer1.0-pulseaudio gstreamer1.0-qt5 \
+  gstreamer1.0-tools gstreamer1.0-x \
+  libasound2-dev libgstreamer1.0-dev \
+  libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev \
+  libmpv-dev mpv
+```
+
+This is the same set of packages Flet uses in its own build environment. A few
+notes on what they are for:
+
+- **Build toolchain** — `clang`, `cmake`, `ninja-build`, `pkg-config`, `llvm`,
+  `lld`, `binutils` and `libgtk-3-dev` are required to compile and link the app.
+  In particular, the `lld` linker must be present — without it the build fails
+  with a linker error.
+- **Secret storage** — `libsecret-1-0` and `libsecret-1-dev` are used for secure
+  storage / keyring access.
+- **Audio and video** — the `gstreamer1.0-*`, `libgstreamer*-dev`,
+  `libasound2-dev`, `libmpv-dev` and `mpv` packages are required by the
+  [`Audio`](../services/audio/index.md#usage) service and
+  [`Video`](../controls/video/index.md#linux) control. You can omit them if your
+  app does not play media, but installing the full set above avoids surprises.
+  See those pages for control-specific details.
+
+:::note[Other distributions]
+Package names differ on non-Debian distributions (e.g. Fedora, Arch). Install
+the equivalent GTK 3, GStreamer, `mpv`/`libmpv`, `libsecret`, `clang`/`llvm`,
+`lld`, `cmake` and `ninja` development packages for your distribution.
+:::
+
 ## `flet build linux`
 
 :::note[Note]
 This command can be run on **Linux only** (or [WSL](https://docs.microsoft.com/en-us/windows/wsl/about)).
 :::
 
 Builds a Linux executable.
+
+## Window positioning on Wayland
+
+On Linux the **display server** controls window placement, and this differs
+between X11 and Wayland:
+
+- **X11** lets applications set their own top-level window position.
+- **Wayland** (the default session on modern GNOME/Ubuntu) does **not** — by
+  design, a client cannot position its own top-level window; the compositor
+  (e.g. Mutter) decides where windows are placed.
+
+As a result, on a Wayland session the following have **no effect** (window
+*sizing* still works — only positioning is restricted):
+
+- [`Page.window.center()`](../types/window.md)
+- setting [`Page.window.left`](../types/window.md) / `Page.window.top`
+- moving the window programmatically
+
+This is a Wayland protocol limitation, not a Flet bug. The same code works as
+expected on Windows, macOS, Linux X11 sessions, and Wayland sessions running the
+app through **XWayland**.
+
+To force the X11 backend (XWayland) on a Wayland session and re-enable
+programmatic positioning, run the app with the `GDK_BACKEND` environment
+variable:
+
+```bash
+GDK_BACKEND=x11 ./your_app
+```
+
+You can check the current session type with:
+
+```bash
+echo $XDG_SESSION_TYPE   # "wayland" or "x11"
+```