Release: FreeBSD, Flatpak (x86_64 + aarch64) and AppImage zsync; README Downloads (#267)

- release.yml: new `flatpak` jobs (x86_64 on ubuntu-24.04, aarch64 on ubuntu-24.04-arm) that repackage the Linux tarball as filmcraft-<v>-linux-<arch>.flatpak, and a `freebsd` job that builds filmcraft-<v>-freebsd-x86_64.tar.gz in a FreeBSD 14.3 VM; both feed the draft release. - AppImages embed gh-releases-zsync update information and ship a .zsync beside them; the Linux job checks both. - Jobs that sign nothing (version, Linux, Flatpak, FreeBSD, web) no longer use the `release` environment, so a dispatch on a branch dry-runs them; the signing jobs and the draft-release job stay in the environment, so nothing is published from a branch. - packaging/linux/flatpak-bundle.sh + bundle manifest (same runtime and finish-args as the Flathub manifest; packaging-lint checks they agree), packaging/freebsd/package.sh (with a --dry-run that packaging-lint runs), and a nightly FreeBSD build workflow. - README: Downloads section listing every build; docs/releasing.md updated. Co-authored-by: Brandon Thomas <[email protected]> Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-10-14 11:17:01 -04:00 · 2026-10-08 09:41:42 -04:00
1 parent 08735f3103
commit 86a531ad22
@@ -0,0 +1,58 @@
+# Builds FilmCraft on FreeBSD, inside a FreeBSD VM on a Linux runner (GitHub has no FreeBSD
+# runners), then runs packaging/freebsd/package.sh, the script the release job runs, and checks
+# the tarball. A broken FreeBSD build or package fails here before it can fail a release. Nothing
+# is uploaded and no secrets are used. (The test suite isn't run here yet: the ffmpeg-oracle and
+# golden-image tests need tools and a GPU the VM doesn't have.)
+name: FreeBSD
+
+# The VM build takes an hour or more, so it runs nightly on main rather than on every push or
+# dependency change: a drifted dependency still shows up within a day. PRs that change the
+# FreeBSD packaging itself still run it.
+on:
+  schedule:
+    - cron: "37 2 * * *"
+  pull_request:
+    paths:
+      - .github/workflows/freebsd.yml
+      - packaging/freebsd/**
+      - packaging/env.sh
+  workflow_dispatch:
+
+concurrency:
+  group: freebsd-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  freebsd:
+    name: FreeBSD 14 (build + package)
+    runs-on: ubuntu-latest
+    timeout-minutes: 240
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build and package in a FreeBSD VM
+        # vmactions/freebsd-vm v1.5.9, pinned by commit (it runs our build).
+        uses: vmactions/freebsd-vm@c46abacb49f09938ca4e1702d15d836285d694cc
+        with:
+          release: "14.3"
+          usesh: true
+          cpu: 4
+          mem: 12288
+          # Nothing to bring back; copying the target dir out of the VM fails on large builds.
+          copyback: false
+          # The same packages as release.yml's freebsd job: winit/wgpu (X11, Wayland, Vulkan,
+          # Mesa), the file dialogs (GTK 3), fonts, and audio (cpal over ALSA: alsa-lib).
+          prepare: |
+            pkg install -y bash git curl pkgconf cmake python3 libxkbcommon wayland libX11 libXcursor libXrandr libXi libxcb mesa-libs vulkan-loader gtk3 fontconfig freetype2 alsa-lib
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable
+          run: |
+            set -e
+            . "$HOME/.cargo/env"
+            git config --global --add safe.directory "*"
+            rustc --version
+            export CARGO_TARGET_DIR=/var/tmp/filmcraft-target CARGO_BUILD_JOBS=4
+            bash packaging/freebsd/package.sh
+            tar -tzf dist/release/filmcraft-*-freebsd-x86_64.tar.gz \
+              | grep -E '/bin/filmcraft$|/bin/filmcraft-cli$|/share/applications/ai\.storyteller\.filmcraft\.desktop$|/share/doc/filmcraft/LICENSE-MIT$'
@@ -54,4 +54,15 @@ jobs:
          desktop-file-validate packaging/linux/ai.storyteller.filmcraft.desktop
          sed -e 's/@VERSION@/0.0.0/' -e 's/@DATE@/2026-01-01/' packaging/linux/ai.storyteller.filmcraft.metainfo.xml.in >"$RUNNER_TEMP/ai.storyteller.filmcraft.metainfo.xml"
          appstreamcli validate --no-net --explain "$RUNNER_TEMP/ai.storyteller.filmcraft.metainfo.xml"
-          python3 -c "import yaml; m = yaml.safe_load(open('packaging/linux/flatpak/ai.storyteller.filmcraft.yml')); assert m['id'] == 'ai.storyteller.filmcraft' and m['command'] == 'filmcraft'"
+          python3 - <<'EOF'
+          import yaml
+          src = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.filmcraft.yml"))
+          bundle = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.filmcraft.bundle.yml"))
+          for m in (src, bundle):
+              assert m["id"] == "ai.storyteller.filmcraft" and m["command"] == "filmcraft", m["id"]
+          for key in ("runtime", "runtime-version", "sdk", "finish-args"):
+              assert src[key] == bundle[key], f"Flatpak manifests disagree on {key}: {src[key]} vs {bundle[key]}"
+          print("Flatpak manifests ok")
+          EOF
+      - name: FreeBSD package layout (stub binaries)
+        run: bash packaging/freebsd/package.sh --dry-run
@@ -1,9 +1,12 @@
 # Release pipeline: every push to `release` builds signed installers for every platform and
 # creates or updates the draft GitHub Release "FilmCraft v<version>". See docs/releasing.md.
 #
-# All jobs run in the `release` environment (restricted to the `release` branch), which holds
-# the signing secrets. Every secret is optional: missing ones produce unsigned artifacts and a
-# warning, never a failed build.
+# The jobs that sign (macOS, Windows) and the one that publishes the draft run in the `release`
+# environment (restricted to the `release` branch), which holds the signing secrets. Every secret
+# is optional: missing ones produce unsigned artifacts and a warning, never a failed build. The
+# jobs that sign nothing (version, Linux, Flatpak, FreeBSD, web) get no environment and no
+# secrets, so a dispatch on any other branch dry-runs them; there the signing jobs are refused,
+# so the draft-release job (which needs them) is skipped and nothing is published.
 name: Release

 on:
@@ -35,7 +38,6 @@ jobs:
  version:
    name: version
    runs-on: ubuntu-latest
-    environment: release
    outputs:
      version: ${{ steps.v.outputs.version }}
      date: ${{ steps.v.outputs.date }}
@@ -173,7 +175,7 @@ jobs:
    # The oldest GitHub-hosted image, so the binaries only need glibc >= 2.35 (Ubuntu 22.04+,
    # Debian 12+, Fedora 36+, RHEL 10). See docs/releasing.md.
    runs-on: ${{ matrix.runner }}
-    environment: release
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
    strategy:
      fail-fast: false
      matrix:
@@ -197,7 +199,7 @@ jobs:
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            libxkbcommon-dev libwayland-dev libx11-dev libxrandr-dev libxi-dev libgl1-mesa-dev libasound2-dev \
-            desktop-file-utils appstream python3-yaml
+            desktop-file-utils appstream python3-yaml zsync
          curl -fsSL -o "$RUNNER_TEMP/nfpm.deb" \
            "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/nfpm_${NFPM_VERSION}_${{ matrix.deb }}.deb"
          sudo dpkg -i "$RUNNER_TEMP/nfpm.deb"
@@ -222,6 +224,9 @@ jobs:
          for appimage in dist/release/*.AppImage; do
            chmod +x "$appimage"
            APPIMAGE_EXTRACT_AND_RUN=1 "$appimage" --version
+            # Update information is embedded, and the .zsync for delta updates sits beside it.
+            "$appimage" --appimage-updateinformation | grep -F 'gh-releases-zsync|'
+            test -s "$appimage.zsync"
          done
      - uses: actions/upload-artifact@v4
        with:
@@ -229,11 +234,101 @@ jobs:
          path: dist/release/*
          if-no-files-found: error

+  flatpak:
+    name: Flatpak ${{ matrix.arch }}
+    needs: [version, linux]
+    # Repackages the Linux job's tarball (the same binaries as the AppImage/deb/rpm); no Rust
+    # build here. 24.04 for a newer flatpak-builder (1.4) than 22.04 ships.
+    runs-on: ${{ matrix.runner }}
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { arch: x86_64, runner: ubuntu-24.04 }
+          - { arch: aarch64, runner: ubuntu-24.04-arm }
+    env:
+      FILMCRAFT_VERSION: ${{ needs.version.outputs.version }}
+      FILMCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-linux-${{ matrix.arch }}
+          path: dist/linux
+      - name: Install flatpak-builder
+        run: |
+          sudo apt-get update
+          # librsvg2-common: the SVG pixbuf loader. flatpak-builder runs the host's
+          # `appstreamcli compose`, which renders the scalable icon and fails without it.
+          sudo apt-get install -y --no-install-recommends flatpak flatpak-builder librsvg2-common
+          # Ubuntu 24.04's AppArmor blocks the unprivileged user namespaces bubblewrap needs.
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+      - name: Build the Flatpak bundle
+        run: packaging/linux/flatpak-bundle.sh "dist/linux/filmcraft-$FILMCRAFT_VERSION-linux-${{ matrix.arch }}.tar.gz"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-flatpak-${{ matrix.arch }}
+          path: dist/release/*.flatpak
+          if-no-files-found: error
+
+  freebsd:
+    name: FreeBSD x86_64
+    needs: version
+    # GitHub has no FreeBSD runners: build in a FreeBSD 14.3 VM, the same image and packages as
+    # .github/workflows/freebsd.yml.
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
+    env:
+      FILMCRAFT_VERSION: ${{ needs.version.outputs.version }}
+      FILMCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
+    steps:
+      - uses: actions/checkout@v4
+      # Fonts (optional build input, required for releases): docs/contributing.md#building-with-craft-fonts
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          repository: storytold/craft-fonts
+          ref: abb83316d96aa59c1cf64784289e378fe9fa5695 # bump deliberately
+          path: craft-fonts
+      - name: Build and package in a FreeBSD VM (tar.gz)
+        # vmactions/freebsd-vm v1.5.9, pinned by commit (it runs our build).
+        uses: vmactions/freebsd-vm@c46abacb49f09938ca4e1702d15d836285d694cc
+        with:
+          release: "14.3"
+          usesh: true
+          cpu: 4
+          mem: 12288
+          # Passed into the VM by name; never templated into the script below.
+          envs: "FILMCRAFT_VERSION FILMCRAFT_BUILD_DATE FILMCRAFT_BUILD_SHA INPUT_VERSION"
+          # The FreeBSD CI packages (.github/workflows/freebsd.yml), plus bash for the script.
+          prepare: |
+            pkg install -y bash git curl pkgconf cmake python3 libxkbcommon wayland libX11 libXcursor libXrandr libXi libxcb mesa-libs vulkan-loader gtk3 fontconfig freetype2 alsa-lib
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable
+          run: |
+            set -e
+            . "$HOME/.cargo/env"
+            git config --global --add safe.directory "$PWD"
+            # Build outside the checkout so only dist/ is copied back out of the VM (copying the
+            # target dir back fails on large builds). 4 jobs: more runs the VM out of memory.
+            export CARGO_TARGET_DIR=/var/tmp/filmcraft-target CARGO_BUILD_JOBS=4
+            if [ -n "$INPUT_VERSION" ]; then cargo xtask version set "$FILMCRAFT_VERSION"; fi
+            # craft-fonts was checked out next to the sources and synced into the VM with them.
+            export CRAFT_FONTS_DIR="$PWD/craft-fonts" CRAFT_FONTS_REQUIRED=1
+            bash packaging/freebsd/package.sh
+            tar -tzf dist/release/filmcraft-*-freebsd-x86_64.tar.gz \
+              | grep -E '/bin/filmcraft$|/bin/filmcraft-cli$|/share/applications/ai\.storyteller\.filmcraft\.desktop$|/share/doc/filmcraft/LICENSE-MIT$'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-freebsd-x86_64
+          path: dist/release/*
+          if-no-files-found: error
+
  web:
    name: Web (wasm)
    needs: version
    runs-on: ubuntu-latest
-    environment: release
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
    env:
      FILMCRAFT_VERSION: ${{ needs.version.outputs.version }}
      FILMCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
@@ -275,7 +370,7 @@ jobs:

  release:
    name: Draft GitHub Release
-    needs: [version, macos, windows, linux, web]
+    needs: [version, macos, windows, linux, flatpak, freebsd, web]
    runs-on: ubuntu-latest
    environment: release
    permissions:
@@ -59,6 +59,7 @@
  <a href="#interchange">Interchange</a> ·
  <a href="#built-for-agents">Agents</a> ·
  <a href="#get-started">Get started</a> ·
+  <a href="#downloads">Downloads</a> ·
  <a href="#documentation">Docs</a> ·
  <a href="#status">Status</a>
 </p>
@@ -310,6 +311,50 @@ A layered Cargo workspace:

 Nothing below the front ends depends on a UI toolkit or OS API. `cargo xtask ci` checks formatting, lints, tests, the layering rules, asset attribution and the wasm build.

+## Downloads
+
+Every [release](https://github.com/storytold/filmcraft/releases/latest) ships these builds. `<ver>` is the
+version number; `SHA256SUMS.txt` lists a checksum for every file.
+
+### macOS
+
+| Build | File | Notes |
+|---|---|---|
+| App, universal (Apple silicon + Intel) | `filmcraft-<ver>-macos-universal.dmg` | Signed and notarized |
+| Command-line tool, universal | `filmcraft-cli-<ver>-macos-universal.zip` | Signed and notarized |
+
+### Windows
+
+| Build | Installer | Portable |
+|---|---|---|
+| x64 (64-bit Intel/AMD) | `filmcraft-<ver>-windows-x64.msi` | `filmcraft-<ver>-windows-x64-portable.zip` |
+| arm64 (Snapdragon and other ARM PCs) | `filmcraft-<ver>-windows-arm64.msi` | `filmcraft-<ver>-windows-arm64-portable.zip` |
+| x86 (32-bit) | `filmcraft-<ver>-windows-x86.msi` | `filmcraft-<ver>-windows-x86-portable.zip` |
+
+Installers and executables are code-signed.
+
+### Linux
+
+| Format | x86_64 | aarch64 (ARM64) | Notes |
+|---|---|---|---|
+| AppImage | `filmcraft-<ver>-linux-x86_64.AppImage` | `filmcraft-<ver>-linux-aarch64.AppImage` | Runs anywhere; updates itself with [AppImageUpdate](https://github.com/AppImageCommunity/AppImageUpdate) (`.zsync` files) |
+| Flatpak | `filmcraft-<ver>-linux-x86_64.flatpak` | `filmcraft-<ver>-linux-aarch64.flatpak` | Sandboxed; `flatpak install --user <file>` |
+| Debian/Ubuntu | `filmcraft-<ver>-linux-x86_64.deb` | `filmcraft-<ver>-linux-aarch64.deb` | |
+| Fedora/RHEL/openSUSE | `filmcraft-<ver>-linux-x86_64.rpm` | `filmcraft-<ver>-linux-aarch64.rpm` | |
+| Tarball | `filmcraft-<ver>-linux-x86_64.tar.gz` | `filmcraft-<ver>-linux-aarch64.tar.gz` | Unpack anywhere |
+
+### FreeBSD
+
+| Build | File |
+|---|---|
+| x86_64 | `filmcraft-<ver>-freebsd-x86_64.tar.gz` |
+
+### Web (WebAssembly)
+
+| Build | File | Notes |
+|---|---|---|
+| Static site | `filmcraft-web-<ver>.zip` | Runs in a modern browser; host it on any static server |
+
 ## The Crafting Apps

 FilmCraft is one of the **Crafting Apps**: free, open-source creative tools from the
@@ -1,7 +1,8 @@
 # Releasing FilmCraft

 Every push to the `release` branch runs `.github/workflows/release.yml`. The workflow builds
-installers for macOS, Windows and Linux, plus the web build, and creates or updates a **draft**
+installers for macOS, Windows, Linux (AppImage, deb, rpm, tarball, Flatpak) and FreeBSD, plus
+the web build, and creates or updates a **draft**
 GitHub Release named `FilmCraft v<version>`. Nobody sees a draft until a maintainer publishes it.

 User-facing names say **FilmCraft**. Files, binaries and ids stay lowercase
@@ -33,8 +34,11 @@ Once the draft is published, the workflow refuses to touch that version again: b

 **Test runs:** *Actions › Release › Run workflow* runs the whole pipeline by hand. The optional
 `version` input (such as `0.3.0-rc.1`) overrides `Cargo.toml` for that run only; each build job
-applies it with `cargo xtask version set` before building. The jobs run in the `release`
-environment, which only the `release` branch can use, so pick that branch in the dialog.
+applies it with `cargo xtask version set` before building. The signing jobs (macOS, Windows)
+and the draft-release job run in the `release` environment, which only the `release` branch can
+use, so pick that branch for a full run. Run from any other branch, it is a dry run: the jobs that
+sign nothing (Linux, Flatpak, FreeBSD, web) build and upload their artifacts to the run, the
+signing jobs are refused, and the draft-release job, which needs them, is skipped.

 ## What gets built

@@ -46,6 +50,9 @@ environment, which only the `release` branch can use, so pick that branch in the
 | Windows on ARM64 | `filmcraft-<v>-windows-arm64.msi`, `filmcraft-<v>-windows-arm64-portable.zip` | `windows-latest` (cross-compiled) |
 | Linux x86_64 | `filmcraft-<v>-linux-x86_64.{AppImage,deb,rpm,tar.gz}` | `ubuntu-22.04` |
 | Linux aarch64 | `filmcraft-<v>-linux-aarch64.{AppImage,deb,rpm,tar.gz}` | `ubuntu-22.04-arm` |
+| AppImage updates | `filmcraft-<v>-linux-{x86_64,aarch64}.AppImage.zsync` | with the AppImage |
+| Flatpak | `filmcraft-<v>-linux-x86_64.flatpak`, `filmcraft-<v>-linux-aarch64.flatpak` | `ubuntu-24.04`, `ubuntu-24.04-arm` (repackaged Linux tarball) |
+| FreeBSD 14 x86_64 | `filmcraft-<v>-freebsd-x86_64.tar.gz` | FreeBSD 14.3 VM on `ubuntu-latest` |
 | Web | `filmcraft-web-<v>.zip`, a static site (see [`packaging/web/README.md`](../packaging/web/README.md)) | `ubuntu-latest` |

 `filmcraft --version` and `filmcraft-cli --version` print the version from `Cargo.toml`.
@@ -104,8 +111,34 @@ the job to a newer image raises the floor, so do it deliberately and update `nfp
 After packaging, the job prints the `.deb`'s metadata and contents, runs `ldd` on the binary and
 runs each AppImage with `--version`.

-`packaging/linux/flatpak/ai.storyteller.filmcraft.yml` is a Flatpak manifest (its header says how
-to build it). The release doesn't build a Flatpak; the workflows only check the manifest's id.
+**AppImage updates.** Each AppImage embeds update information,
+`gh-releases-zsync|storytold|filmcraft|latest|filmcraft-*-linux-<arch>.AppImage.zsync`, and
+`appimagetool` writes the matching `.zsync` beside it (the job installs `zsync` for
+`zsyncmake`). [AppImageUpdate](https://github.com/AppImageCommunity/AppImageUpdate) and
+AppImageLauncher then fetch only the changed blocks from the newest published (non-pre-release)
+release. The job checks both with `--appimage-updateinformation` and `test -s`.
+
+**Flatpak.** The `flatpak` jobs (x86_64 on `ubuntu-24.04`, aarch64 on `ubuntu-24.04-arm`) run
+`packaging/linux/flatpak-bundle.sh` on the Linux job's tarball: it installs the binaries with
+`packaging/linux/flatpak/ai.storyteller.filmcraft.bundle.yml` into a single-file bundle,
+`filmcraft-<v>-linux-<arch>.flatpak` (no Rust build, so it takes a minute), then installs it and
+runs `filmcraft-cli --version` in the sandbox. Users install it with
+`flatpak install --user <file>`; the freedesktop runtime comes from Flathub.
+`packaging/linux/flatpak/ai.storyteller.filmcraft.yml` is the from-source manifest for a Flathub
+submission (its header says how to build it). Both manifests must keep the same runtime and
+`finish-args` (packaging-lint checks this).
+
+### FreeBSD
+
+GitHub has no FreeBSD runners, so the `freebsd` job builds in a FreeBSD 14.3 VM
+([vmactions/freebsd-vm](https://github.com/vmactions/freebsd-vm), pinned by commit) on
+`ubuntu-latest`. `packaging/freebsd/package.sh` builds both programs and packs a
+`/usr/local`-style tree as `filmcraft-<v>-freebsd-x86_64.tar.gz`; install it with
+`tar -xzf filmcraft-<v>-freebsd-x86_64.tar.gz --strip-components 1 -C /usr/local`. The build needs
+the packages listed in the job (winit/wgpu, GTK 3 for the file dialogs, fontconfig, and
+`alsa-lib` for audio through cpal). `.github/workflows/freebsd.yml` builds and packages the same
+way nightly, so a FreeBSD break shows up before a release. `package.sh --dry-run` checks the
+tree's layout with stub binaries on any OS (packaging-lint runs it).

 ### Web

@@ -122,8 +155,9 @@ the job fails and asks for a version bump (`cargo xtask version set`).

 ## Secrets

-All jobs run in the `release` environment, which only the `release` branch can use and which holds
-the signing secrets. Every secret is optional: a missing one produces unsigned artifacts and a
+The macOS, Windows and draft-release jobs run in the `release` environment, which only the
+`release` branch can use and which holds the signing secrets. The other jobs sign nothing and get
+no secrets. Every secret is optional: a missing one produces unsigned artifacts and a
 warning, never a failed build.

 | Secret | Used for |
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Build and package FilmCraft for FreeBSD:
+#
+#   $DIST/filmcraft-<version>-freebsd-x86_64.tar.gz   a /usr/local-style tree:
+#       filmcraft-<version>-freebsd-x86_64/{bin, share/applications, share/icons, share/mime,
+#       share/metainfo, share/doc/filmcraft}
+#
+# Install by copying the tree's contents into /usr/local:
+#   tar -xzf filmcraft-<version>-freebsd-x86_64.tar.gz --strip-components 1 -C /usr/local
+#
+# Usage: packaging/freebsd/package.sh [--skip-build] [--dry-run]
+#   --dry-run   stage the tree from stub binaries and list it, without building (works on any OS)
+#
+# Needs: bash, cargo, and the packages installed in .github/workflows/freebsd.yml.
+set -euo pipefail
+# shellcheck source=../env.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
+LINUX="$ROOT/packaging/linux"
+APP_ID=ai.storyteller.filmcraft
+
+SKIP_BUILD=0
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --skip-build) SKIP_BUILD=1; shift ;;
+    --dry-run) DRY_RUN=1; SKIP_BUILD=1; shift ;;
+    -h | --help) sed -n '2,15p' "$0"; exit 0 ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+# FreeBSD's uname says amd64; release file names use x86_64 like the Linux and Windows ones.
+MACHINE="$(uname -m)"
+case "$MACHINE" in
+  amd64 | x86_64) ARCH=x86_64 ;;
+  arm64 | aarch64) ARCH=aarch64 ;;
+  *) echo "unsupported architecture $MACHINE" >&2; exit 2 ;;
+esac
+if [ "$DRY_RUN" = 0 ] && [ "$(uname -s)" != FreeBSD ]; then
+  echo "error: build on FreeBSD (or pass --dry-run to check the tree layout)" >&2
+  exit 2
+fi
+BASENAME="filmcraft-$VERSION-freebsd-$ARCH"
+
+echo "==> FilmCraft $VERSION for FreeBSD $ARCH"
+
+# The release VM has 12 GB; full parallelism on the biggest crates runs it out of memory.
+export CARGO_BUILD_JOBS="${CARGO_BUILD_JOBS:-4}"
+if [ "$SKIP_BUILD" = 0 ]; then
+  (cd "$ROOT" && cargo build --release --locked -p filmcraft -p filmcraft-cli)
+fi
+WORK="$CARGO_TARGET_DIR/freebsd-package"
+STAGE="$WORK/$BASENAME"
+rm -rf "$WORK"
+mkdir -p "$WORK"
+
+BIN="$CARGO_TARGET_DIR/release"
+OUT_DIR="$DIST"
+if [ "$DRY_RUN" = 1 ]; then
+  # Stub binaries, and the tarball stays in the work dir so dist/ only ever holds real builds.
+  BIN="$WORK/stub-bin"
+  OUT_DIR="$WORK"
+  mkdir -p "$BIN"
+  for b in filmcraft filmcraft-cli; do
+    printf '#!/bin/sh\necho "%s %s (dry-run stub)"\n' "$b" "$VERSION" >"$BIN/$b"
+    chmod 755 "$BIN/$b"
+  done
+fi
+
+# ---- stage a /usr/local-style tree --------------------------------------------------------------
+# FreeBSD's install(1) has no -D: create the directories first.
+mkdir -p "$STAGE/bin" "$STAGE/share/applications" "$STAGE/share/mime/packages" \
+  "$STAGE/share/metainfo" "$STAGE/share/icons" "$STAGE/share/doc/filmcraft"
+install -m 755 "$BIN/filmcraft" "$BIN/filmcraft-cli" "$STAGE/bin/"
+strip "$STAGE/bin/filmcraft" "$STAGE/bin/filmcraft-cli" 2>/dev/null || true
+# The desktop entry, MIME type, metainfo and icons are the freedesktop files Linux ships.
+install -m 644 "$LINUX/$APP_ID.desktop" "$STAGE/share/applications/$APP_ID.desktop"
+install -m 644 "$LINUX/$APP_ID.mime.xml" "$STAGE/share/mime/packages/$APP_ID.xml"
+sed -e "s/@VERSION@/$VERSION/g" -e "s/@DATE@/$FILMCRAFT_BUILD_DATE/g" \
+  "$LINUX/$APP_ID.metainfo.xml.in" >"$STAGE/share/metainfo/$APP_ID.metainfo.xml"
+cp -R "$ROOT/assets/app-icon/hicolor" "$STAGE/share/icons/"
+copy_docs "$STAGE/share/doc/filmcraft"
+for f in NOTICE ATTRIBUTION.md; do
+  if [ -f "$ROOT/$f" ]; then install -m 644 "$ROOT/$f" "$STAGE/share/doc/filmcraft/"; fi
+done
+
+for f in bin/filmcraft bin/filmcraft-cli "share/applications/$APP_ID.desktop" \
+  "share/icons/hicolor/256x256/apps/$APP_ID.png" "share/icons/hicolor/scalable/apps/$APP_ID.svg" \
+  share/doc/filmcraft/LICENSE-MIT share/doc/filmcraft/LICENSE-APACHE; do
+  if [ ! -e "$STAGE/$f" ]; then echo "error: $f is missing from the package" >&2; exit 1; fi
+done
+
+# ---- .tar.gz ------------------------------------------------------------------------------------
+mkdir -p "$OUT_DIR"
+tar -C "$WORK" -czf "$OUT_DIR/$BASENAME.tar.gz" "$BASENAME"
+echo "wrote $OUT_DIR/$BASENAME.tar.gz"
+
+"$STAGE/bin/filmcraft-cli" --version
+if [ "$DRY_RUN" = 1 ]; then
+  echo "==> dry run: tarball contents"
+  tar -tzvf "$OUT_DIR/$BASENAME.tar.gz"
+fi
+echo "==> done"
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Repackage a FilmCraft Linux tarball as a single-file Flatpak bundle:
+#
+#   $DIST/filmcraft-<version>-linux-<arch>.flatpak
+#
+# Usage: packaging/linux/flatpak-bundle.sh [--no-test] [TARBALL]
+#
+# TARBALL defaults to $DIST/filmcraft-<version>-linux-<arch>.tar.gz from package.sh. The bundle
+# is built for the host architecture (x86_64 or aarch64), which must match the tarball's.
+# Needs flatpak, flatpak-builder and the SVG pixbuf loader (librsvg2-common) for the host's
+# `appstreamcli compose`; the freedesktop runtime and SDK named in the manifest are
+# installed per-user from Flathub. Unless --no-test, the bundle is then installed per-user and
+# `filmcraft-cli --version` is run inside the sandbox as a smoke test.
+# Manifest: packaging/linux/flatpak/ai.storyteller.filmcraft.bundle.yml.
+set -euo pipefail
+# shellcheck source=../env.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
+HERE="$ROOT/packaging/linux"
+APP_ID=ai.storyteller.filmcraft
+FLATHUB=https://dl.flathub.org/repo/flathub.flatpakrepo
+
+TEST=1
+TARBALL=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --no-test) TEST=0; shift ;;
+    -h | --help) sed -n '2,14p' "$0"; exit 0 ;;
+    -*) echo "unknown argument: $1" >&2; exit 2 ;;
+    *) TARBALL="$1"; shift ;;
+  esac
+done
+
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64) ;;
+  aarch64 | arm64) ARCH=aarch64 ;;
+  *) echo "unsupported architecture $ARCH" >&2; exit 2 ;;
+esac
+BASENAME="filmcraft-$VERSION-linux-$ARCH"
+TARBALL="${TARBALL:-$DIST/$BASENAME.tar.gz}"
+[ -f "$TARBALL" ] || { echo "error: $TARBALL not found (run packaging/linux/package.sh --formats tar first)" >&2; exit 1; }
+for tool in flatpak flatpak-builder; do
+  command -v "$tool" >/dev/null || { echo "error: $tool not found (apt install flatpak flatpak-builder librsvg2-common)" >&2; exit 1; }
+done
+
+echo "==> FilmCraft $VERSION Flatpak bundle for $ARCH from $(basename "$TARBALL")"
+
+WORK="$CARGO_TARGET_DIR/flatpak-bundle"
+rm -rf "$WORK"
+mkdir -p "$WORK/stage"
+tar -xzf "$TARBALL" -C "$WORK/stage" --strip-components=1
+[ -x "$WORK/stage/bin/filmcraft" ] || { echo "error: $TARBALL has no bin/filmcraft" >&2; exit 1; }
+cp "$HERE/flatpak/$APP_ID.bundle.yml" "$WORK/$APP_ID.yml"
+
+flatpak remote-add --user --if-not-exists flathub "$FLATHUB"
+# --disable-rofiles-fuse: no FUSE in containers and CI runners.
+flatpak-builder --user --install-deps-from=flathub --disable-rofiles-fuse --force-clean \
+  --default-branch=stable --repo="$WORK/repo" --state-dir="$WORK/state" "$WORK/build" "$WORK/$APP_ID.yml"
+
+OUT="$DIST/$BASENAME.flatpak"
+# --runtime-repo lets `flatpak install` fetch the freedesktop runtime from Flathub if missing.
+flatpak build-bundle --runtime-repo="$FLATHUB" "$WORK/repo" "$OUT" "$APP_ID" stable
+echo "wrote $OUT"
+
+if [ "$TEST" = 1 ]; then
+  flatpak install --user -y --noninteractive --reinstall "$OUT"
+  flatpak info --user "$APP_ID"
+  flatpak run --command=filmcraft-cli "$APP_ID" --version
+  flatpak run --command=sh "$APP_ID" -c 'ls /app/share/applications /app/share/metainfo /app/share/mime/packages /app/share/icons/hicolor/scalable/apps'
+fi
+echo "==> done"
+ls -lh "$OUT"
@@ -0,0 +1,59 @@
+# Flatpak manifest for the single-file bundle attached to every GitHub release
+# (filmcraft-<version>-linux-<arch>.flatpak). Build it with packaging/linux/flatpak-bundle.sh.
+#
+# It repackages the release's own Linux tarball (filmcraft-<version>-linux-<arch>.tar.gz,
+# built on Ubuntu 22.04 by package.sh) instead of compiling Rust inside flatpak-builder: no
+# network and no vendored crate sources during the build, a few seconds instead of 20+ minutes,
+# and byte-for-byte the same binaries as the AppImage/deb/rpm. The script unpacks the tarball
+# into `stage/` next to a copy of this file. The binaries need glibc >= 2.35 and load X11,
+# Wayland, xkbcommon, ALSA and Vulkan at runtime; the freedesktop runtime has all of them (its
+# ALSA routes through PulseAudio/PipeWire), and the GPU driver comes from its
+# org.freedesktop.Platform.GL extension.
+#
+# ai.storyteller.filmcraft.yml (same directory) is the from-source manifest for Flathub. Keep
+# runtime-version and finish-args identical in both (packaging-lint checks this).
+id: ai.storyteller.filmcraft
+runtime: org.freedesktop.Platform
+runtime-version: '25.08'
+sdk: org.freedesktop.Sdk
+command: filmcraft
+finish-args:
+  # X11 shared memory (MIT-SHM). Without it the X11 fallback is slow or fails.
+  - --share=ipc
+  # Display: Wayland first; X11 only when no Wayland compositor is running.
+  - --socket=wayland
+  - --socket=fallback-x11
+  # Audio playback and the mixer's meters (cpal over ALSA, which the runtime routes to the
+  # host's PulseAudio or PipeWire server).
+  - --socket=pulseaudio
+  # GPU access for the wgpu compositor, scopes and effects (Vulkan, or GL as a fallback).
+  - --device=dri
+  # A project refers to its media by absolute path (docs/project-files.md), and the document
+  # portal only exposes the file it was handed, not the media beside it: a project opened from
+  # ~/Videos found none of its clips (#107). So, as other video editors do, FilmCraft reads and
+  # writes the home directory (media, projects, exports, autosave next to the project) and the
+  # usual mount points of external drives, where footage often lives. Open/Save dialogs still go
+  # through the file-chooser portal; nothing outside these locations is granted.
+  - --filesystem=home
+  - --filesystem=/media
+  - --filesystem=/run/media
+  - --filesystem=/mnt
+  # Deliberately not granted: network (the optional --control server listens on 127.0.0.1 in
+  # the sandbox; `flatpak override --user --share=network ai.storyteller.filmcraft` exposes it
+  # to host agents) and host-wide filesystem access.
+modules:
+  - name: filmcraft
+    buildsystem: simple
+    build-commands:
+      - install -Dm755 bin/filmcraft /app/bin/filmcraft
+      - install -Dm755 bin/filmcraft-cli /app/bin/filmcraft-cli
+      - install -Dm644 share/applications/ai.storyteller.filmcraft.desktop /app/share/applications/ai.storyteller.filmcraft.desktop
+      # The same MIME file the deb/rpm install (no types of its own yet; the runtime's
+      # shared-mime-info already knows the video and audio formats).
+      - install -Dm644 share/mime/packages/ai.storyteller.filmcraft.xml /app/share/mime/packages/ai.storyteller.filmcraft.xml
+      # Already has the release's version and date substituted by package.sh.
+      - install -Dm644 share/metainfo/ai.storyteller.filmcraft.metainfo.xml /app/share/metainfo/ai.storyteller.filmcraft.metainfo.xml
+      - mkdir -p /app/share/icons /app/share/doc && cp -R share/icons/hicolor /app/share/icons/ && cp -R share/doc/filmcraft /app/share/doc/
+    sources:
+      - type: dir
+        path: stage
@@ -16,10 +16,15 @@ sdk-extensions:
  - org.freedesktop.Sdk.Extension.rust-stable
 command: filmcraft
 finish-args:
+  # X11 shared memory (MIT-SHM). Without it the X11 fallback is slow or fails.
  - --share=ipc
+  # Display: Wayland first; X11 only when no Wayland compositor is running.
  - --socket=wayland
  - --socket=fallback-x11
+  # Audio playback and the mixer's meters (cpal over ALSA, which the runtime routes to the
+  # host's PulseAudio or PipeWire server).
  - --socket=pulseaudio
+  # GPU access for the wgpu compositor, scopes and effects (Vulkan, or GL as a fallback).
  - --device=dri
  # A project refers to its media by absolute path (docs/project-files.md), and the document
  # portal only exposes the file it was handed, not the media beside it: a project opened from
@@ -31,6 +36,9 @@ finish-args:
  - --filesystem=/media
  - --filesystem=/run/media
  - --filesystem=/mnt
+  # Deliberately not granted: network (the optional --control server listens on 127.0.0.1 in
+  # the sandbox; `flatpak override --user --share=network ai.storyteller.filmcraft` exposes it
+  # to host agents) and host-wide filesystem access.
 build-options:
  append-path: /usr/lib/sdk/rust-stable/bin
 modules:
@@ -2,6 +2,7 @@
 # Build and package FilmCraft for Linux (<arch> is x86_64 or aarch64):
 #
 #   $DIST/filmcraft-<version>-linux-<arch>.AppImage  any distro with glibc >= the build host's
+#   $DIST/filmcraft-<version>-linux-<arch>.AppImage.zsync  delta updates (needs zsyncmake)
 #   $DIST/filmcraft-<version>-linux-<arch>.deb       Debian, Ubuntu, Mint, Pop!_OS, ...
 #   $DIST/filmcraft-<version>-linux-<arch>.rpm       Fedora, openSUSE, RHEL, ...
 #   $DIST/filmcraft-<version>-linux-<arch>.tar.gz    plain FHS-style tree (bin/, share/)
@@ -10,7 +11,8 @@
 #
 # Needs: cargo; nfpm for deb/rpm (https://nfpm.goreleaser.com); appimagetool for the AppImage
 # (downloaded into $CARGO_TARGET_DIR if missing). Build on an old distro (CI: Ubuntu 22.04,
-# glibc 2.35) so the binaries run on newer ones. Optional: desktop-file-validate, appstreamcli.
+# glibc 2.35) so the binaries run on newer ones. Optional: desktop-file-validate, appstreamcli,
+# zsyncmake (the zsync package) for the AppImage's .zsync.
 set -euo pipefail
 # shellcheck source=../env.sh
 . "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
@@ -23,7 +25,7 @@ while [ $# -gt 0 ]; do
  case "$1" in
    --skip-build) SKIP_BUILD=1; shift ;;
    --formats) FORMATS="$2"; shift 2 ;;
-    -h | --help) sed -n '2,15p' "$0"; exit 0 ;;
+    -h | --help) sed -n '2,16p' "$0"; exit 0 ;;
    *) echo "unknown argument: $1" >&2; exit 2 ;;
  esac
 done
@@ -108,11 +110,29 @@ if has appimage; then
      chmod +x "$TOOL"
    fi
  fi
-  OUT="$DIST/$BASENAME.AppImage"
+  # Absolute, because appimagetool runs in $DIST below (CARGO_TARGET_DIR or APPIMAGETOOL may be
+  # relative, e.g. target/agent-<name>).
+  OUT="$(cd "$DIST" && pwd)/$BASENAME.AppImage"
+  APPDIR="$(cd "$APPDIR" && pwd)"
+  TOOL="$(cd "$(dirname "$TOOL")" && pwd)/$(basename "$TOOL")"
+  # A .zsync left by an earlier run would hide a missing zsyncmake and describe another file.
+  rm -f "$OUT.zsync"
+  # Update information: AppImageUpdate, AppImageLauncher and the like read it from the file and
+  # fetch only the blocks that changed in a newer release, through the .zsync published next to
+  # each AppImage on GitHub Releases. `latest` is the newest published release that is not a
+  # pre-release. A fork's builds point at its own releases through GITHUB_REPOSITORY.
+  REPO="${GITHUB_REPOSITORY:-storytold/filmcraft}"
+  UPDATE_INFO="gh-releases-zsync|${REPO%%/*}|${REPO#*/}|latest|filmcraft-*-linux-$ARCH.AppImage.zsync"
  # Extract-and-run: works without FUSE (containers, CI). The output embeds the static runtime,
-  # so users don't need libfuse2 either.
-  ARCH="$ARCH" APPIMAGE_EXTRACT_AND_RUN=1 "$TOOL" --no-appstream "$APPDIR" "$OUT"
+  # so users don't need libfuse2 either. With zsyncmake on the host (CI installs the zsync
+  # package) appimagetool also writes the .zsync, into its working directory, hence the cd.
+  (cd "$DIST" && ARCH="$ARCH" APPIMAGE_EXTRACT_AND_RUN=1 "$TOOL" --no-appstream -u "$UPDATE_INFO" "$APPDIR" "$OUT")
  echo "wrote $OUT"
+  if [ -s "$OUT.zsync" ]; then
+    echo "wrote $OUT.zsync"
+  else
+    warn "zsyncmake not found, so $OUT.zsync was not written; AppImage delta updates need it"
+  fi
 fi

 "$STAGE/usr/bin/filmcraft-cli" --version