feat(build): Flatpak distribution target as secondary packaging format

[yandy-r]

Migrated from issue yandy-r/crosshook#69
Originally opened by @yandy-r on 2026-03-26T16:24:30Z
Original state: open

---

Problem / Use Case

Flatpak has become the dominant universal Linux packaging format. While AppImage is correct for CrossHook's deep filesystem access needs, a Flatpak target would improve discoverability via Flathub and support immutable distros.

Proposed Solution

• Create a Flatpak manifest for CrossHook
• Test sandbox compatibility with Steam path access, Proton execution, and trainer staging
• Ensure FUSE dependency is documented for AppImage on immutable distros
• Evaluate Flatpak portal access for the required filesystem interactions

Research Context

• Priority: P3 | Support: 3/8 | Effort: High | Readiness: None
• Note: AppImage remains the primary format; Flatpak sandboxing may conflict with CrossHook's needs
• Research source: docs/research/additional-features/deep-research-report.md

Acceptance Criteria

• Flatpak manifest exists and builds successfully
• Core launch workflows function within Flatpak sandbox
• Steam path access works through Flatpak portals
• Documentation covers both AppImage and Flatpak installation

Storage strategy

• TOML settings should remain the home for any user-editable Flatpak-specific defaults or packaging preferences.
• SQLite metadata should hold any persisted operational snapshots, probe caches, or migration bookkeeping that becomes necessary for sandbox support.
• Runtime-only state should cover launch/session checks, portal handles, and build/submission artifacts; packaging should not invent a parallel persistence layer.

Persistence & usability

• Flatpak support must preserve CrossHook's TOML settings and metadata DB split instead of introducing browser-only or package-specific storage.
• Any migration or isolation work should be captured in child implementation issues such as #212, not hidden inside the packaging target itself.

Code maintainability

• Keep Flatpak-specific behavior behind shared platform and packaging abstractions in crosshook-core rather than duplicating AppImage logic.
• Keep src-tauri and packaging manifests thin; core launch and storage decisions should stay reusable across packaging formats.
• Split packaging helpers, validation scripts, and docs into focused files instead of building one large Flatpak-only implementation surface.

Scope boundaries / Non-goals

• AppImage remains the primary packaging format; Flatpak is a secondary target.
• Do not solve this by bundling host tools or by forking core launch logic into a Flatpak-only product variant.

[yandy-r]

Original comment by @yandy-r on 2026-04-10T14:06:34Z

---

Implementation Tracking

PRD complete: docs/prps/prds/flatpak-distribution.prd.md

Phase Trackers

• [Tracking]: Flatpak Phase 1 — Build Infrastructure (MVP) #207 — Phase 1: Build Infrastructure (MVP) — manifest, packaging artifacts, build script, platform detection
• [Tracking]: Flatpak Phase 2 — CI Integration #208 — Phase 2: CI Integration — automated Flatpak builds in release pipeline
• [Tracking]: Flatpak Phase 3 — Process Execution Hardening #209 — Phase 3: Process Execution Hardening — host command abstraction, helper scripts, system Proton discovery
• [Tracking]: Flatpak Phase 4 — Flathub Submission #210 — Phase 4: Flathub Submission — screenshots, OARS, build-from-source manifest, Flathub PR

Key Decisions (from PRD)

• App ID: io.github.yandy_r.CrossHook (Flathub-compliant, no domain needed)
• Permissions: --filesystem=home + /mnt + /run/media + /media (Lutris precedent)
• Process execution: Centralized flatpak-spawn --host wrapping via platform::host_command()
• Success metric: ≥10% of downloads shift to Flatpak within 2 release cycles