fix(flet pack): Windows taskbar identity of packaged apps

[ndonkoHenri]

Fixes the long-standing Windows issue where apps packaged with flet pack show a second taskbar identity named "Flet description", whose right-click entry and pin launch a blank Flet client window instead of the app. Reported in #6767 (and effectively what #6403 / #6421 attempted to fix).

Three independent defects stacked up:

1. The AUMID fix from fix(flet pack): Windows taskbar shortcut pointing to wrong .exe #6403 never shipped. It lives in a PyInstaller runtime hook that PyInstaller discovers through rthooks.dat — a plain data file that was silently missing from the flet-cli wheel (no package-data declaration; PyInstaller ignores a missing rthooks.dat without any warning). The fix only ever worked from editable installs, which is how it passed verification back then. The wheel now ships it.

2. A process-level AppUserModelID only fixes taskbar grouping. The taskbar name, icon, and pin target resolve through the shell's relaunch properties, and with none set they fall back to the window's process image: the cached flet.exe. (What looked like the raw-path AUMID working in earlier testing was residue in Windows' app-resolver cache from prior experiments — the same trap that made feat(flet-map): add image overlay support #6421 appear verified. Windows persists AUMID→relaunch associations across unpin and Explorer restarts, so any taskbar-identity claim must be tested from a never-used path.) flet_desktop now stamps System.AppUserModel.ID / RelaunchCommand / RelaunchDisplayNameResource / RelaunchIconResource on the client window right after launch — new flet_desktop/win_taskbar.py, pure ctypes, no new dependencies. The window is matched by its FLUTTER_RUNNER_WIN32_WINDOW class (not visibility), so hidden-start apps (AppView.FLET_APP_HIDDEN) are stamped immediately too, and the stamping worker holds a SYNCHRONIZE process handle so it stops when the client exits and a recycled PID can never be stamped. Values come from env vars set by the runtime hook (FLET_APP_RELAUNCH_*, documented as Windows-desktop-only), so packaging by other means (e.g. Nuitka) gets the same behavior by setting FLET_APP_USER_MODEL_ID manually.

3. ~/.flet/client cache collisions. The cache was keyed by flavor+version only, and ensure_client_cached() returns any existing dir untouched — so the pack-patched client (custom icon/metadata) and the vanilla client of the same version silently shadowed each other. Bundled archives are now content-fingerprinted: flet pack writes a <archive>.sha256 sidecar (<hash> <size>; the size check detects a stale sidecar next to a replaced archive), and the cache dir is keyed by that fingerprint. To keep the cache bounded: archives are built deterministically (fixed timestamps, sorted entries) so unchanged rebuilds reuse the same fingerprint, superseded fingerprint dirs unused for 30 days are garbage-collected with a rename-before-delete guard (a running app's client can never be half-deleted), and concurrent first-run extractions no longer crash the losing process.

Verified end-to-end on a Windows 11 VM with packed apps run from fresh paths: single taskbar entry, correct right-click name and icon, pins that relaunch the packaged app — including paths with spaces, paths longer than 128 characters (the window property store accepts what SetCurrentProcessExplicitAppUserModelID documents as invalid), and FLET_APP_HIDDEN apps that show their window seconds after launch.

Fixes #6767

Test code

import flet as ft


def main(page: ft.Page):
    page.title = "TaskbarTest"
    page.add(ft.Text("Hello taskbar"))


ft.run(main)

How to test (reviewers)

Needs a Windows 10/11 machine. Two iron rules, both of which have produced false verdicts on this bug before:

1. Run every packed exe from a fresh, never-used folder (C:\t1, C:\t2, …). Windows' app-resolver cache permanently remembers taskbar identity per AUMID — a folder that ever showed the correct identity keeps showing it forever, even for a broken build.
2. Test from built wheels, not a repo checkout. Half of this fix is wheel packaging (rthooks.dat); pip install -e / running from source always has the file and false-passes.

Phase A — reproduce with released Flet (baseline):

Remove-Item -Recurse -Force $env:USERPROFILE\.flet\client -ErrorAction SilentlyContinue
python -m venv venv-a; venv-a\Scripts\Activate.ps1
pip install "flet[all]==0.86.5" pyinstaller
flet pack main.py --name TaskbarTest --product-name TaskbarTest --file-description "Taskbar Test App" --yes
mkdir C:\t1; copy dist\TaskbarTest.exe C:\t1\; C:\t1\TaskbarTest.exe

Expected (bug): right-clicking the taskbar icon shows "Flet description"; pin it, close the app, click the pin → a blank "Flet" window opens instead of the app.

Phase B — the fix: download the flet-cli-desktop-python-distribution artifact from this PR's CI run and unzip it, then:

Remove-Item -Recurse -Force $env:USERPROFILE\.flet\client
python -m venv venv-b; venv-b\Scripts\Activate.ps1
pip install "flet[all]==0.86.5" pyinstaller
pip install --force-reinstall --no-deps path\to\flet_cli-*.whl path\to\flet_desktop-*.whl
$env:FLET_CLIENT_URL = "https://github.com/flet-dev/flet/releases/download/v0.86.5/flet-windows.zip"
flet pack main.py --name TaskbarTest --product-name TaskbarTest --file-description "Taskbar Test App" --yes
mkdir C:\t2; copy dist\TaskbarTest.exe C:\t2\; C:\t2\TaskbarTest.exe

(FLET_CLIENT_URL is needed only in the packing venv: the PR-built flet-desktop wheel carries a dev version with no matching client release. This PR changes no client code, so the released v0.86.5 client is the correct pairing.)

Expected (fixed): pack output includes Including run-time hook 'pyi_rth_localhost_fletd.py' (absent in Phase A); right-click shows TaskbarTest; the pin relaunches the actual app; %USERPROFILE%\.flet\client contains a fingerprint-suffixed directory.

Optional extras: repeat Phase B's run for an AppView.FLET_APP_HIDDEN app that shows its window after a delay — pre-fix, hidden apps could never be stamped.

Additional details

• An adversarial multi-agent review of the diff confirmed and led to fixes for six issues (hidden-window stamping, PID-reuse safety, stale fingerprint sidecars, fingerprint churn, cache growth, extraction races); seven other candidate findings were refuted on verification.
• Not in scope: setting the same window properties natively in the client's main.cpp (would close the sub-second window between window creation and stamping — optional future polish); renaming the client's placeholder FileDescription ("Flet description") in Runner.rc; the bare client process lingering after its blank window is closed (pre-existing, unreachable in normal use once this fix is in).

Summary by Sourcery

Fix Windows taskbar identity and client-cache isolation for applications packaged with flet pack.

Bug Fixes:

• Fix Windows apps packaged with flet pack so they use the packaged executable’s taskbar name, icon, grouping, and pin relaunch behavior instead of a duplicate generic Flet identity.
• Prevent packaged and vanilla desktop clients with the same version from colliding in the shared client cache.

Enhancements:

• Make packaged client archives deterministic and content-fingerprinted, with stale-cache cleanup and safe concurrent extraction.

Build:

• Include PyInstaller runtime hook manifests and hook files in the flet-cli wheel so packaged applications receive the Windows taskbar configuration.

Documentation:

• Document the Windows-only taskbar relaunch environment variables and how to configure them for alternative packaging tools.

Chores:

• Remove the 1.0.0 release announcement link from the release-notes index.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[cloudflare-workers-and-pages]

Deploying flet-website-v2 with    Cloudflare Pages

Latest commit:	e302817
Status:	🚫  Build failed.

View logs

[Copilot]

Pull request overview

This PR fixes Windows taskbar/pinning identity for apps packaged with flet pack by ensuring the PyInstaller runtime hook is shipped in the flet-cli wheel, stamping Windows relaunch properties on the desktop client window, and preventing patched bundled clients from colliding in the shared ~/.flet/client cache.

Changes:

• Ship PyInstaller runtime hook manifests/files in the flet-cli wheel and extend the runtime hook to set relaunch env vars on Windows.
• Add Windows window-property stamping (System.AppUserModel.*) in flet-desktop and invoke it after launching the client.
• Make bundled client archives deterministic + fingerprinted, key cache dirs by fingerprint, add stale-cache GC and extraction race handling.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
website/docs/reference/environment-variables.md	Documents new Windows relaunch environment variables and clarifies FLET_APP_USER_MODEL_ID.
sdk/python/packages/flet-desktop/src/flet_desktop/win_taskbar.py	New ctypes-based Windows taskbar relaunch-property stamping helper.
sdk/python/packages/flet-desktop/src/flet_desktop/init.py	Fingerprinted client cache dirs, GC of stale fingerprint dirs, extraction race handling, and taskbar prop application after launch.
sdk/python/packages/flet-cli/src/flet_cli/commands/pack.py	Deterministic client archive creation and writing <archive>.sha256 sidecars; preserve sidecar during macOS cleanup.
sdk/python/packages/flet-cli/src/flet_cli/__pyinstaller/utils.py	Adds tar entry normalization helper for deterministic tars.
sdk/python/packages/flet-cli/src/flet_cli/__pyinstaller/rthooks/pyi_rth_localhost_fletd.py	Sets Windows relaunch env vars alongside FLET_APP_USER_MODEL_ID.
sdk/python/packages/flet-cli/src/flet_cli/__pyinstaller/macos_utils.py	Makes macOS tar creation deterministic (fixed gzip mtime + normalized tar entries).
sdk/python/packages/flet-cli/pyproject.toml	Includes rthooks.dat and runtime hook files in wheel package data.
CHANGELOG.md	Adds release notes for the Windows taskbar fix and the fingerprinted client-cache fix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.