# Flatpak packaging

Builds a portable `sunstone.flatpak` bundle you can install on any distro with
Flatpak + the GNOME 49 runtime.

## Build a test bundle

Prereqs (one-time):

```sh
flatpak install --user flathub org.flatpak.Builder \
  org.gnome.Platform//49 org.gnome.Sdk//49 \
  org.freedesktop.Sdk.Extension.rust-stable//25.08
```

Commit your changes (the manifest builds from git HEAD), then from the repo root:

```sh
flatpak run org.flatpak.Builder --force-clean --user --install \
  --install-deps-from=flathub \
  build-dir packaging/dev.sunstone.Sunstone.yaml
```

Run it:

```sh
flatpak run dev.sunstone.Sunstone
```

## Make a single-file bundle to copy to another machine

```sh
flatpak build-bundle ~/.local/share/flatpak/repo \
  sunstone.flatpak dev.sunstone.Sunstone --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo
```

On the target distro:

```sh
flatpak install --user sunstone.flatpak
flatpak run dev.sunstone.Sunstone
```

(The target needs the GNOME 49 runtime; `flatpak install` will pull it from
Flathub automatically if the repo is configured.)

## Notes / caveats

- **This is a dev bundle, not Flathub-ready.** The manifest uses
  `--share=network` at build time so cargo can fetch crates. Flathub requires
  fully-offline builds: generate `cargo-sources.json` with
  [`flatpak-cargo-generator.py`](https://github.com/flatpak/flatpak-builder-tools/tree/master/cargo)
  from `Cargo.lock`, add it as a source, drop the network build-arg, and run
  `cargo build --offline`.
- The player requires GStreamer's `gtk4paintablesink`. If a stream/video fails
  to open inside the sandbox, the GNOME runtime is missing that element and we
  need to add `gst-plugin-gtk4` as a build module.
- Hardware video decode is intentionally disabled in-app on Intel GPUs
  (`SUNSTONE_HW_DECODE=1` to opt back in); software decode runs everywhere.