Bound Gitea release mirror retries

.gitea/workflows/android.yaml

@@ -1,4 +1,4 @@
-name: Gitea Android Compile Check
+name: Gitea Android APK
 
 on: [push]
 
@@ -6,19 +6,123 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Compile Android APK
+      - name: Build Android APK
         env:
           CLONE_TOKEN: ${{ secrets.TMUX_GITEA_TOKEN }}
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
         run: |
           set -eu
 
+          install_packages() {
+            if command -v apt-get >/dev/null 2>&1; then
+              apt-get update
+              apt-get install -y "$@"
+            elif command -v apk >/dev/null 2>&1; then
+              apk add --no-cache "$@"
+            elif command -v dnf >/dev/null 2>&1; then
+              dnf install -y "$@"
+            else
+              echo "No supported package manager found." >&2
+              exit 1
+            fi
+          }
+
           if ! command -v git >/dev/null 2>&1 || ! command -v curl >/dev/null 2>&1 || ! command -v unzip >/dev/null 2>&1; then
-            apt-get update
-            apt-get install -y git curl unzip
+            install_packages git curl unzip
           fi
+
+          REF="${GITHUB_REF:-}"
+          REF_NAME="${GITHUB_REF_NAME:-}"
+          if [ -z "${REF_NAME}" ]; then
+            REF_NAME="${REF##*/}"
+          fi
+          if [ "${REF#refs/tags/v}" != "${REF}" ]; then
+            if [ -z "${CLONE_TOKEN:-}" ]; then
+              echo "Gitea release publishing requires TMUX_GITEA_TOKEN." >&2
+              exit 1
+            fi
+
+            TAG="${REF_NAME}"
+            VERSION_NAME="${TAG#v}"
+            MAJOR="$(printf '%s' "${VERSION_NAME}" | cut -d. -f1)"
+            MINOR="$(printf '%s' "${VERSION_NAME}" | cut -d. -f2)"
+            PATCH="$(printf '%s' "${VERSION_NAME}" | cut -d. -f3)"
+            VERSION_CODE=$((MAJOR * 1000000 + MINOR * 1000 + PATCH))
+            GITHUB_APK_URL="https://github.com/neatstudio/tmux-browser-android/releases/download/${TAG}/tmux-android.apk"
+
+            mkdir -p release
+            ATTEMPT=1
+            while [ "${ATTEMPT}" -le 6 ]; do
+              if curl -fsSL "${GITHUB_APK_URL}" -o release/tmux-android.apk; then
+                break
+              fi
+              rm -f release/tmux-android.apk
+              echo "Waiting for GitHub release ${TAG} (${ATTEMPT}/6)..."
+              sleep 10
+              ATTEMPT=$((ATTEMPT + 1))
+            done
+            if [ ! -s release/tmux-android.apk ]; then
+              echo "GitHub release APK unavailable for ${TAG}." >&2
+              exit 1
+            fi
+
+            SHA256="$(sha256sum release/tmux-android.apk | cut -d ' ' -f1)"
+            APK_URL="https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/${TAG}/tmux-android.apk"
+            RELEASE_PAGE_URL="https://gitea.neatcn.com/tmux/tmux-browser-android/releases/tag/${TAG}"
+            cat > release/latest.json << JSON
+            {
+              "versionCode": ${VERSION_CODE},
+              "versionName": "${VERSION_NAME}",
+              "apkUrl": "${APK_URL}",
+              "sha256": "${SHA256}",
+              "releasePageUrl": "${RELEASE_PAGE_URL}",
+              "minSdk": 26
+            }
+          JSON
+
+            API_ROOT="https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android"
+            RELEASE_BODY='{"tag_name":"'"${TAG}"'","target_commitish":"main","name":"tmux Android '"${VERSION_NAME}"'","body":"Android APK for tmux-ui remote testing.","draft":false,"prerelease":false}'
+            if ! curl -fsSL -X POST \
+              -H "Authorization: token ${CLONE_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "${RELEASE_BODY}" \
+              "${API_ROOT}/releases" \
+              -o /tmp/gitea-release.json; then
+              curl -fsSL -H "Authorization: token ${CLONE_TOKEN}" \
+                "${API_ROOT}/releases/tags/${TAG}" \
+                -o /tmp/gitea-release.json
+            fi
+            RELEASE_ID="$(sed -n 's/.*"id":\([0-9][0-9]*\).*/\1/p' /tmp/gitea-release.json | head -1)"
+            if [ -z "${RELEASE_ID}" ]; then
+              echo "Cannot resolve Gitea release id for ${TAG}." >&2
+              exit 1
+            fi
+            curl -fsSL -X POST -H "Authorization: token ${CLONE_TOKEN}" \
+              -F "attachment=@release/tmux-android.apk;type=application/vnd.android.package-archive" \
+              "${API_ROOT}/releases/${RELEASE_ID}/assets?name=tmux-android.apk" \
+              -o /tmp/gitea-apk-asset.json
+            curl -fsSL -X POST -H "Authorization: token ${CLONE_TOKEN}" \
+              -F "attachment=@release/latest.json;type=application/json" \
+              "${API_ROOT}/releases/${RELEASE_ID}/assets?name=latest.json" \
+              -o /tmp/gitea-latest-asset.json
+            echo "Mirrored GitHub release ${TAG} to Gitea."
+            echo "versionCode=${VERSION_CODE}"
+            echo "versionName=${VERSION_NAME}"
+            echo "sha256=${SHA256}"
+            exit 0
+          fi
+
           if ! command -v java >/dev/null 2>&1; then
-            apt-get update
-            apt-get install -y openjdk-17-jdk-headless
+            if command -v apk >/dev/null 2>&1; then
+              install_packages openjdk17-jdk
+            elif command -v dnf >/dev/null 2>&1; then
+              install_packages java-17-openjdk-devel
+            else
+              install_packages openjdk-17-jdk-headless
+            fi
           fi
           java -version
 
@@ -26,8 +130,12 @@ jobs:
           rm -rf "${WORKDIR}"
           SERVER_URL="${GITHUB_SERVER_URL:-https://gitea.neatcn.com}"
           REPOSITORY="${GITHUB_REPOSITORY:-tmux/tmux-browser-android}"
-          AUTH_SERVER_URL="$(printf '%s' "${SERVER_URL}" | sed "s#https://#https://gouki:${CLONE_TOKEN}@#")"
-          git clone "${AUTH_SERVER_URL}/${REPOSITORY}.git" "${WORKDIR}"
+          if [ -n "${CLONE_TOKEN:-}" ]; then
+            AUTH_SERVER_URL="$(printf '%s' "${SERVER_URL}" | sed "s#https://#https://gouki:${CLONE_TOKEN}@#")"
+            git clone "${AUTH_SERVER_URL}/${REPOSITORY}.git" "${WORKDIR}"
+          else
+            git clone "${SERVER_URL}/${REPOSITORY}.git" "${WORKDIR}"
+          fi
           cd "${WORKDIR}"
           git checkout "${GITHUB_SHA:-main}"
 
@@ -53,17 +161,105 @@ jobs:
           yes | sdkmanager --licenses >/dev/null || true
           sdkmanager "platforms;android-35" "build-tools;35.0.0" "platform-tools"
 
-          VERSION_NAME="0.1.${GITHUB_RUN_NUMBER:-0}"
-          VERSION_CODE=$((2000 + ${GITHUB_RUN_NUMBER:-0}))
-          gradle :app:assembleDebug \
+          REF="${GITHUB_REF:-}"
+          REF_NAME="${GITHUB_REF_NAME:-}"
+          if [ -z "${REF_NAME}" ]; then
+            REF_NAME="${REF##*/}"
+          fi
+          PUBLISH_RELEASE=0
+          if [ "${REF#refs/tags/v}" != "${REF}" ]; then
+            PUBLISH_RELEASE=1
+            VERSION_NAME="${REF_NAME#v}"
+            MAJOR="$(printf '%s' "${VERSION_NAME}" | cut -d. -f1)"
+            MINOR="$(printf '%s' "${VERSION_NAME}" | cut -d. -f2)"
+            PATCH="$(printf '%s' "${VERSION_NAME}" | cut -d. -f3)"
+            VERSION_CODE=$((MAJOR * 1000000 + MINOR * 1000 + PATCH))
+          else
+            VERSION_NAME="0.1.${GITHUB_RUN_NUMBER:-0}"
+            VERSION_CODE=$((3000 + ${GITHUB_RUN_NUMBER:-0}))
+          fi
+
+          SIGNED=false
+          if [ -n "${ANDROID_KEYSTORE_BASE64:-}" ]; then
+            echo "${ANDROID_KEYSTORE_BASE64}" | base64 -d > release.jks
+            {
+              echo "storeFile=release.jks"
+              echo "storePassword=${ANDROID_KEYSTORE_PASSWORD}"
+              echo "keyAlias=${ANDROID_KEY_ALIAS}"
+              echo "keyPassword=${ANDROID_KEY_PASSWORD}"
+            } > signing.properties
+            SIGNED=true
+          fi
+
+          if [ "${PUBLISH_RELEASE}" = "1" ] && [ "${SIGNED}" != "true" ]; then
+            echo "Gitea release publishing requires ANDROID_KEYSTORE_BASE64 and signing secrets." >&2
+            exit 1
+          fi
+          if [ "${PUBLISH_RELEASE}" = "1" ] && [ -z "${CLONE_TOKEN:-}" ]; then
+            echo "Gitea release publishing requires TMUX_GITEA_TOKEN." >&2
+            exit 1
+          fi
+
+          if [ "${SIGNED}" = "true" ]; then
+            BUILD_TASK=":app:assembleRelease"
+          else
+            BUILD_TASK=":app:assembleDebug"
+          fi
+          gradle "${BUILD_TASK}" \
             -PversionCode="${VERSION_CODE}" \
             -PversionName="${VERSION_NAME}" \
             -PrepoSlug="neatstudio/tmux-browser-android"
 
           mkdir -p release
           APK_PATH="$(find app/build/outputs/apk -name '*.apk' | sort | tail -n 1)"
-          cp "${APK_PATH}" release/tmux-android-gitea-compile-check.apk
-          ls -lh release/tmux-android-gitea-compile-check.apk
-          sha256sum release/tmux-android-gitea-compile-check.apk
-          echo "Gitea-built APK is a compile check only."
-          echo "Do not publish it as a release asset; release APKs are GitHub-built and mirrored byte-for-byte to Gitea."
+          cp "${APK_PATH}" release/tmux-android.apk
+          cp "${APK_PATH}" "release/tmux-android-${VERSION_NAME}.apk"
+          SHA256="$(sha256sum release/tmux-android.apk | awk '{print $1}')"
+          TAG="v${VERSION_NAME}"
+          APK_URL="https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/${TAG}/tmux-android.apk"
+          RELEASE_PAGE_URL="https://gitea.neatcn.com/tmux/tmux-browser-android/releases/tag/${TAG}"
+          cat > release/latest.json << JSON
+          {
+            "versionCode": ${VERSION_CODE},
+            "versionName": "${VERSION_NAME}",
+            "apkUrl": "${APK_URL}",
+            "sha256": "${SHA256}",
+            "releasePageUrl": "${RELEASE_PAGE_URL}",
+            "minSdk": 26
+          }
+          JSON
+          ls -lh release/tmux-android.apk release/latest.json
+          sha256sum release/tmux-android.apk
+
+          if [ "${PUBLISH_RELEASE}" != "1" ]; then
+            echo "Gitea main build completed as compile check."
+            exit 0
+          fi
+
+          API_ROOT="https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android"
+          RELEASE_BODY='{"tag_name":"'"${TAG}"'","target_commitish":"main","name":"tmux Android '"${VERSION_NAME}"'","body":"Android APK for tmux-ui remote testing.","draft":false,"prerelease":false}'
+          if ! curl -fsSL -X POST \
+            -H "Authorization: token ${CLONE_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "${RELEASE_BODY}" \
+            "${API_ROOT}/releases" \
+            -o /tmp/gitea-release.json; then
+            curl -fsSL -H "Authorization: token ${CLONE_TOKEN}" \
+              "${API_ROOT}/releases/tags/${TAG}" \
+              -o /tmp/gitea-release.json
+          fi
+          RELEASE_ID="$(sed -n 's/.*"id":\([0-9][0-9]*\).*/\1/p' /tmp/gitea-release.json | head -1)"
+          if [ -z "${RELEASE_ID}" ]; then
+            echo "Cannot resolve Gitea release id." >&2
+            cat /tmp/gitea-release.json >&2
+            exit 1
+          fi
+          curl -fsSL -X POST -H "Authorization: token ${CLONE_TOKEN}" \
+            -F "attachment=@release/tmux-android.apk;type=application/vnd.android.package-archive" \
+            "${API_ROOT}/releases/${RELEASE_ID}/assets?name=tmux-android.apk" \
+            -o /tmp/gitea-apk-asset.json
+          curl -fsSL -X POST -H "Authorization: token ${CLONE_TOKEN}" \
+            -F "attachment=@release/latest.json;type=application/json" \
+            "${API_ROOT}/releases/${RELEASE_ID}/assets?name=latest.json" \
+            -o /tmp/gitea-latest-asset.json
+          echo "Published Gitea release ${TAG}."

.github/workflows/android.yml

@@ -2,8 +2,6 @@ name: Android APK
 
 on:
   push:
-    branches:
-      - main
     tags:
       - "v*"
   pull_request:
@@ -27,10 +25,12 @@ jobs:
         run: |
           if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
             VERSION_NAME="${GITHUB_REF_NAME#v}"
+            IFS='.' read -r MAJOR MINOR PATCH <<< "${VERSION_NAME}"
+            VERSION_CODE=$((MAJOR * 1000000 + MINOR * 1000 + PATCH))
           else
             VERSION_NAME="0.1.${GITHUB_RUN_NUMBER}"
+            VERSION_CODE=$((1000 + GITHUB_RUN_NUMBER))
           fi
-          VERSION_CODE=$((1000 + GITHUB_RUN_NUMBER))
           echo "VERSION_NAME=${VERSION_NAME}" >> "${GITHUB_ENV}"
           echo "VERSION_CODE=${VERSION_CODE}" >> "${GITHUB_ENV}"
 

.gitignore

@@ -1,4 +1,5 @@
 .gradle/
+.ci/
 build/
 app/build/
 local.properties
@@ -6,4 +7,3 @@ signing.properties
 *.jks
 *.keystore
 release/
-

README.md

@@ -88,31 +88,32 @@ base64 -w 0 tmux-android-release.jks
 Branch builds and manual workflow runs create Actions artifacts only. Use them
 to verify grouped changes before publishing.
 
-Publish a release build by pushing a `v*` tag. A tag should be reserved for a
-coherent feature/test batch, not every small UI or text change. Tag publishing
-creates a GitHub Release with:
+Gitea is the primary build and update channel. Normal `main` pushes run the
+Gitea Android workflow for compile checks, while GitHub no longer builds every
+main push. Publish a release build by pushing a `v*` tag after a coherent
+feature/test batch, not every small UI or text change.
+
+Tag publishing can create GitHub Release assets with:
 
 ```text
 https://github.com/neatstudio/tmux-browser-android/releases/latest/download/tmux-android.apk
 https://github.com/neatstudio/tmux-browser-android/releases/latest/download/latest.json
 ```
 
-Gitea is the app's default install/update channel because phones may not be able
-to reach GitHub reliably. GitHub remains an optional public source. This Gitea
-instance does not support the GitHub-style `/releases/latest/download/...` URL,
-so the app uses the Gitea Release API as the stable Gitea update entrypoint.
+Gitea is also the app's default install/update channel because phones may not be
+able to reach GitHub reliably. GitHub remains an optional public source. This
+Gitea instance does not support the GitHub-style
+`/releases/latest/download/...` URL, so the app uses the Gitea Release API as
+the stable Gitea update entrypoint.
 
-Release APKs must be identical on GitHub and Gitea. The canonical APK is the
-GitHub Release asset built by `.github/workflows/android.yml`; publish to Gitea
-by mirroring that same `tmux-android.apk` byte-for-byte and uploading a
-Gitea-specific `latest.json` whose `apkUrl` points at the Gitea asset but whose
-`versionCode`, `versionName`, and `sha256` match the GitHub manifest. Do not use
-a separately built Gitea APK as a release asset unless it is proven to have the
-same SHA-256 as the GitHub APK. This keeps Android signatures and update
-compatibility identical no matter which platform the phone can reach.
+Release APKs on GitHub and Gitea should either be the exact same file or be
+built from the same tag with the same signing keystore, `versionCode`, and
+`versionName`. The Gitea workflow publishes release assets only when signing
+secrets are present. Unsigned Gitea builds remain compile checks and must not be
+used for automatic in-place updates.
 
-Plain branch builds only create Actions artifacts; they are useful for CI
-verification, but releases are the stable download/update channel.
+Plain branch builds are useful for CI verification, but releases are the stable
+download/update channel.
 
 Unsigned/debug workflow artifacts are useful only for smoke testing install and
 launch. Automatic in-place updates require release APKs signed with the same
@@ -123,18 +124,16 @@ incompatible package.
 
 The terminal screen connects to `/ws/terminal` and sends the upstream protocol
 messages unchanged: `attach`, `input`, `resize`, `scroll`, and `clear-history`.
-The first Android UI renders terminal output as monospace text with basic ANSI
-SGR color support. The terminal view stays bottom-aligned when output is short,
-auto-scrolls as data arrives, and adjusts its bottom inset when the soft keyboard
-opens. Rendering is throttled and the local terminal buffer is capped so opening
-busy sessions does not block the UI thread. Input typed before the terminal
-attach message is sent is queued and flushed after the WebSocket client is ready.
-It is enough for shell-oriented remote testing, but it is not yet a complete
-xterm-compatible renderer for full-screen TUIs such as `vim` or `top`.
+The Android UI renders terminal output through a lightweight screen buffer with
+cursor movement, line clearing, screen clearing, basic ANSI SGR color support,
+and throttled redraws. It is enough for shell-oriented remote testing, but it is
+not yet a complete xterm-compatible renderer for full-screen TUIs such as `vim`
+or `top`.
 
-The terminal toolbar and shortcut row include tmux prefix helpers. The app sends
-the same control bytes a keyboard would send, for example `Ctrl+B`, `Ctrl+B d`,
-`Ctrl+B c`, `Ctrl+B n`, and `Ctrl+B p`.
+The terminal input area is a native multi-line composer with a paged accessory
+bar for editing keys, control keys, tmux prefix helpers, navigation keys, and
+common shell symbols. The app sends the same control bytes a keyboard would
+send, for example `Ctrl+B`, `Ctrl+B d`, `Ctrl+B c`, `Ctrl+B n`, and `Ctrl+B p`.
 
 All app features are native Android controls. Complex server objects such as
 preferences, timeline events, group messages, and image metadata currently use

app/build.gradle.kts

@@ -14,6 +14,8 @@ val defaultGithubUpdateUrl = providers.gradleProperty("defaultGithubUpdateUrl")
     .orElse("https://github.com/${repoSlug.get()}/releases/latest/download/latest.json")
 val defaultGiteaUpdateUrl = providers.gradleProperty("defaultGiteaUpdateUrl")
     .orElse("https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android/releases/latest")
+val defaultPreviewUpdateUrl = providers.gradleProperty("defaultPreviewUpdateUrl")
+    .orElse("https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/preview/latest.json")
 val defaultApkUrl = providers.gradleProperty("defaultApkUrl")
     .orElse("https://github.com/${repoSlug.get()}/releases/latest/download/tmux-android.apk")
 val defaultReleasePageUrl = providers.gradleProperty("defaultReleasePageUrl")
@@ -40,6 +42,7 @@ android {
         buildConfigField("String", "DEFAULT_UPDATE_URL", "\"${defaultUpdateUrl.get()}\"")
         buildConfigField("String", "DEFAULT_GITHUB_UPDATE_URL", "\"${defaultGithubUpdateUrl.get()}\"")
         buildConfigField("String", "DEFAULT_GITEA_UPDATE_URL", "\"${defaultGiteaUpdateUrl.get()}\"")
+        buildConfigField("String", "DEFAULT_PREVIEW_UPDATE_URL", "\"${defaultPreviewUpdateUrl.get()}\"")
         buildConfigField("String", "DEFAULT_APK_URL", "\"${defaultApkUrl.get()}\"")
         buildConfigField("String", "DEFAULT_RELEASE_PAGE_URL", "\"${defaultReleasePageUrl.get()}\"")
     }

app/src/main/java/com/neatstudio/tmuxandroid/AppEventSocketClient.java

@@ -4,6 +4,7 @@ import android.util.Base64;
 
 import java.io.BufferedInputStream;
 import java.io.BufferedOutputStream;
+import java.net.InetSocketAddress;
 import java.net.Socket;
 import java.net.URI;
 import java.nio.charset.StandardCharsets;
@@ -14,16 +15,22 @@ import java.util.Arrays;
 import javax.net.ssl.SSLSocketFactory;
 
 final class AppEventSocketClient {
+    private static final long HEARTBEAT_INTERVAL_MS = 15000L;
+    private static final int SOCKET_CONNECT_TIMEOUT_MS = 10000;
+    private static final int SOCKET_READ_TIMEOUT_MS = 45000;
+
     interface Listener {
         void onMessage(String text);
         void onClosed();
     }
 
     private final Listener listener;
+    private final Object writeLock = new Object();
     private Socket socket;
     private BufferedInputStream input;
     private BufferedOutputStream output;
     private volatile boolean closed;
+    private Thread heartbeatThread;
 
     AppEventSocketClient(Listener listener) {
         this.listener = listener;
@@ -40,12 +47,11 @@ final class AppEventSocketClient {
             sendFrame(8, new byte[0]);
         } catch (Exception ignored) {
         }
-        try {
-            if (socket != null) {
-                socket.close();
-            }
-        } catch (Exception ignored) {
-        }
+        closeSocketQuietly();
+    }
+
+    boolean isClosed() {
+        return closed;
     }
 
     private void run(String baseUrl) {
@@ -55,6 +61,7 @@ final class AppEventSocketClient {
             input = new BufferedInputStream(socket.getInputStream());
             output = new BufferedOutputStream(socket.getOutputStream());
             handshake(uri);
+            startHeartbeat();
             while (!closed) {
                 Frame frame = readFrame();
                 if (frame.opcode == 1) {
@@ -69,12 +76,7 @@ final class AppEventSocketClient {
         } finally {
             closed = true;
             listener.onClosed();
-            try {
-                if (socket != null) {
-                    socket.close();
-                }
-            } catch (Exception ignored) {
-            }
+            closeSocketQuietly();
         }
     }
 
@@ -91,10 +93,39 @@ final class AppEventSocketClient {
         if (port == -1) {
             port = "wss".equalsIgnoreCase(uri.getScheme()) ? 443 : 80;
         }
+        Socket raw = new Socket();
+        raw.connect(new InetSocketAddress(uri.getHost(), port), SOCKET_CONNECT_TIMEOUT_MS);
+        Socket connected;
         if ("wss".equalsIgnoreCase(uri.getScheme())) {
-            return SSLSocketFactory.getDefault().createSocket(uri.getHost(), port);
+            connected = ((SSLSocketFactory) SSLSocketFactory.getDefault())
+                    .createSocket(raw, uri.getHost(), port, true);
+        } else {
+            connected = raw;
         }
-        return new Socket(uri.getHost(), port);
+        connected.setKeepAlive(true);
+        connected.setTcpNoDelay(true);
+        connected.setSoTimeout(SOCKET_READ_TIMEOUT_MS);
+        return connected;
+    }
+
+    private void startHeartbeat() {
+        heartbeatThread = new Thread(() -> {
+            while (!closed) {
+                try {
+                    Thread.sleep(HEARTBEAT_INTERVAL_MS);
+                    if (!closed) {
+                        sendFrame(9, new byte[0]);
+                    }
+                } catch (InterruptedException ignored) {
+                    Thread.currentThread().interrupt();
+                    return;
+                } catch (Exception error) {
+                    closeSocketQuietly();
+                    return;
+                }
+            }
+        }, "app-events-ws-heartbeat");
+        heartbeatThread.start();
     }
 
     private void handshake(URI uri) throws Exception {
@@ -181,32 +212,47 @@ final class AppEventSocketClient {
     }
 
     private void sendFrame(int opcode, byte[] payload) throws Exception {
-        if (output == null) {
-            return;
-        }
-        output.write(0x80 | opcode);
-        byte[] mask = new byte[4];
-        new SecureRandom().nextBytes(mask);
-        int length = payload.length;
-        if (length < 126) {
-            output.write(0x80 | length);
-        } else if (length <= 0xffff) {
-            output.write(0x80 | 126);
-            output.write((length >>> 8) & 0xff);
-            output.write(length & 0xff);
-        } else {
-            output.write(0x80 | 127);
-            for (int i = 7; i >= 0; i--) {
-                output.write((length >>> (8 * i)) & 0xff);
+        synchronized (writeLock) {
+            if (output == null) {
+                return;
             }
+            output.write(0x80 | opcode);
+            byte[] mask = new byte[4];
+            new SecureRandom().nextBytes(mask);
+            int length = payload.length;
+            if (length < 126) {
+                output.write(0x80 | length);
+            } else if (length <= 0xffff) {
+                output.write(0x80 | 126);
+                output.write((length >>> 8) & 0xff);
+                output.write(length & 0xff);
+            } else {
+                output.write(0x80 | 127);
+                for (int i = 7; i >= 0; i--) {
+                    output.write((length >>> (8 * i)) & 0xff);
+                }
+            }
+            output.write(mask);
+            byte[] masked = Arrays.copyOf(payload, payload.length);
+            for (int i = 0; i < masked.length; i++) {
+                masked[i] = (byte) (masked[i] ^ mask[i % 4]);
+            }
+            output.write(masked);
+            output.flush();
         }
-        output.write(mask);
-        byte[] masked = Arrays.copyOf(payload, payload.length);
-        for (int i = 0; i < masked.length; i++) {
-            masked[i] = (byte) (masked[i] ^ mask[i % 4]);
+    }
+
+    private void closeSocketQuietly() {
+        if (heartbeatThread != null) {
+            heartbeatThread.interrupt();
+            heartbeatThread = null;
+        }
+        try {
+            if (socket != null) {
+                socket.close();
+            }
+        } catch (Exception ignored) {
         }
-        output.write(masked);
-        output.flush();
     }
 
     private static final class Frame {

app/src/main/java/com/neatstudio/tmuxandroid/ConversationMessage.java

@@ -0,0 +1,85 @@
+package com.neatstudio.tmuxandroid;
+
+import org.json.JSONObject;
+
+final class ConversationMessage {
+    final String messageId;
+    final String sessionName;
+    final String role;
+    final String contentType;
+    final String content;
+    final String status;
+    final String toolName;
+    final String parentMessageId;
+    final String createdAt;
+    final boolean local;
+
+    ConversationMessage(
+            String messageId,
+            String sessionName,
+            String role,
+            String contentType,
+            String content,
+            String status,
+            String toolName,
+            String parentMessageId,
+            String createdAt,
+            boolean local
+    ) {
+        this.messageId = messageId;
+        this.sessionName = sessionName;
+        this.role = role;
+        this.contentType = contentType;
+        this.content = content;
+        this.status = status;
+        this.toolName = toolName;
+        this.parentMessageId = parentMessageId;
+        this.createdAt = createdAt;
+        this.local = local;
+    }
+
+    static ConversationMessage fromJson(JSONObject object) {
+        return new ConversationMessage(
+                value(object, "messageId", object.optString("id", "")),
+                object.optString("sessionName", ""),
+                object.optString("role", "assistant"),
+                object.optString("contentType", "text"),
+                object.optString("content", ""),
+                object.optString("status", "complete"),
+                object.optString("toolName", ""),
+                value(object, "parentMessageId", ""),
+                object.optString("createdAt", ""),
+                false
+        );
+    }
+
+    static ConversationMessage localUser(String sessionName, String content) {
+        long now = System.currentTimeMillis();
+        return new ConversationMessage(
+                "local-" + now,
+                sessionName,
+                "user",
+                "text",
+                content,
+                "sending",
+                "",
+                "",
+                "~" + now,
+                true
+        );
+    }
+
+    boolean isTool() {
+        return "tool".equals(role)
+                || "tool".equals(contentType)
+                || "command".equals(contentType)
+                || "code".equals(contentType);
+    }
+
+    private static String value(JSONObject object, String key, String fallback) {
+        if (!object.has(key) || object.isNull(key)) {
+            return fallback;
+        }
+        return object.optString(key, fallback);
+    }
+}

app/src/main/java/com/neatstudio/tmuxandroid/TerminalScreenBuffer.java

@@ -4,16 +4,22 @@ import android.graphics.Color;
 import android.graphics.Typeface;
 import android.text.SpannableStringBuilder;
 import android.text.Spanned;
+import android.text.TextPaint;
 import android.text.style.BackgroundColorSpan;
+import android.text.style.ClickableSpan;
 import android.text.style.ForegroundColorSpan;
 import android.text.style.StyleSpan;
+import android.view.View;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Locale;
+import java.util.Set;
 
 final class TerminalScreenBuffer {
     private static final int DEFAULT_FG = 0xffe6ebf2;
     private static final int DEFAULT_BG = Color.TRANSPARENT;
+    private static final int TERMINAL_BG = 0xff0b0e13;
 
     private int cols;
     private int rows;
@@ -27,6 +33,11 @@ final class TerminalScreenBuffer {
     private int fg = DEFAULT_FG;
     private int bg = DEFAULT_BG;
     private boolean bold;
+    private boolean dim;
+
+    interface FocusToggle {
+        void toggle(String key);
+    }
 
     TerminalScreenBuffer(int cols, int rows) {
         resize(cols, rows);
@@ -35,9 +46,6 @@ final class TerminalScreenBuffer {
     void resize(int nextCols, int nextRows) {
         nextCols = Math.max(1, nextCols);
         nextRows = Math.max(1, nextRows);
-        Cell[][] previous = cells;
-        int previousRows = rows;
-        int previousCols = cols;
         cols = nextCols;
         rows = nextRows;
         cells = new Cell[rows][cols];
@@ -46,21 +54,11 @@ final class TerminalScreenBuffer {
                 cells[row][col] = new Cell();
             }
         }
-        if (previous != null) {
-            int copyRows = Math.min(previousRows, rows);
-            int copyCols = Math.min(previousCols, cols);
-            int previousStart = Math.max(0, previousRows - copyRows);
-            int nextStart = Math.max(0, rows - copyRows);
-            for (int row = 0; row < copyRows; row++) {
-                for (int col = 0; col < copyCols; col++) {
-                    cells[nextStart + row][col].copyFrom(previous[previousStart + row][col]);
-                }
-            }
-        }
-        cursorRow = clamp(cursorRow, 0, rows - 1);
-        cursorCol = clamp(cursorCol, 0, cols - 1);
-        savedRow = clamp(savedRow, 0, rows - 1);
-        savedCol = clamp(savedCol, 0, cols - 1);
+        cursorRow = 0;
+        cursorCol = 0;
+        savedRow = 0;
+        savedCol = 0;
+        wrapPending = false;
     }
 
     void clear() {
@@ -74,6 +72,7 @@ final class TerminalScreenBuffer {
         fg = DEFAULT_FG;
         bg = DEFAULT_BG;
         bold = false;
+        dim = false;
     }
 
     void write(String text) {
@@ -121,16 +120,200 @@ final class TerminalScreenBuffer {
     }
 
     CharSequence render() {
+        return renderRows(0, rows);
+    }
+
+    CharSequence renderBody() {
+        return renderRows(0, Math.max(0, rows - 1));
+    }
+
+    CharSequence renderStatusLine() {
+        return renderRows(Math.max(0, rows - 1), rows);
+    }
+
+    private CharSequence renderRows(int startRow, int endRow) {
         SpannableStringBuilder output = new SpannableStringBuilder();
-        for (int row = 0; row < rows; row++) {
+        for (int row = startRow; row < endRow; row++) {
             appendRow(output, row);
-            if (row + 1 < rows) {
+            if (row + 1 < endRow) {
                 output.append('\n');
             }
         }
         return output;
     }
 
+    String renderTail(int maxRows) {
+        List<String> visible = new ArrayList<>();
+        for (int row = rows - 1; row >= 0 && visible.size() < maxRows; row--) {
+            String text = rowText(row).trim();
+            if (!text.isEmpty()) {
+                visible.add(0, text);
+            }
+        }
+        if (visible.isEmpty()) {
+            return "Waiting for terminal output";
+        }
+        return String.join("\n", visible);
+    }
+
+    CharSequence renderFocused(Set<String> expandedBlocks, FocusToggle toggle) {
+        SpannableStringBuilder output = new SpannableStringBuilder();
+        int row = 0;
+        while (row < rows) {
+            String text = rowText(row).trim();
+            if (!isCollapsibleHeader(text)) {
+                if (text.isEmpty()) {
+                    if (output.length() > 0) {
+                        output.append('\n');
+                    }
+                } else {
+                    appendStyledRow(output, row);
+                }
+                row++;
+                continue;
+            }
+
+            int startRow = row;
+            List<String> hiddenRows = new ArrayList<>();
+            hiddenRows.add(text);
+            row++;
+            while (row < rows) {
+                String next = rowText(row).trim();
+                if (next.isEmpty() || isTopLevelLine(next)) {
+                    break;
+                }
+                hiddenRows.add(next);
+                row++;
+            }
+            appendFocusBlock(output, hiddenRows, startRow, row - 1, expandedBlocks, toggle);
+        }
+        if (output.length() == 0) {
+            output.append("Waiting for terminal output");
+        }
+        return output;
+    }
+
+    private boolean isCollapsibleHeader(String text) {
+        boolean activity = text.startsWith("• ") || text.startsWith("● ");
+        String header = stripActivityMarker(text);
+        return activity && (header.startsWith("Ran ")
+                || header.equals("Explored")
+                || header.startsWith("Explored ")
+                || header.startsWith("Searched ")
+                || header.startsWith("Read ")
+                || header.startsWith("List ")
+                || header.startsWith("Viewed ")
+                || header.startsWith("Opened ")
+                || header.startsWith("Fetched ")
+                || header.startsWith("Downloaded ")
+                || header.startsWith("Wrote ")
+                || header.startsWith("Edited ")
+                || header.startsWith("Applied ")
+                || header.startsWith("Updated ")
+                || header.startsWith("Checked ")
+                || header.startsWith("Inspected ")
+                || header.startsWith("Waited ")
+                || header.startsWith("Working")
+                || header.startsWith("Stop hook"))
+                || text.startsWith("─ Worked for ");
+    }
+
+    private boolean isTopLevelLine(String text) {
+        return text.startsWith("• ")
+                || text.startsWith("● ")
+                || text.startsWith("› ")
+                || text.startsWith("> ")
+                || text.startsWith("─ ")
+                || isCollapsibleHeader(text);
+    }
+
+    private String stripActivityMarker(String text) {
+        if (text.startsWith("• ") || text.startsWith("● ")) {
+            return text.substring(2).trim();
+        }
+        return text;
+    }
+
+    private void appendFocusBlock(
+            SpannableStringBuilder output,
+            List<String> lines,
+            int startRow,
+            int endRow,
+            Set<String> expandedBlocks,
+            FocusToggle toggle
+    ) {
+        String key = startRow + ":" + endRow;
+        boolean expanded = expandedBlocks.contains(key);
+        String summary = focusSummary(lines);
+        int actionStart = output.length();
+        appendLine(output, (expanded ? "▼ " : "▶ ") + summary);
+        int actionEnd = output.length();
+        output.setSpan(new ClickableSpan() {
+            @Override
+            public void onClick(View widget) {
+                toggle.toggle(key);
+            }
+
+            @Override
+            public void updateDrawState(TextPaint paint) {
+                paint.setColor(0xff67da91);
+                paint.setUnderlineText(false);
+                paint.setFakeBoldText(true);
+            }
+        }, actionStart, actionEnd, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
+        if (expanded) {
+            for (String line : lines) {
+                appendLine(output, "  " + line);
+            }
+        }
+    }
+
+    private String focusSummary(List<String> lines) {
+        String first = stripActivityMarker(lines.get(0));
+        String joined = String.join(" ", lines).toLowerCase(Locale.ROOT);
+        String type;
+        if (first.startsWith("Explored") || first.startsWith("Searched")
+                || first.startsWith("Read ") || first.startsWith("List ")
+                || first.startsWith("Viewed ") || first.startsWith("Inspected ")) {
+            type = "Explored";
+        } else if (first.startsWith("Working") || first.startsWith("Stop hook")
+                || first.startsWith("─ Worked for ")) {
+            type = "Status";
+        } else if (joined.contains("error") || joined.contains("failed") || joined.contains("exception")) {
+            type = "Command failed";
+        } else {
+            type = "Command output";
+        }
+        return type + " · " + lines.size() + " lines · " + compactSummary(first, 48);
+    }
+
+    private String compactSummary(String text, int maxChars) {
+        String compact = text.replaceAll("\\s+", " ").trim();
+        if (compact.length() <= maxChars) {
+            return compact;
+        }
+        return compact.substring(0, maxChars - 1) + "…";
+    }
+
+    private void appendLine(SpannableStringBuilder output, String text) {
+        if (output.length() > 0) {
+            output.append('\n');
+        }
+        output.append(text);
+    }
+
+    private void appendStyledRow(SpannableStringBuilder output, int row) {
+        if (output.length() > 0) {
+            output.append('\n');
+        }
+        int limit = cols;
+        while (limit > 0 && cells[row][limit - 1].value == ' '
+                && cells[row][limit - 1].bg == DEFAULT_BG) {
+            limit--;
+        }
+        appendRow(output, row, limit);
+    }
+
     private int handleEscape(String text, int index) {
         if (index + 1 >= text.length()) {
             return -1;
@@ -257,10 +440,14 @@ final class TerminalScreenBuffer {
                 fg = DEFAULT_FG;
                 bg = DEFAULT_BG;
                 bold = false;
+                dim = false;
             } else if (value == 1) {
                 bold = true;
+            } else if (value == 2) {
+                dim = true;
             } else if (value == 22) {
                 bold = false;
+                dim = false;
             } else if (value == 39) {
                 fg = DEFAULT_FG;
             } else if (value == 49) {
@@ -302,14 +489,34 @@ final class TerminalScreenBuffer {
             wrapPending = false;
             newLine();
         }
-        cells[cursorRow][cursorCol].set(value, fg, bg, bold);
-        if (cursorCol == cols - 1) {
+        int width = isWideCharacter(value) ? 2 : 1;
+        if (width == 2 && cursorCol == cols - 1) {
+            newLine();
+        }
+        cells[cursorRow][cursorCol].set(value, fg, bg, bold, dim);
+        if (width == 2) {
+            cells[cursorRow][cursorCol + 1].setContinuation(fg, bg, bold, dim);
+        }
+        if (cursorCol + width >= cols) {
+            cursorCol = cols - 1;
             wrapPending = true;
         } else {
-            cursorCol++;
+            cursorCol += width;
         }
     }
 
+    private boolean isWideCharacter(char value) {
+        return value >= '\u1100' && (value <= '\u115f'
+                || value == '\u2329' || value == '\u232a'
+                || (value >= '\u2e80' && value <= '\ua4cf' && value != '\u303f')
+                || (value >= '\uac00' && value <= '\ud7a3')
+                || (value >= '\uf900' && value <= '\ufaff')
+                || (value >= '\ufe10' && value <= '\ufe19')
+                || (value >= '\ufe30' && value <= '\ufe6f')
+                || (value >= '\uff00' && value <= '\uff60')
+                || (value >= '\uffe0' && value <= '\uffe6'));
+    }
+
     private void newLine() {
         wrapPending = false;
         cursorRow++;
@@ -446,22 +653,32 @@ final class TerminalScreenBuffer {
     }
 
     private void appendRow(SpannableStringBuilder output, int row) {
+        appendRow(output, row, cols);
+    }
+
+    private void appendRow(SpannableStringBuilder output, int row, int limit) {
         int col = 0;
-        while (col < cols) {
+        while (col < limit) {
             Cell first = cells[row][col];
             int start = output.length();
             int fgColor = first.fg;
             int bgColor = first.bg;
             boolean isBold = first.bold;
-            while (col < cols) {
+            boolean isDim = first.dim;
+            while (col < limit) {
                 Cell cell = cells[row][col];
-                if (cell.fg != fgColor || cell.bg != bgColor || cell.bold != isBold) {
+                if (cell.fg != fgColor || cell.bg != bgColor || cell.bold != isBold || cell.dim != isDim) {
                     break;
                 }
-                output.append(cell.value);
+                if (!cell.continuation) {
+                    output.append(cell.value);
+                }
                 col++;
             }
             int end = output.length();
+            if (isDim) {
+                fgColor = blendColor(fgColor, bgColor == DEFAULT_BG ? TERMINAL_BG : bgColor, 0.55f);
+            }
             output.setSpan(new ForegroundColorSpan(fgColor), start, end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
             if (bgColor != DEFAULT_BG) {
                 output.setSpan(new BackgroundColorSpan(bgColor), start, end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
@@ -472,6 +689,17 @@ final class TerminalScreenBuffer {
         }
     }
 
+    private String rowText(int row) {
+        StringBuilder text = new StringBuilder(cols);
+        for (int col = 0; col < cols; col++) {
+            Cell cell = cells[row][col];
+            if (!cell.continuation) {
+                text.append(cell.value);
+            }
+        }
+        return text.toString();
+    }
+
     private void saveCursor() {
         savedRow = cursorRow;
         savedCol = cursorCol;
@@ -613,6 +841,15 @@ final class TerminalScreenBuffer {
         return value == 0 ? 0 : 55 + value * 40;
     }
 
+    private static int blendColor(int foreground, int background, float foregroundRatio) {
+        float backgroundRatio = 1f - foregroundRatio;
+        return Color.rgb(
+                Math.round(Color.red(foreground) * foregroundRatio + Color.red(background) * backgroundRatio),
+                Math.round(Color.green(foreground) * foregroundRatio + Color.green(background) * backgroundRatio),
+                Math.round(Color.blue(foreground) * foregroundRatio + Color.blue(background) * backgroundRatio)
+        );
+    }
+
     private static int clamp(int value, int min, int max) {
         return Math.max(min, Math.min(max, value));
     }
@@ -622,19 +859,34 @@ final class TerminalScreenBuffer {
         int fg = DEFAULT_FG;
         int bg = DEFAULT_BG;
         boolean bold;
+        boolean dim;
+        boolean continuation;
 
         void clear() {
             value = ' ';
             fg = DEFAULT_FG;
             bg = DEFAULT_BG;
             bold = false;
+            dim = false;
+            continuation = false;
         }
 
-        void set(char nextValue, int nextFg, int nextBg, boolean nextBold) {
+        void set(char nextValue, int nextFg, int nextBg, boolean nextBold, boolean nextDim) {
             value = nextValue;
             fg = nextFg;
             bg = nextBg;
             bold = nextBold;
+            dim = nextDim;
+            continuation = false;
+        }
+
+        void setContinuation(int nextFg, int nextBg, boolean nextBold, boolean nextDim) {
+            value = ' ';
+            fg = nextFg;
+            bg = nextBg;
+            bold = nextBold;
+            dim = nextDim;
+            continuation = true;
         }
 
         void copyFrom(Cell other) {
@@ -642,6 +894,8 @@ final class TerminalScreenBuffer {
             fg = other.fg;
             bg = other.bg;
             bold = other.bold;
+            dim = other.dim;
+            continuation = other.continuation;
         }
     }
 }

app/src/main/java/com/neatstudio/tmuxandroid/TerminalSocketClient.java

@@ -6,6 +6,7 @@ import org.json.JSONObject;
 
 import java.io.BufferedInputStream;
 import java.io.BufferedOutputStream;
+import java.net.InetSocketAddress;
 import java.net.Socket;
 import java.net.URI;
 import java.nio.charset.StandardCharsets;
@@ -19,6 +20,10 @@ import java.util.concurrent.RejectedExecutionException;
 import javax.net.ssl.SSLSocketFactory;
 
 final class TerminalSocketClient {
+    private static final long HEARTBEAT_INTERVAL_MS = 15000L;
+    private static final int SOCKET_CONNECT_TIMEOUT_MS = 10000;
+    private static final int SOCKET_READ_TIMEOUT_MS = 45000;
+
     interface Listener {
         void onConnected();
         void onOutput(String data);
@@ -35,6 +40,7 @@ final class TerminalSocketClient {
     private BufferedOutputStream output;
     private volatile boolean closed;
     private Thread thread;
+    private Thread heartbeatThread;
 
     TerminalSocketClient(Listener listener) {
         this.listener = listener;
@@ -97,6 +103,7 @@ final class TerminalSocketClient {
                     "rows", rows
             );
             listener.onConnected();
+            startHeartbeat();
             readLoop();
         } catch (Exception error) {
             if (!closed) {
@@ -123,10 +130,39 @@ final class TerminalSocketClient {
         if (port == -1) {
             port = "wss".equalsIgnoreCase(uri.getScheme()) ? 443 : 80;
         }
+        Socket raw = new Socket();
+        raw.connect(new InetSocketAddress(uri.getHost(), port), SOCKET_CONNECT_TIMEOUT_MS);
+        Socket connected;
         if ("wss".equalsIgnoreCase(uri.getScheme())) {
-            return SSLSocketFactory.getDefault().createSocket(uri.getHost(), port);
+            connected = ((SSLSocketFactory) SSLSocketFactory.getDefault())
+                    .createSocket(raw, uri.getHost(), port, true);
+        } else {
+            connected = raw;
         }
-        return new Socket(uri.getHost(), port);
+        connected.setKeepAlive(true);
+        connected.setTcpNoDelay(true);
+        connected.setSoTimeout(SOCKET_READ_TIMEOUT_MS);
+        return connected;
+    }
+
+    private void startHeartbeat() {
+        heartbeatThread = new Thread(() -> {
+            while (!closed) {
+                try {
+                    Thread.sleep(HEARTBEAT_INTERVAL_MS);
+                    if (!closed) {
+                        sendFrame(9, new byte[0]);
+                    }
+                } catch (InterruptedException ignored) {
+                    Thread.currentThread().interrupt();
+                    return;
+                } catch (Exception error) {
+                    closeSocketQuietly();
+                    return;
+                }
+            }
+        }, "terminal-ws-heartbeat");
+        heartbeatThread.start();
     }
 
     private void handshake(URI uri) throws Exception {
@@ -279,6 +315,10 @@ final class TerminalSocketClient {
     }
 
     private void closeSocketQuietly() {
+        if (heartbeatThread != null) {
+            heartbeatThread.interrupt();
+            heartbeatThread = null;
+        }
         try {
             if (socket != null) {
                 socket.close();

app/src/main/java/com/neatstudio/tmuxandroid/UpdateManager.java

@@ -80,6 +80,14 @@ final class UpdateManager {
         );
     }
 
+    void checkPreview(boolean userInitiated) {
+        startUpdateCheck(
+                userInitiated,
+                "Preview",
+                new String[]{BuildConfig.DEFAULT_PREVIEW_UPDATE_URL}
+        );
+    }
+
     void checkWithFallback(boolean userInitiated) {
         startUpdateCheck(
                 userInitiated,

app/src/main/res/values/styles.xml

@@ -1,11 +1,12 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <style name="AppTheme" parent="android:style/Theme.Material.Light.NoActionBar">
+    <style name="AppTheme" parent="android:style/Theme.Material.NoActionBar">
         <item name="android:fontFamily">sans</item>
         <item name="android:windowLightStatusBar">false</item>
-        <item name="android:statusBarColor">#111418</item>
-        <item name="android:navigationBarColor">#111418</item>
+        <item name="android:windowLightNavigationBar">false</item>
+        <item name="android:statusBarColor">#090B0D</item>
+        <item name="android:navigationBarColor">#090B0D</item>
+        <item name="android:windowBackground">#090B0D</item>
         <item name="android:windowActionModeOverlay">true</item>
     </style>
 </resources>
-

docs/preview-build.md

@@ -0,0 +1,41 @@
+# Preview APK workflow
+
+Use this path for fast UI testing before a formal tag/release.
+
+The preview build is a debug APK with package id `com.neatstudio.tmuxandroid.debug`.
+It can be installed next to the formal release app, so preview version codes do not
+block future formal releases.
+
+## Build locally
+
+```bash
+scripts/setup-android-local.sh
+scripts/build-preview-apk.sh
+```
+
+Output:
+
+- `release/preview/tmux-android-preview.apk`
+- `release/preview/latest.json`
+
+## Upload to Gitea preview release
+
+```bash
+scripts/upload-gitea-preview.sh
+```
+
+The script reads `TMUX_GITEA_TOKEN` or prompts for a hidden token.
+Before uploading, it deletes existing assets with the same names, so the preview
+release keeps only one current APK and one current manifest.
+
+Fixed preview URLs:
+
+- Manifest: `https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/preview/latest.json`
+- APK: `https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/preview/tmux-android-preview.apk`
+
+## Notes
+
+- Preview APKs are not formal releases and should not be tagged as `v*`.
+- Preview uses debug signing unless a separate debug signing setup is added.
+- The installed preview app is separate from the release app because Gradle applies
+  `applicationIdSuffix = ".debug"` for debug builds.

scripts/build-preview-apk.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CI_DIR="${ROOT_DIR}/.ci"
+GRADLE_VERSION="${GRADLE_VERSION:-8.10.2}"
+GRADLE_HOME="${CI_DIR}/gradle-${GRADLE_VERSION}"
+ANDROID_HOME="${ANDROID_HOME:-${CI_DIR}/android-sdk}"
+CMDLINE_TOOLS="${ANDROID_HOME}/cmdline-tools/latest"
+BUILD_NUMBER="${BUILD_NUMBER:-$(date -u +%m%d%H%M)}"
+VERSION_CODE="${VERSION_CODE:-$((900000000 + 10#${BUILD_NUMBER}))}"
+VERSION_NAME="${VERSION_NAME:-preview-${BUILD_NUMBER}}"
+
+if [ ! -x "${GRADLE_HOME}/bin/gradle" ] || [ ! -x "${CMDLINE_TOOLS}/bin/sdkmanager" ]; then
+  "${ROOT_DIR}/scripts/setup-android-local.sh"
+fi
+
+export ANDROID_HOME
+export ANDROID_SDK_ROOT="${ANDROID_HOME}"
+export PATH="${GRADLE_HOME}/bin:${CMDLINE_TOOLS}/bin:${ANDROID_HOME}/platform-tools:${PATH}"
+
+cd "${ROOT_DIR}"
+gradle :app:assembleDebug \
+  -PversionCode="${VERSION_CODE}" \
+  -PversionName="${VERSION_NAME}" \
+  -PrepoSlug="neatstudio/tmux-browser-android"
+
+OUT_DIR="${ROOT_DIR}/release/preview"
+mkdir -p "${OUT_DIR}"
+APK_PATH="$(find app/build/outputs/apk/debug -name '*.apk' | sort | tail -n 1)"
+cp "${APK_PATH}" "${OUT_DIR}/tmux-android-preview.apk"
+SHA256="$(sha256sum "${OUT_DIR}/tmux-android-preview.apk" | cut -d " " -f 1)"
+
+cat > "${OUT_DIR}/latest.json" <<JSON
+{
+  "versionCode": ${VERSION_CODE},
+  "versionName": "${VERSION_NAME}",
+  "apkUrl": "https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/preview/tmux-android-preview.apk",
+  "sha256": "${SHA256}",
+  "releasePageUrl": "https://gitea.neatcn.com/tmux/tmux-browser-android/releases/tag/preview",
+  "minSdk": 26
+}
+JSON
+
+ls -lh "${OUT_DIR}/tmux-android-preview.apk" "${OUT_DIR}/latest.json"
+sha256sum "${OUT_DIR}/tmux-android-preview.apk"

scripts/mirror-gitea-release.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: scripts/mirror-gitea-release.sh TAG APK_PATH [VERSION_CODE] [VERSION_NAME]
+
+Mirrors an already-built APK to the Gitea release for TAG and uploads a
+Gitea-specific latest.json.
+
+Token source:
+  TMUX_GITEA_TOKEN environment variable, or hidden stdin prompt.
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+if [ "$#" -lt 2 ] || [ "$#" -gt 4 ]; then
+  usage
+  exit 2
+fi
+
+TAG="$1"
+APK_PATH="$2"
+VERSION_NAME="${4:-${TAG#v}}"
+
+if [ ! -f "$APK_PATH" ]; then
+  echo "APK not found: $APK_PATH" >&2
+  exit 1
+fi
+
+if [ -n "${3:-}" ]; then
+  VERSION_CODE="$3"
+else
+  IFS=. read -r MAJOR MINOR PATCH <<EOF
+$VERSION_NAME
+EOF
+  VERSION_CODE=$((MAJOR * 1000000 + MINOR * 1000 + PATCH))
+fi
+
+TOKEN="${TMUX_GITEA_TOKEN:-}"
+if [ -z "$TOKEN" ]; then
+  printf "Gitea token: " >&2
+  IFS= read -rs TOKEN
+  printf "\n" >&2
+fi
+
+if [ -z "$TOKEN" ]; then
+  echo "Missing Gitea token." >&2
+  exit 1
+fi
+
+API_ROOT="https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android"
+RELEASE_PAGE_URL="https://gitea.neatcn.com/tmux/tmux-browser-android/releases/tag/${TAG}"
+APK_URL="https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/${TAG}/tmux-android.apk"
+SHA256="$(sha256sum "$APK_PATH" | cut -d " " -f 1)"
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+LATEST_JSON="${WORK_DIR}/latest.json"
+cat > "$LATEST_JSON" <<JSON
+{
+  "versionCode": ${VERSION_CODE},
+  "versionName": "${VERSION_NAME}",
+  "apkUrl": "${APK_URL}",
+  "sha256": "${SHA256}",
+  "releasePageUrl": "${RELEASE_PAGE_URL}",
+  "minSdk": 26
+}
+JSON
+
+RELEASE_JSON="${WORK_DIR}/release.json"
+BODY='{"tag_name":"'"${TAG}"'","target_commitish":"main","name":"tmux Android '"${VERSION_NAME}"'","body":"Android APK for tmux-ui remote testing.","draft":false,"prerelease":false}'
+
+if ! curl -fsSL \
+  -X POST \
+  -H "Authorization: token ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "$BODY" \
+  "${API_ROOT}/releases" \
+  -o "$RELEASE_JSON"; then
+  curl -fsSL \
+    -H "Authorization: token ${TOKEN}" \
+    "${API_ROOT}/releases/tags/${TAG}" \
+    -o "$RELEASE_JSON"
+fi
+
+RELEASE_ID="$(sed -n 's/^{"id":\([0-9][0-9]*\),.*/\1/p' "$RELEASE_JSON" | head -1)"
+if [ -z "$RELEASE_ID" ]; then
+  echo "Cannot resolve Gitea release id for ${TAG}." >&2
+  exit 1
+fi
+
+upload_asset() {
+  local file="$1"
+  local name="$2"
+  local type="$3"
+  curl -fsSL \
+    -X POST \
+    -H "Authorization: token ${TOKEN}" \
+    -F "attachment=@${file};type=${type}" \
+    "${API_ROOT}/releases/${RELEASE_ID}/assets?name=${name}" \
+    -o "${WORK_DIR}/${name}.asset.json"
+}
+
+upload_asset "$APK_PATH" "tmux-android.apk" "application/vnd.android.package-archive"
+upload_asset "$LATEST_JSON" "latest.json" "application/json"
+
+echo "Mirrored ${TAG} to Gitea release ${RELEASE_ID}"
+echo "versionCode=${VERSION_CODE}"
+echo "versionName=${VERSION_NAME}"
+echo "sha256=${SHA256}"

scripts/setup-android-local.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CI_DIR="${ROOT_DIR}/.ci"
+GRADLE_VERSION="${GRADLE_VERSION:-8.10.2}"
+ANDROID_TOOLS_ZIP="${ANDROID_TOOLS_ZIP:-commandlinetools-linux-11076708_latest.zip}"
+GRADLE_HOME="${CI_DIR}/gradle-${GRADLE_VERSION}"
+ANDROID_HOME="${ANDROID_HOME:-${CI_DIR}/android-sdk}"
+CMDLINE_TOOLS="${ANDROID_HOME}/cmdline-tools/latest"
+
+mkdir -p "${CI_DIR}"
+
+if [ ! -x "${GRADLE_HOME}/bin/gradle" ]; then
+  curl -fSL --connect-timeout 20 --retry 3 --retry-delay 2 --max-time 600 \
+    -o "${CI_DIR}/gradle.zip" \
+    "https://services.gradle.org/distributions/gradle-${GRADLE_VERSION}-bin.zip"
+  unzip -q "${CI_DIR}/gradle.zip" -d "${CI_DIR}"
+fi
+
+if [ ! -x "${CMDLINE_TOOLS}/bin/sdkmanager" ]; then
+  mkdir -p "${ANDROID_HOME}/cmdline-tools"
+  curl -fSL --connect-timeout 20 --retry 3 --retry-delay 2 --max-time 600 \
+    -o "${CI_DIR}/android-tools.zip" \
+    "https://dl.google.com/android/repository/${ANDROID_TOOLS_ZIP}"
+  unzip -q "${CI_DIR}/android-tools.zip" -d "${ANDROID_HOME}/cmdline-tools"
+  rm -rf "${CMDLINE_TOOLS}"
+  mv "${ANDROID_HOME}/cmdline-tools/cmdline-tools" "${CMDLINE_TOOLS}"
+fi
+
+export ANDROID_HOME
+export ANDROID_SDK_ROOT="${ANDROID_HOME}"
+export PATH="${GRADLE_HOME}/bin:${CMDLINE_TOOLS}/bin:${ANDROID_HOME}/platform-tools:${PATH}"
+
+yes | sdkmanager --licenses >/dev/null || true
+sdkmanager "platforms;android-35" "build-tools;35.0.0" "platform-tools"
+
+echo "ANDROID_HOME=${ANDROID_HOME}"
+echo "GRADLE_HOME=${GRADLE_HOME}"

scripts/upload-gitea-preview.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+APK_PATH="${1:-${ROOT_DIR}/release/preview/tmux-android-preview.apk}"
+LATEST_JSON="${2:-${ROOT_DIR}/release/preview/latest.json}"
+TAG="preview"
+API_ROOT="https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android"
+
+if [ ! -f "${APK_PATH}" ]; then
+  echo "APK not found: ${APK_PATH}" >&2
+  exit 1
+fi
+if [ ! -f "${LATEST_JSON}" ]; then
+  echo "latest.json not found: ${LATEST_JSON}" >&2
+  exit 1
+fi
+
+TOKEN="${TMUX_GITEA_TOKEN:-}"
+if [ -z "${TOKEN}" ]; then
+  printf "Gitea token: " >&2
+  IFS= read -rs TOKEN
+  printf "\n" >&2
+fi
+if [ -z "${TOKEN}" ]; then
+  echo "Missing Gitea token." >&2
+  exit 1
+fi
+
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "${WORK_DIR}"' EXIT
+
+RELEASE_JSON="${WORK_DIR}/release.json"
+BODY='{"tag_name":"preview","target_commitish":"main","name":"tmux Android Preview","body":"Mutable preview APK for fast UI testing. This is not a formal release.","draft":false,"prerelease":true}'
+
+if ! curl -fsSL \
+  -X POST \
+  -H "Authorization: token ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "${BODY}" \
+  "${API_ROOT}/releases" \
+  -o "${RELEASE_JSON}"; then
+  curl -fsSL \
+    -H "Authorization: token ${TOKEN}" \
+    "${API_ROOT}/releases/tags/${TAG}" \
+    -o "${RELEASE_JSON}"
+fi
+
+RELEASE_ID="$(sed -n 's/^{"id":\([0-9][0-9]*\),.*/\1/p' "${RELEASE_JSON}" | head -1)"
+if [ -z "${RELEASE_ID}" ]; then
+  echo "Cannot resolve Gitea release id for preview." >&2
+  exit 1
+fi
+
+upload_asset() {
+  local file="$1"
+  local name="$2"
+  local type="$3"
+  local assets_json old_ids old_id
+  assets_json="${WORK_DIR}/assets-${name}.json"
+  curl -fsSL -H "Authorization: token ${TOKEN}" \
+    "${API_ROOT}/releases/${RELEASE_ID}/assets" \
+    -o "${assets_json}"
+  old_ids="$(python3 - "${assets_json}" "${name}" <<'PY'
+import json
+import sys
+
+with open(sys.argv[1], "r", encoding="utf-8") as handle:
+    assets = json.load(handle)
+for asset in assets:
+    if asset.get("name") == sys.argv[2]:
+        print(asset.get("id"))
+PY
+)"
+  for old_id in ${old_ids}; do
+    curl -fsSL -X DELETE -H "Authorization: token ${TOKEN}" \
+      "${API_ROOT}/releases/${RELEASE_ID}/assets/${old_id}" \
+      -o /dev/null
+  done
+  curl -fsSL \
+    -X POST \
+    -H "Authorization: token ${TOKEN}" \
+    -F "attachment=@${file};type=${type}" \
+    "${API_ROOT}/releases/${RELEASE_ID}/assets?name=${name}" \
+    -o "${WORK_DIR}/${name}.asset.json"
+}
+
+upload_asset "${APK_PATH}" "tmux-android-preview.apk" "application/vnd.android.package-archive"
+upload_asset "${LATEST_JSON}" "latest.json" "application/json"
+
+echo "Uploaded preview release ${RELEASE_ID}"
+echo "Manifest: https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/preview/latest.json"
+echo "APK: https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/preview/tmux-android-preview.apk"