Fix Cross-Platform Default Output Directory Handling - Android

[ChikithRishi]

Fix Cross-Platform Default Output Directory Handling

Description

Hyperkey currently uses Flet's StoragePaths().get_downloads_directory() for the Android default output location.

In the packaged Android app, this resolves to an app-specific location:

/storage/emulated/0/Android/data/com.flet.hyperkey/files/Download/Hyperkey/

instead of a normal user-accessible shared folder.

Custom output folders selected through Android's folder picker work correctly.

Why This Happens on Android

Modern Android uses scoped storage, which restricts applications from freely accessing arbitrary locations in shared internal storage.

Hyperkey currently asks Flet for the Downloads directory using:

StoragePaths().get_downloads_directory()

However, in the packaged Android application, Flet resolves this to Hyperkey's app-specific external storage directory, rather than the user's normal public Documents or Download folder.

Therefore, a request for the default Downloads location can result in:

/storage/emulated/0/Android/data/com.flet.hyperkey/files/Download/

rather than:

/storage/emulated/0/Download/

This is different from Windows, macOS, and Linux, where the application can normally construct a user-level Documents/Hyperkey directory without Android's scoped-storage restrictions.

Why the Folder Picker Works

When the user manually selects a folder using Android's system folder picker, Android treats this as an explicit user choice.

For example, selecting:

Internal Storage/Documents/Hyperkey/

allows Hyperkey to receive and use the location selected by the user.

This is why custom output directories already work correctly, while automatically resolving the public Android directory through Flet does not.

Why We Cannot Simply Use the Existing Flet Default

The existing Flet API does not provide Hyperkey with the public shared-storage Documents/Hyperkey location required for this use case.

Using:

StoragePaths().get_downloads_directory()

has already been tested in the packaged Android application and resolves to the app-specific Android/data/... location.

Therefore, continuing to use this API would leave generated results in a location that is not convenient for users to browse later through their normal file manager.

There is also no simple Flet option such as a public=True setting that changes this call into the public Android Documents directory.

Why We Are Not Hardcoding the Android Path

A possible workaround would be to directly use:

/storage/emulated/0/Documents/Hyperkey/

However, this should not be hardcoded.

/storage/emulated/0/ is a commonly used Android internal-storage path, but Hyperkey should not assume that every Android device, Android user/profile, storage configuration, or future Android version exposes shared storage using exactly that filesystem path.

Hardcoding it would make the application dependent on a device-specific filesystem implementation rather than Android's storage APIs.

It could therefore work on the development/test device while failing or behaving differently for another user.

Proposed Workaround

Instead of attempting to automatically construct the Android filesystem path, Hyperkey will use Android's folder picker once.

On the first run, the user will be guided to select the recommended location:

Internal Storage/Documents/Hyperkey/

Hyperkey will then remember the actual path returned by Android and automatically reuse it for subsequent runs.

The application therefore does not need to assume that:

Internal Storage = /storage/emulated/0/

The displayed location is a recommendation to the user; the actual filesystem location used by Hyperkey comes from the Android folder selection.

Impact

Although users can still open or share generated files directly from Hyperkey after a run, the current Android default location is inside the app-specific Android/data/... directory.

This means the current Open/Share functionality solves access to the files from the current run, but it does not fully solve long-term output management.

Users need to be able to leave Hyperkey, open their normal file manager later, and return to outputs generated during previous runs.

Being able to retain, browse, compare, manage, and reuse results from previous Hyperkey runs is a core purpose of Hyperkey's output storage.

Therefore, the default outputs should be placed in a persistent and easily user-accessible location.

Expected Behaviour

• Windows: Documents/Hyperkey/
• macOS: Documents/Hyperkey/
• Linux: Documents/Hyperkey/
• Android: Internal Storage/Documents/Hyperkey/ (recommended)

Windows, macOS, and Linux can use their normal user Documents directory automatically.

Android requires a different approach because of its scoped-storage model.

Android Behaviour

• On first use, prompt the user to select an output directory.

• Clearly recommend:

  Internal Storage/Documents/Hyperkey/

• Store the directory selected by the user.

• Automatically reuse the saved directory for future runs.

• Do not show the folder picker again during normal use once a valid location has been selected.

• If the user manually selects another output folder, update the remembered location.

• Continue allowing users to choose any custom output directory when required.

• Apply the same output-directory behaviour to both the normal UI and Advanced CLI execution.

• Do not hardcode /storage/emulated/0/....

Required Changes

• Remove the Android dependency on StoragePaths().get_downloads_directory() for determining the default Hyperkey output directory.
• Add persistent storage for the Android directory selected by the user.
• Add a common Android output-directory resolver:
  • use the current/custom directory when supplied;
  • otherwise use the previously remembered directory;
  • if no directory has been saved yet, launch the folder picker.
• Save a newly selected Android output directory so it becomes the location used for future runs.
• Apply the same resolver to normal UI execution and Advanced CLI execution.
• Add macOS default output handling for Documents/Hyperkey/.
• Add Linux default output handling for Documents/Hyperkey/.
• Keep Windows default output handling as Documents/Hyperkey/.
• Keep custom output directory support on every platform.
• Remove duplicated Android default-output resolution currently present in the run paths.

UI Guidance

Update the output directory hint to:

Windows/macOS/Linux: Documents/Hyperkey

Android: Select once. Recommended standard path: Internal Storage/Documents/Hyperkey/

The Android folder picker should also clearly indicate that the user is selecting Hyperkey's persistent output folder.

Cross-Platform Output Policy

The final intended behaviour is:

Windows
→ Documents/Hyperkey/
→ Automatically created/resolved

macOS
→ Documents/Hyperkey/
→ Automatically created/resolved

Linux
→ Documents/Hyperkey/
→ Automatically created/resolved

Android
→ Recommend Internal Storage/Documents/Hyperkey/
→ User selects once
→ Hyperkey remembers the selected location
→ Automatically reused for subsequent runs

Goal

Provide a consistent cross-platform output-storage policy while respecting the storage model of each operating system.

Generated Hyperkey results should remain easily accessible after the application is closed so users can return to previous runs, inspect and compare results, move files, or use them with other applications.

The solution should avoid both Android's inaccessible app-specific default directory and unreliable hardcoded shared-storage paths.

[ChikithRishi]

@mdchia

[ChikithRishi]