Insert uploaded image paths

Reduce terminal key overflow
Rearrange terminal composer controls
2026-07-11 08:11:46 +00:00 · 2026-07-11 08:01:21 +00:00 · 2026-07-11 03:12:52 +00:00 · 2026-07-10 16:18:55 +00:00 · 2026-07-10 15:54:51 +00:00 · 2026-07-10 15:11:12 +00:00
17 changed files with 4170 additions and 632 deletions
@@ -6,19 +6,41 @@ jobs:
  build:
    runs-on: ubuntu-latest
    steps:
-      - name: Build 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
          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 +48,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,15 +79,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.apk
-          ls -lh release/tmux-android-gitea.apk
-          sha256sum release/tmux-android-gitea.apk
+          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}."
@@ -2,21 +2,10 @@ name: Android APK

 on:
  push:
-    branches:
-      - main
    tags:
      - "v*"
  pull_request:
  workflow_dispatch:
-    inputs:
-      publish_release:
-        description: "Create or update a GitHub Release"
-        required: true
-        default: "false"
-        type: choice
-        options:
-          - "false"
-          - "true"

 permissions:
  contents: write
@@ -25,7 +14,7 @@ jobs:
  build:
    runs-on: ubuntu-latest
    env:
-      PUBLISH_RELEASE: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') || inputs.publish_release == 'true' }}
+      PUBLISH_RELEASE: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}

    steps:
      - name: Checkout
@@ -36,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}"

@@ -139,15 +130,7 @@ jobs:
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            TAG="${GITHUB_REF_NAME}"
-          else
-            TAG="v${VERSION_NAME}"
-            git config user.name "github-actions[bot]"
-            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            git tag -f "${TAG}"
-            git push -f origin "${TAG}"
-          fi
+          TAG="${GITHUB_REF_NAME}"

          if gh release view "${TAG}" >/dev/null 2>&1; then
            gh release upload "${TAG}" release/tmux-android.apk release/latest.json --clobber
@@ -157,4 +140,3 @@ jobs:
              --title "tmux Android ${VERSION_NAME}" \
              --notes "Android APK for tmux-ui remote testing."
          fi
-
@@ -1,4 +1,5 @@
 .gradle/
+.ci/
 build/
 app/build/
 local.properties
@@ -6,4 +7,3 @@ signing.properties
 *.jks
 *.keystore
 release/
-
@@ -12,18 +12,28 @@ APIs directly:
 - one-tap probe for the preset Tailscale APIs, showing health/version and
  session counts
 - native tmux session list
+- Sessions page with current API/server and loaded session count
+- native Projects page for kanban project grouping, project agents, project
+  messages, add/remove session, create, and delete actions
 - create, rename, send command, split pane, select pane, kill pane, pin, mute,
  and kill session through HTTP API
 - open one live terminal viewer through `/ws/terminal`
 - native `/ws/events` listener for session invalidation and hook notifications
- GitHub and Gitea update manifest mirrors with fallback
- native API action center for health, server status, timeline, preferences,
-  kanban projects, group messages, hook events, image file/URL upload, image
-  preview info, and native image preview display
+- selectable Gitea or GitHub update source, defaulting to Gitea for mobile
+  reachability
+- native Tools page for health, server status, timeline, preferences, hook
+  events, image file/URL upload, image preview info, and native image preview
+  display
 - mobile soft-key row for tmux-oriented input, including tmux prefix, detach,
  new window, previous/next window, Ctrl keys, arrows, page keys, and paste
- automatic update checks against a GitHub Release manifest
- APK download, SHA-256 verification, and installer handoff
+- terminal viewport resize based on the phone's visible text area, including
+  keyboard height changes, so tmux output wraps at the same width the user sees
+- automatic update checks with Gitea first and GitHub fallback, plus manual
+  source-specific checks
+- one-download-per-version APK cache, SHA-256 verification, and installer
+  handoff
+- native Update and About pages for version/build type, protocol, permission,
+  selected update source, and release information

 ## Server URL

@@ -75,20 +85,35 @@ Create the base64 value from your release keystore:
 base64 -w 0 tmux-android-release.jks
 ```

-Publish a test build by pushing a `v*` tag. That creates a GitHub Release with:
+Branch builds and manual workflow runs create Actions artifacts only. Use them
+to verify grouped changes before publishing.
+
+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
 ```

-Those GitHub links are the primary public install/update channel. Gitea releases
-are mirrored as a second 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.

-Plain branch builds only create Actions artifacts; they are useful for CI
-verification, but releases are the stable download/update channel.
+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 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
@@ -99,20 +124,22 @@ 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. 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
-kanban projects, preferences, timeline events, group messages, and image metadata
-currently use native forms plus native JSON detail dialogs; image preview uses a
-native `ImageView`. The app does not load the browser UI.
+preferences, timeline events, group messages, and image metadata currently use
+native forms plus native JSON detail dialogs; kanban projects use a native
+project/agent list; image preview uses a native `ImageView`. The app does not
+load the browser UI.

 ## Permissions

@@ -131,24 +158,33 @@ release manifest automatically, downloads the newer APK, verifies its SHA-256,
 then opens Android's package installer. The user still has to approve the
 install, and Android 8+ may require allowing this app to install unknown apps.

-The default update manifest is:
+The default update source is the Gitea Release API:
+
+```text
+https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android/releases/latest
+```
+
+The default source resolves `latest.json` and `tmux-android.apk` from Gitea
+release assets, so APK downloads do not require GitHub. The optional GitHub
+manifest is:

 ```text
 https://github.com/neatstudio/tmux-browser-android/releases/latest/download/latest.json
 ```

-The public manual APK download is:
+The app has four update checks on the `Update` page:

-```text
-https://github.com/neatstudio/tmux-browser-android/releases/latest/download/tmux-android.apk
-```
+- `Auto check` tries Gitea first, then tries GitHub only if Gitea cannot be
+  reached.
+- `Gitea` checks only the public Gitea release API.
+- `GitHub` checks only the public GitHub manifest.
+- `Selected` checks the source chosen with `Source`, including a custom
+  manifest/API URL.

-The app tries the selected update source first, then falls back to the GitHub
-manifest and the Gitea release API. The Gitea API endpoint is:
-
-```text
-https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android/releases/latest
-```
+Each source retries transient network failures before that source is considered
+failed. The `APK` and `Release page` buttons still resolve from the selected
+source, so they can be forced to Gitea on phones that cannot reliably reach
+GitHub.

 Gitea tag-specific assets are also public, for example:

@@ -159,10 +195,20 @@ https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/v0.1.7/tmux

 In the app:

- Tap `Update` on the main screen to check `latest.json`, download the APK,
-  verify SHA-256, and open Android's installer.
- Open `More` -> `Open APK download` to download the current public APK in a
-  browser.
- Open `More` -> `Permissions / update status` to see the installed version,
-  update manifest, APK URL, install permission state, and a `Check update`
-  button.
+- Open the `Update` page and tap `Auto check` to check `latest.json`, download
+  the APK, verify SHA-256, and open Android's installer. Use `Gitea`, `GitHub`,
+  or `Selected` to force a single update source.
+- If the same version APK was already downloaded and its SHA-256 still matches,
+  the app reuses that file instead of downloading it again.
+- If Android sends you to the unknown-app install permission screen, return to
+  the app after allowing it; the app continues installing the already downloaded
+  APK without another update check or download.
+- Open the `Update` page and tap `APK` to resolve the APK from the selected
+  update source and open it in a browser.
+- Open the `Update` page and tap `Details` to see the installed version,
+  selected update source, APK/Release resolver behavior, install permission
+  state, and a `Check update` button.
+- Open the `Update` page and tap `App settings` for Android's full per-app
+  permission/settings screen.
+- Open the `About` page to see the app version/build type, package name,
+  API/protocol summary, selected update source, and update policy.
@@ -9,9 +9,13 @@ val repoSlug = providers.gradleProperty("repoSlug")
 val defaultServerUrl = providers.gradleProperty("defaultServerUrl")
    .orElse("http://100.89.0.116:3000")
 val defaultUpdateUrl = providers.gradleProperty("defaultUpdateUrl")
+    .orElse("https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android/releases/latest")
+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")
@@ -36,7 +40,9 @@ android {

        buildConfigField("String", "DEFAULT_SERVER_URL", "\"${defaultServerUrl.get()}\"")
        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()}\"")
    }
@@ -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 {
@@ -0,0 +1,647 @@
+package com.neatstudio.tmuxandroid;
+
+import android.graphics.Color;
+import android.graphics.Typeface;
+import android.text.SpannableStringBuilder;
+import android.text.Spanned;
+import android.text.style.BackgroundColorSpan;
+import android.text.style.ForegroundColorSpan;
+import android.text.style.StyleSpan;
+
+import java.util.ArrayList;
+import java.util.List;
+
+final class TerminalScreenBuffer {
+    private static final int DEFAULT_FG = 0xffe6ebf2;
+    private static final int DEFAULT_BG = Color.TRANSPARENT;
+
+    private int cols;
+    private int rows;
+    private Cell[][] cells;
+    private int cursorRow;
+    private int cursorCol;
+    private int savedRow;
+    private int savedCol;
+    private String pendingControl = "";
+    private boolean wrapPending;
+    private int fg = DEFAULT_FG;
+    private int bg = DEFAULT_BG;
+    private boolean bold;
+
+    TerminalScreenBuffer(int cols, int rows) {
+        resize(cols, rows);
+    }
+
+    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];
+        for (int row = 0; row < rows; row++) {
+            for (int col = 0; col < cols; col++) {
+                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);
+    }
+
+    void clear() {
+        clearScreen();
+        cursorRow = 0;
+        cursorCol = 0;
+        savedRow = 0;
+        savedCol = 0;
+        pendingControl = "";
+        wrapPending = false;
+        fg = DEFAULT_FG;
+        bg = DEFAULT_BG;
+        bold = false;
+    }
+
+    void write(String text) {
+        if (!pendingControl.isEmpty()) {
+            text = pendingControl + text;
+            pendingControl = "";
+        }
+        int index = 0;
+        while (index < text.length()) {
+            char item = text.charAt(index);
+            if (item == '\u001b') {
+                int next = handleEscape(text, index);
+                if (next < 0) {
+                    pendingControl = text.substring(index);
+                    return;
+                }
+                index = next;
+            } else if (item == '\r') {
+                wrapPending = false;
+                cursorCol = 0;
+                index++;
+            } else if (item == '\n') {
+                wrapPending = false;
+                newLine();
+                index++;
+            } else if (item == '\b') {
+                wrapPending = false;
+                cursorCol = Math.max(0, cursorCol - 1);
+                index++;
+            } else if (item == '\t') {
+                int nextTab = ((cursorCol / 8) + 1) * 8;
+                while (cursorCol < Math.min(nextTab, cols)) {
+                    putChar(' ');
+                }
+                index++;
+            } else if (isNakedDeviceAttributesTail(text, index)) {
+                index = skipNakedDeviceAttributesTail(text, index);
+            } else if (item >= 0x20 && item != 0x7f) {
+                putChar(item);
+                index++;
+            } else {
+                index++;
+            }
+        }
+    }
+
+    CharSequence render() {
+        SpannableStringBuilder output = new SpannableStringBuilder();
+        for (int row = 0; row < rows; row++) {
+            appendRow(output, row);
+            if (row + 1 < rows) {
+                output.append('\n');
+            }
+        }
+        return output;
+    }
+
+    private int handleEscape(String text, int index) {
+        if (index + 1 >= text.length()) {
+            return -1;
+        }
+        char next = text.charAt(index + 1);
+        wrapPending = false;
+        if (next == '[') {
+            int end = findAnsiEnd(text, index + 2);
+            if (end == -1) {
+                return -1;
+            }
+            applyCsi(text.substring(index + 2, end), text.charAt(end));
+            return end + 1;
+        }
+        if (next == ']') {
+            return skipStringEscape(text, index + 2);
+        }
+        if (next == 'P' || next == '^' || next == '_') {
+            return skipStringEscape(text, index + 2);
+        }
+        if (next == '(' || next == ')' || next == '*' || next == '+' || next == '-' || next == '.') {
+            if (index + 2 >= text.length()) {
+                return -1;
+            }
+            return Math.min(index + 3, text.length());
+        }
+        if (next == '7') {
+            saveCursor();
+        } else if (next == '8') {
+            restoreCursor();
+        } else if (next == 'D') {
+            newLine();
+        } else if (next == 'E') {
+            cursorCol = 0;
+            newLine();
+        } else if (next == 'M') {
+            reverseIndex();
+        } else if (next == 'c') {
+            clear();
+        }
+        return Math.min(index + 2, text.length());
+    }
+
+    private void applyCsi(String rawParams, char command) {
+        wrapPending = false;
+        String params = rawParams;
+        while (!params.isEmpty()) {
+            char first = params.charAt(0);
+            if (first == '?' || first == '>' || first == '!' || first == '=') {
+                params = params.substring(1);
+            } else {
+                break;
+            }
+        }
+        List<Integer> values = parseParams(params);
+        switch (command) {
+            case 'm':
+                applySgr(values);
+                break;
+            case 'H':
+            case 'f':
+                cursorRow = clamp(param(values, 0, 1) - 1, 0, rows - 1);
+                cursorCol = clamp(param(values, 1, 1) - 1, 0, cols - 1);
+                break;
+            case 'A':
+                cursorRow = clamp(cursorRow - param(values, 0, 1), 0, rows - 1);
+                break;
+            case 'B':
+                cursorRow = clamp(cursorRow + param(values, 0, 1), 0, rows - 1);
+                break;
+            case 'C':
+                cursorCol = clamp(cursorCol + param(values, 0, 1), 0, cols - 1);
+                break;
+            case 'D':
+                cursorCol = clamp(cursorCol - param(values, 0, 1), 0, cols - 1);
+                break;
+            case 'G':
+                cursorCol = clamp(param(values, 0, 1) - 1, 0, cols - 1);
+                break;
+            case 'd':
+                cursorRow = clamp(param(values, 0, 1) - 1, 0, rows - 1);
+                break;
+            case 'J':
+                eraseDisplay(param(values, 0, 0));
+                break;
+            case 'K':
+                eraseLine(param(values, 0, 0));
+                break;
+            case 'P':
+                deleteChars(param(values, 0, 1));
+                break;
+            case '@':
+                insertChars(param(values, 0, 1));
+                break;
+            case 'X':
+                eraseChars(param(values, 0, 1));
+                break;
+            case 'L':
+                insertLines(param(values, 0, 1));
+                break;
+            case 'M':
+                deleteLines(param(values, 0, 1));
+                break;
+            case 's':
+                saveCursor();
+                break;
+            case 'u':
+                restoreCursor();
+                break;
+            case 'c':
+                break;
+            default:
+                break;
+        }
+    }
+
+    private void applySgr(List<Integer> values) {
+        if (values.isEmpty()) {
+            values.add(0);
+        }
+        for (int index = 0; index < values.size(); index++) {
+            int value = values.get(index);
+            if (value == 0) {
+                fg = DEFAULT_FG;
+                bg = DEFAULT_BG;
+                bold = false;
+            } else if (value == 1) {
+                bold = true;
+            } else if (value == 22) {
+                bold = false;
+            } else if (value == 39) {
+                fg = DEFAULT_FG;
+            } else if (value == 49) {
+                bg = DEFAULT_BG;
+            } else if ((value >= 30 && value <= 37) || (value >= 90 && value <= 97)) {
+                fg = ansiColor(value, false);
+            } else if ((value >= 40 && value <= 47) || (value >= 100 && value <= 107)) {
+                bg = ansiColor(value, true);
+            } else if ((value == 38 || value == 48) && index + 2 < values.size()) {
+                boolean background = value == 48;
+                int mode = values.get(index + 1);
+                if (mode == 5) {
+                    int color = xtermColor(values.get(index + 2));
+                    if (background) {
+                        bg = color;
+                    } else {
+                        fg = color;
+                    }
+                    index += 2;
+                } else if (mode == 2 && index + 4 < values.size()) {
+                    int color = Color.rgb(
+                            clamp(values.get(index + 2), 0, 255),
+                            clamp(values.get(index + 3), 0, 255),
+                            clamp(values.get(index + 4), 0, 255)
+                    );
+                    if (background) {
+                        bg = color;
+                    } else {
+                        fg = color;
+                    }
+                    index += 4;
+                }
+            }
+        }
+    }
+
+    private void putChar(char value) {
+        if (wrapPending) {
+            wrapPending = false;
+            newLine();
+        }
+        cells[cursorRow][cursorCol].set(value, fg, bg, bold);
+        if (cursorCol == cols - 1) {
+            wrapPending = true;
+        } else {
+            cursorCol++;
+        }
+    }
+
+    private void newLine() {
+        wrapPending = false;
+        cursorRow++;
+        if (cursorRow >= rows) {
+            scrollUp(1);
+            cursorRow = rows - 1;
+        }
+        cursorCol = 0;
+    }
+
+    private void reverseIndex() {
+        if (cursorRow == 0) {
+            scrollDown(1);
+        } else {
+            cursorRow--;
+        }
+    }
+
+    private void eraseDisplay(int mode) {
+        if (mode == 2 || mode == 3) {
+            clearScreen();
+        } else if (mode == 1) {
+            for (int row = 0; row < cursorRow; row++) {
+                clearLine(row, 0, cols - 1);
+            }
+            clearLine(cursorRow, 0, cursorCol);
+        } else {
+            clearLine(cursorRow, cursorCol, cols - 1);
+            for (int row = cursorRow + 1; row < rows; row++) {
+                clearLine(row, 0, cols - 1);
+            }
+        }
+    }
+
+    private void eraseLine(int mode) {
+        if (mode == 2) {
+            clearLine(cursorRow, 0, cols - 1);
+        } else if (mode == 1) {
+            clearLine(cursorRow, 0, cursorCol);
+        } else {
+            clearLine(cursorRow, cursorCol, cols - 1);
+        }
+    }
+
+    private void eraseChars(int count) {
+        int end = Math.min(cols - 1, cursorCol + Math.max(1, count) - 1);
+        clearLine(cursorRow, cursorCol, end);
+    }
+
+    private void deleteChars(int count) {
+        count = Math.max(1, count);
+        Cell[] line = cells[cursorRow];
+        for (int col = cursorCol; col < cols; col++) {
+            int source = col + count;
+            if (source < cols) {
+                line[col].copyFrom(line[source]);
+            } else {
+                line[col].clear();
+            }
+        }
+    }
+
+    private void insertChars(int count) {
+        count = Math.max(1, count);
+        Cell[] line = cells[cursorRow];
+        for (int col = cols - 1; col >= cursorCol; col--) {
+            int source = col - count;
+            if (source >= cursorCol) {
+                line[col].copyFrom(line[source]);
+            } else {
+                line[col].clear();
+            }
+        }
+    }
+
+    private void insertLines(int count) {
+        count = Math.min(Math.max(1, count), rows - cursorRow);
+        for (int row = rows - 1; row >= cursorRow + count; row--) {
+            copyLine(row, row - count);
+        }
+        for (int row = cursorRow; row < cursorRow + count; row++) {
+            clearLine(row, 0, cols - 1);
+        }
+    }
+
+    private void deleteLines(int count) {
+        count = Math.min(Math.max(1, count), rows - cursorRow);
+        for (int row = cursorRow; row + count < rows; row++) {
+            copyLine(row, row + count);
+        }
+        for (int row = rows - count; row < rows; row++) {
+            clearLine(row, 0, cols - 1);
+        }
+    }
+
+    private void clearScreen() {
+        for (int row = 0; row < rows; row++) {
+            clearLine(row, 0, cols - 1);
+        }
+    }
+
+    private void clearLine(int row, int start, int end) {
+        start = clamp(start, 0, cols - 1);
+        end = clamp(end, 0, cols - 1);
+        for (int col = start; col <= end; col++) {
+            cells[row][col].clear();
+        }
+    }
+
+    private void scrollUp(int count) {
+        count = Math.min(Math.max(1, count), rows);
+        for (int row = 0; row + count < rows; row++) {
+            copyLine(row, row + count);
+        }
+        for (int row = rows - count; row < rows; row++) {
+            clearLine(row, 0, cols - 1);
+        }
+    }
+
+    private void scrollDown(int count) {
+        count = Math.min(Math.max(1, count), rows);
+        for (int row = rows - 1; row - count >= 0; row--) {
+            copyLine(row, row - count);
+        }
+        for (int row = 0; row < count; row++) {
+            clearLine(row, 0, cols - 1);
+        }
+    }
+
+    private void copyLine(int target, int source) {
+        for (int col = 0; col < cols; col++) {
+            cells[target][col].copyFrom(cells[source][col]);
+        }
+    }
+
+    private void appendRow(SpannableStringBuilder output, int row) {
+        int col = 0;
+        while (col < cols) {
+            Cell first = cells[row][col];
+            int start = output.length();
+            int fgColor = first.fg;
+            int bgColor = first.bg;
+            boolean isBold = first.bold;
+            while (col < cols) {
+                Cell cell = cells[row][col];
+                if (cell.fg != fgColor || cell.bg != bgColor || cell.bold != isBold) {
+                    break;
+                }
+                output.append(cell.value);
+                col++;
+            }
+            int end = output.length();
+            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);
+            }
+            if (isBold) {
+                output.setSpan(new StyleSpan(Typeface.BOLD), start, end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
+            }
+        }
+    }
+
+    private void saveCursor() {
+        savedRow = cursorRow;
+        savedCol = cursorCol;
+    }
+
+    private void restoreCursor() {
+        cursorRow = clamp(savedRow, 0, rows - 1);
+        cursorCol = clamp(savedCol, 0, cols - 1);
+    }
+
+    private int skipStringEscape(String text, int start) {
+        int cursor = start;
+        while (cursor < text.length()) {
+            char item = text.charAt(cursor);
+            if (item == '\u0007') {
+                return cursor + 1;
+            }
+            if (item == '\u001b' && cursor + 1 < text.length() && text.charAt(cursor + 1) == '\\') {
+                return cursor + 2;
+            }
+            cursor++;
+        }
+        return -1;
+    }
+
+    private boolean isNakedDeviceAttributesTail(String text, int index) {
+        int cursor = index;
+        boolean hasSemicolon = false;
+        if (cursor < text.length() && (text.charAt(cursor) == '?' || text.charAt(cursor) == '>')) {
+            cursor++;
+        }
+        while (cursor < text.length()) {
+            char item = text.charAt(cursor);
+            if (item >= '0' && item <= '9') {
+                cursor++;
+                continue;
+            }
+            if (item == ';') {
+                hasSemicolon = true;
+                cursor++;
+                continue;
+            }
+            return item == 'c' && hasSemicolon && cursor > index && cursor - index <= 16;
+        }
+        return false;
+    }
+
+    private int skipNakedDeviceAttributesTail(String text, int index) {
+        int cursor = index;
+        while (cursor < text.length() && text.charAt(cursor) != 'c') {
+            cursor++;
+        }
+        return Math.min(cursor + 1, text.length());
+    }
+
+    private int findAnsiEnd(String text, int start) {
+        for (int index = start; index < text.length(); index++) {
+            char item = text.charAt(index);
+            if (item >= '@' && item <= '~') {
+                return index;
+            }
+        }
+        return -1;
+    }
+
+    private List<Integer> parseParams(String params) {
+        List<Integer> values = new ArrayList<>();
+        if (params.isEmpty()) {
+            return values;
+        }
+        String[] parts = params.split(";", -1);
+        for (String part : parts) {
+            String cleaned = part.trim();
+            if (cleaned.isEmpty()) {
+                values.add(0);
+                continue;
+            }
+            try {
+                values.add(Integer.parseInt(cleaned));
+            } catch (NumberFormatException ignored) {
+                values.add(0);
+            }
+        }
+        return values;
+    }
+
+    private int param(List<Integer> values, int index, int fallback) {
+        if (index >= values.size()) {
+            return fallback;
+        }
+        int value = values.get(index);
+        return value == 0 ? fallback : value;
+    }
+
+    private int ansiColor(int code, boolean background) {
+        int base = background ? (code >= 100 ? code - 100 : code - 40) : (code >= 90 ? code - 90 : code - 30);
+        boolean bright = code >= 90;
+        switch (base) {
+            case 0:
+                return bright ? Color.rgb(80, 88, 100) : Color.rgb(33, 38, 45);
+            case 1:
+                return bright ? Color.rgb(255, 123, 114) : Color.rgb(248, 81, 73);
+            case 2:
+                return bright ? Color.rgb(86, 211, 100) : Color.rgb(63, 185, 80);
+            case 3:
+                return bright ? Color.rgb(234, 179, 8) : Color.rgb(210, 153, 34);
+            case 4:
+                return bright ? Color.rgb(121, 192, 255) : Color.rgb(88, 166, 255);
+            case 5:
+                return bright ? Color.rgb(210, 168, 255) : Color.rgb(188, 140, 255);
+            case 6:
+                return bright ? Color.rgb(86, 211, 219) : Color.rgb(57, 197, 187);
+            case 7:
+            default:
+                return bright ? Color.rgb(240, 246, 252) : Color.rgb(201, 209, 217);
+        }
+    }
+
+    private int xtermColor(int value) {
+        value = clamp(value, 0, 255);
+        if (value < 16) {
+            if (value < 8) {
+                return ansiColor(30 + value, false);
+            }
+            return ansiColor(90 + value - 8, false);
+        }
+        if (value >= 232) {
+            int shade = 8 + (value - 232) * 10;
+            return Color.rgb(shade, shade, shade);
+        }
+        int index = value - 16;
+        int red = xtermComponent(index / 36);
+        int green = xtermComponent((index / 6) % 6);
+        int blue = xtermComponent(index % 6);
+        return Color.rgb(red, green, blue);
+    }
+
+    private int xtermComponent(int value) {
+        return value == 0 ? 0 : 55 + value * 40;
+    }
+
+    private static int clamp(int value, int min, int max) {
+        return Math.max(min, Math.min(max, value));
+    }
+
+    private static final class Cell {
+        char value = ' ';
+        int fg = DEFAULT_FG;
+        int bg = DEFAULT_BG;
+        boolean bold;
+
+        void clear() {
+            value = ' ';
+            fg = DEFAULT_FG;
+            bg = DEFAULT_BG;
+            bold = false;
+        }
+
+        void set(char nextValue, int nextFg, int nextBg, boolean nextBold) {
+            value = nextValue;
+            fg = nextFg;
+            bg = nextBg;
+            bold = nextBold;
+        }
+
+        void copyFrom(Cell other) {
+            value = other.value;
+            fg = other.fg;
+            bg = other.bg;
+            bold = other.bold;
+        }
+    }
+}
@@ -6,16 +6,24 @@ 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;
 import java.security.MessageDigest;
 import java.security.SecureRandom;
 import java.util.Arrays;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+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);
@@ -25,11 +33,14 @@ final class TerminalSocketClient {

    private final Object writeLock = new Object();
    private final Listener listener;
+    private final ExecutorService writeExecutor = Executors.newSingleThreadExecutor(runnable ->
+            new Thread(runnable, "terminal-ws-write"));
    private Socket socket;
    private BufferedInputStream input;
    private BufferedOutputStream output;
    private volatile boolean closed;
    private Thread thread;
+    private Thread heartbeatThread;

    TerminalSocketClient(Listener listener) {
        this.listener = listener;
@@ -42,35 +53,41 @@ final class TerminalSocketClient {
    }

    void sendInput(String data) {
-        sendMessage("input", "data", data);
+        sendMessageAsync("input", "data", data);
    }

    void resize(int cols, int rows) {
-        sendMessage("resize", "cols", cols, "rows", rows);
+        sendMessageAsync("resize", "cols", cols, "rows", rows);
    }

    void scroll(int lines) {
-        sendMessage("scroll", "lines", lines);
+        sendMessageAsync("scroll", "lines", lines);
    }

    void clearHistory() {
-        sendMessage("clear-history");
+        sendMessageAsync("clear-history");
    }

    void close() {
        closed = true;
        try {
-            sendFrame(8, new byte[0]);
-        } catch (Exception ignored) {
-        }
-        try {
-            if (socket != null) {
-                socket.close();
-            }
-        } catch (Exception ignored) {
+            writeExecutor.execute(() -> {
+                try {
+                    sendFrame(8, new byte[0]);
+                } catch (Exception ignored) {
+                }
+                closeSocketQuietly();
+            });
+            writeExecutor.shutdown();
+        } catch (RejectedExecutionException ignored) {
+            closeSocketQuietly();
        }
    }

+    boolean isClosed() {
+        return closed;
+    }
+
    private void run(String baseUrl, String sessionName, int cols, int rows) {
        try {
            URI uri = buildWsUri(baseUrl);
@@ -78,14 +95,15 @@ final class TerminalSocketClient {
            input = new BufferedInputStream(socket.getInputStream());
            output = new BufferedOutputStream(socket.getOutputStream());
            handshake(uri);
-            listener.onConnected();
-            sendMessage(
+            sendMessageSync(
                    "attach",
                    "tabId", "android-" + System.currentTimeMillis(),
                    "sessionName", sessionName,
                    "cols", cols,
                    "rows", rows
            );
+            listener.onConnected();
+            startHeartbeat();
            readLoop();
        } catch (Exception error) {
            if (!closed) {
@@ -94,12 +112,8 @@ final class TerminalSocketClient {
        } finally {
            closed = true;
            listener.onClosed();
-            try {
-                if (socket != null) {
-                    socket.close();
-                }
-            } catch (Exception ignored) {
-            }
+            closeSocketQuietly();
+            writeExecutor.shutdownNow();
        }
    }

@@ -116,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 {
@@ -239,7 +282,7 @@ final class TerminalSocketClient {
        }
    }

-    private void sendJson(JSONObject object) {
+    private void sendJsonSync(JSONObject object) {
        try {
            sendFrame(1, object.toString().getBytes(StandardCharsets.UTF_8));
        } catch (Exception error) {
@@ -249,14 +292,21 @@ final class TerminalSocketClient {
        }
    }

-    private void sendMessage(String type, Object... keyValues) {
+    private void sendMessageAsync(String type, Object... keyValues) {
+        try {
+            writeExecutor.execute(() -> sendMessageSync(type, keyValues));
+        } catch (RejectedExecutionException ignored) {
+        }
+    }
+
+    private void sendMessageSync(String type, Object... keyValues) {
        try {
            JSONObject object = new JSONObject();
            object.put("type", type);
            for (int i = 0; i + 1 < keyValues.length; i += 2) {
                object.put(String.valueOf(keyValues[i]), keyValues[i + 1]);
            }
-            sendJson(object);
+            sendJsonSync(object);
        } catch (Exception error) {
            if (!closed) {
                listener.onError(error.getMessage() == null ? error.toString() : error.getMessage());
@@ -264,6 +314,19 @@ final class TerminalSocketClient {
        }
    }

+    private void closeSocketQuietly() {
+        if (heartbeatThread != null) {
+            heartbeatThread.interrupt();
+            heartbeatThread = null;
+        }
+        try {
+            if (socket != null) {
+                socket.close();
+            }
+        } catch (Exception ignored) {
+        }
+    }
+
    private void sendFrame(int opcode, byte[] payload) throws Exception {
        synchronized (writeLock) {
            if (output == null) {
@@ -20,23 +20,31 @@ import java.io.InputStream;
 import java.net.HttpURLConnection;
 import java.net.URL;
 import java.security.MessageDigest;
-import java.util.ArrayList;
-import java.util.LinkedHashSet;
-import java.util.List;
 import java.util.Locale;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;

 final class UpdateManager {
+    private static final String PREF_PENDING_INSTALL_APK = "pending_install_apk";
+    private static final int NETWORK_ATTEMPTS = 3;
+    private static final long RETRY_DELAY_MS = 1200L;
+
    interface Callback {
        void onChecking(boolean checking);
        void onMessage(String message);
    }

+    private interface ReleaseUrlPicker {
+        String pick(ReleaseInfo info);
+    }
+
    private final Activity activity;
    private final SharedPreferences prefs;
    private final Callback callback;
    private final ExecutorService executor = Executors.newSingleThreadExecutor();
+    private volatile boolean checkInProgress;
+    private volatile boolean downloadInProgress;
+    private File pendingInstallApk;

    UpdateManager(Activity activity, SharedPreferences prefs, Callback callback) {
        this.activity = activity;
@@ -45,52 +53,132 @@ final class UpdateManager {
    }

    void check(boolean userInitiated) {
-        List<String> manifestUrls = getUpdateManifestUrls();
+        checkWithFallback(userInitiated);
+    }
+
+    void checkSelected(boolean userInitiated) {
+        startUpdateCheck(
+                userInitiated,
+                "selected source",
+                new String[]{getUpdateManifestUrl()}
+        );
+    }
+
+    void checkGitea(boolean userInitiated) {
+        startUpdateCheck(
+                userInitiated,
+                "Gitea",
+                new String[]{BuildConfig.DEFAULT_GITEA_UPDATE_URL}
+        );
+    }
+
+    void checkGithub(boolean userInitiated) {
+        startUpdateCheck(
+                userInitiated,
+                "GitHub",
+                new String[]{BuildConfig.DEFAULT_GITHUB_UPDATE_URL}
+        );
+    }
+
+    void checkPreview(boolean userInitiated) {
+        startUpdateCheck(
+                userInitiated,
+                "Preview",
+                new String[]{BuildConfig.DEFAULT_PREVIEW_UPDATE_URL}
+        );
+    }
+
+    void checkWithFallback(boolean userInitiated) {
+        startUpdateCheck(
+                userInitiated,
+                "Gitea, then GitHub",
+                new String[]{BuildConfig.DEFAULT_GITEA_UPDATE_URL, BuildConfig.DEFAULT_GITHUB_UPDATE_URL}
+        );
+    }
+
+    private void startUpdateCheck(boolean userInitiated, String label, String[] manifestUrls) {
+        if (checkInProgress) {
+            postMessage("Update check already running");
+            return;
+        }
+        checkInProgress = true;
        callback.onChecking(true);
-        postMessage("Checking update...");
+        postMessage("Checking update: " + label + "...");
        executor.execute(() -> {
+            Exception lastError = null;
            try {
-                ReleaseInfo info = fetchFirstReleaseInfo(manifestUrls);
-                if (info.versionCode <= BuildConfig.VERSION_CODE) {
-                    postMessage("Already up to date: " + BuildConfig.VERSION_NAME);
-                    return;
+                for (int index = 0; index < manifestUrls.length; index++) {
+                    String manifestUrl = manifestUrls[index];
+                    try {
+                        postMessage("Checking " + hostLabel(manifestUrl) + "...");
+                        ReleaseInfo info = fetchReleaseInfo(manifestUrl);
+                        if (info.versionCode <= BuildConfig.VERSION_CODE) {
+                            postMessage("Already up to date: " + BuildConfig.VERSION_NAME + " from " + hostLabel(manifestUrl));
+                            return;
+                        }
+                        postMessage("Update found: " + info.versionName + " from " + hostLabel(manifestUrl));
+                        activity.runOnUiThread(() -> showUpdateDialog(info));
+                        return;
+                    } catch (Exception error) {
+                        lastError = error;
+                        if (index + 1 < manifestUrls.length) {
+                            postMessage(hostLabel(manifestUrl) + " failed; trying " + hostLabel(manifestUrls[index + 1]) + "...");
+                        }
+                    }
                }
-                postMessage("Update found: " + info.versionName);
-                activity.runOnUiThread(() -> showUpdateDialog(info));
-            } catch (Exception error) {
-                postMessage(userInitiated ? "Update check failed: " + error.getMessage() : null);
+                if (lastError != null) {
+                    throw lastError;
+                }
+                throw new IllegalStateException("No update sources configured");
+            } catch (Exception finalError) {
+                postMessage(userInitiated ? "Update check failed: " + finalError.getMessage() : null);
            } finally {
+                checkInProgress = false;
                activity.runOnUiThread(() -> callback.onChecking(false));
            }
        });
    }

-    private List<String> getUpdateManifestUrls() {
-        LinkedHashSet<String> urls = new LinkedHashSet<>();
-        addUrl(urls, prefs.getString("update_url", BuildConfig.DEFAULT_UPDATE_URL));
-        addUrl(urls, BuildConfig.DEFAULT_UPDATE_URL);
-        addUrl(urls, BuildConfig.DEFAULT_GITEA_UPDATE_URL);
-        return new ArrayList<>(urls);
+    void openApkDownload() {
+        openSelectedReleaseUrl("APK", info -> info.apkUrl);
    }

-    private void addUrl(LinkedHashSet<String> urls, String url) {
-        if (url != null && !url.trim().isEmpty()) {
-            urls.add(url.trim());
+    void openReleasePage() {
+        openSelectedReleaseUrl("Release page", info -> info.releasePageUrl);
+    }
+
+    private void openSelectedReleaseUrl(String label, ReleaseUrlPicker picker) {
+        if (checkInProgress) {
+            postMessage("Update check already running");
+            return;
        }
-    }
-
-    private ReleaseInfo fetchFirstReleaseInfo(List<String> manifestUrls) throws Exception {
-        Exception lastError = null;
-        for (String manifestUrl : manifestUrls) {
+        String manifestUrl = getUpdateManifestUrl();
+        checkInProgress = true;
+        callback.onChecking(true);
+        postMessage("Resolving " + label + " from " + hostLabel(manifestUrl) + "...");
+        executor.execute(() -> {
            try {
-                postMessage("Checking " + hostLabel(manifestUrl) + "...");
-                return fetchReleaseInfo(manifestUrl);
+                ReleaseInfo info = fetchReleaseInfo(manifestUrl);
+                String url = picker.pick(info);
+                if (url == null || url.trim().isEmpty()) {
+                    throw new IllegalStateException(label + " URL is missing");
+                }
+                activity.runOnUiThread(() -> openExternalUrl(url.trim(), label));
            } catch (Exception error) {
-                lastError = error;
-                postMessage(hostLabel(manifestUrl) + " failed");
+                postMessage(label + " failed: " + error.getMessage());
+            } finally {
+                checkInProgress = false;
+                activity.runOnUiThread(() -> callback.onChecking(false));
            }
+        });
+    }
+
+    private String getUpdateManifestUrl() {
+        String url = prefs.getString("update_url", BuildConfig.DEFAULT_UPDATE_URL);
+        if (url == null || url.trim().isEmpty()) {
+            return BuildConfig.DEFAULT_UPDATE_URL;
        }
-        throw lastError == null ? new IllegalStateException("No update source configured") : lastError;
+        return url.trim();
    }

    private String hostLabel(String url) {
@@ -151,6 +239,22 @@ final class UpdateManager {
    }

    private String readText(String url) throws Exception {
+        Exception lastError = null;
+        for (int attempt = 1; attempt <= NETWORK_ATTEMPTS; attempt++) {
+            try {
+                return readTextOnce(url);
+            } catch (Exception error) {
+                lastError = error;
+                if (attempt < NETWORK_ATTEMPTS) {
+                    postMessage("Retrying " + hostLabel(url) + " (" + (attempt + 1) + "/" + NETWORK_ATTEMPTS + ")...");
+                    waitBeforeRetry();
+                }
+            }
+        }
+        throw lastError == null ? new IllegalStateException("Request failed") : lastError;
+    }
+
+    private String readTextOnce(String url) throws Exception {
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        connection.setConnectTimeout(12000);
        connection.setReadTimeout(12000);
@@ -173,8 +277,13 @@ final class UpdateManager {
    }

    private void downloadAndInstall(ReleaseInfo info) {
+        if (downloadInProgress) {
+            postMessage("Update download already running");
+            return;
+        }
+        downloadInProgress = true;
        callback.onChecking(true);
-        postMessage("Downloading " + info.versionName + "...");
+        postMessage("Preparing " + info.versionName + "...");
        executor.execute(() -> {
            try {
                File apk = downloadApk(info);
@@ -189,6 +298,7 @@ final class UpdateManager {
            } catch (Exception error) {
                postMessage("Update download failed: " + error.getMessage());
            } finally {
+                downloadInProgress = false;
                activity.runOnUiThread(() -> callback.onChecking(false));
            }
        });
@@ -200,8 +310,42 @@ final class UpdateManager {
            throw new IllegalStateException("Cannot create update cache");
        }
        File apk = new File(dir, "tmux-android-" + info.versionCode + ".apk");
+        if (isCachedApkValid(apk, info)) {
+            postMessage("Using downloaded APK");
+            return apk;
+        }

-        HttpURLConnection connection = (HttpURLConnection) new URL(info.apkUrl).openConnection();
+        postMessage("Downloading " + info.versionName + "...");
+        File partial = new File(dir, "tmux-android-" + info.versionCode + ".apk.tmp");
+        if (partial.exists()) {
+            partial.delete();
+        }
+        if (apk.exists()) {
+            apk.delete();
+        }
+
+        Exception lastError = null;
+        for (int attempt = 1; attempt <= NETWORK_ATTEMPTS; attempt++) {
+            try {
+                downloadApkOnce(info.apkUrl, partial);
+                if (!partial.renameTo(apk)) {
+                    throw new IllegalStateException("Cannot finalize APK download");
+                }
+                return apk;
+            } catch (Exception error) {
+                lastError = error;
+                partial.delete();
+                if (attempt < NETWORK_ATTEMPTS) {
+                    postMessage("Retrying APK download (" + (attempt + 1) + "/" + NETWORK_ATTEMPTS + ")...");
+                    waitBeforeRetry();
+                }
+            }
+        }
+        throw lastError == null ? new IllegalStateException("APK download failed") : lastError;
+    }
+
+    private void downloadApkOnce(String apkUrl, File apk) throws Exception {
+        HttpURLConnection connection = (HttpURLConnection) new URL(apkUrl).openConnection();
        connection.setConnectTimeout(12000);
        connection.setReadTimeout(60000);
        try (InputStream input = new BufferedInputStream(connection.getInputStream());
@@ -214,21 +358,34 @@ final class UpdateManager {
        } finally {
            connection.disconnect();
        }
-        return apk;
+    }
+
+    private boolean isCachedApkValid(File apk, ReleaseInfo info) throws Exception {
+        if (!apk.exists() || apk.length() <= 0) {
+            return false;
+        }
+        if (info.sha256.isEmpty()) {
+            return true;
+        }
+        return sha256(apk).equalsIgnoreCase(info.sha256);
    }

    private void installApk(File apk) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
                && !activity.getPackageManager().canRequestPackageInstalls()) {
+            pendingInstallApk = apk;
+            prefs.edit().putString(PREF_PENDING_INSTALL_APK, apk.getAbsolutePath()).apply();
            Intent settingsIntent = new Intent(
                    Settings.ACTION_MANAGE_UNKNOWN_APP_SOURCES,
                    Uri.parse("package:" + activity.getPackageName())
            );
            activity.startActivity(settingsIntent);
-            Toast.makeText(activity, "Allow installs, then run update again", Toast.LENGTH_LONG).show();
+            Toast.makeText(activity, "Allow installs, then return to continue", Toast.LENGTH_LONG).show();
            postMessage("Install permission required");
            return;
        }
+        pendingInstallApk = null;
+        prefs.edit().remove(PREF_PENDING_INSTALL_APK).apply();

        Uri apkUri = UpdateFileProvider.getUriForFile(
                activity,
@@ -247,6 +404,41 @@ final class UpdateManager {
        }
    }

+    private void openExternalUrl(String url, String label) {
+        try {
+            activity.startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(url)));
+            postMessage("Opened " + label);
+        } catch (ActivityNotFoundException error) {
+            postMessage("No app can open " + label);
+        }
+    }
+
+    void resumePendingInstall() {
+        File apk = pendingInstallApk;
+        if (apk == null) {
+            String path = prefs.getString(PREF_PENDING_INSTALL_APK, "");
+            if (path != null && !path.isEmpty()) {
+                apk = new File(path);
+                pendingInstallApk = apk;
+            }
+        }
+        if (apk == null) {
+            return;
+        }
+        if (!apk.exists() || apk.length() <= 0) {
+            pendingInstallApk = null;
+            prefs.edit().remove(PREF_PENDING_INSTALL_APK).apply();
+            postMessage("Downloaded APK is no longer available");
+            return;
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
+                && !activity.getPackageManager().canRequestPackageInstalls()) {
+            return;
+        }
+        postMessage("Continuing APK install...");
+        installApk(apk);
+    }
+
    private static byte[] readAllBytes(InputStream input) throws Exception {
        java.io.ByteArrayOutputStream output = new java.io.ByteArrayOutputStream();
        byte[] buffer = new byte[16 * 1024];
@@ -280,4 +472,8 @@ final class UpdateManager {
        }
        activity.runOnUiThread(() -> callback.onMessage(message));
    }
+
+    private void waitBeforeRetry() throws InterruptedException {
+        Thread.sleep(RETRY_DELAY_MS);
+    }
 }
@@ -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>
-
@@ -70,6 +70,8 @@ Implemented now:

 - configurable base URL, defaulting to `http://100.89.0.116:3000`
 - support for Tailscale URLs such as `http://100.x.y.z:3000`
+- native multi-page shell with `Sessions`, `Projects`, `Tools`, `Update`, and
+  `About`
 - native session list from `GET /api/sessions`
 - create, rename, command send, split, pane select, pane kill, pin, mute, and
  kill session through documented session/preference endpoints
@@ -78,18 +80,60 @@ Implemented now:
 - bottom shortcut bar for `Esc`, `Tab`, `Ctrl+C`, `Ctrl+V`, arrows, page keys,
  tmux prefix actions, and paste
 - shortcut delivery through the terminal WebSocket `input` message
- native action center for health, server status, timeline, preferences, kanban
-  projects, group messages, hook events, image file/URL upload, image preview
-  metadata, and native image preview display
+- native Projects page for kanban project grouping, project agents, project
+  messages, add/remove session, create, and delete actions
+- native Tools page for health, server status, timeline, preferences, hook
+  events, image file/URL upload, image preview metadata, and native image
+  preview display
 - GitHub Actions APK build
 - release manifest `latest.json`
- APK download, SHA-256 verification, and installer handoff
+- Auto/Gitea/GitHub/Selected update checks, with Auto falling back from Gitea
+  to GitHub
+- one-download-per-version APK cache, SHA-256 verification, and installer
+  handoff
+- terminal viewport resize derived from the Android text area, including
+  keyboard height changes, to avoid fixed-width tmux output wrapping on phones
+- permission/about surfaces for unknown-app install status, notification status,
+  app settings, app version/build type, package name, selected update source, and
+  HTTP/WebSocket API/protocol summary
+
+## Update And Release Policy
+
+The Android app cannot silently replace itself. It may download a newer APK and
+open Android's package installer, but the user must approve the install. On
+Android 8+, the user may also need to allow this app to install unknown apps.
+
+The app provides explicit update checks for Auto, Gitea, GitHub, and Selected.
+Auto checks Gitea first because phones may not reach GitHub reliably, then tries
+GitHub only if Gitea cannot be reached. The manual Gitea, GitHub, and Selected
+buttons force one source. Transient network failures are retried against the
+current source before a source is considered failed.
+
+Downloaded APKs are cached by `versionCode`. If a cached APK exists and its
+SHA-256 matches the manifest, the app reuses it instead of downloading the same
+version again. This matters when Android redirects the user to unknown-app
+install settings before the installer can run. After the user grants that
+permission and returns to the app, the app resumes installation of the pending
+APK instead of asking the user to run update again.
+
+Only `v*` tags publish GitHub Releases. Main branch builds and manual workflow
+runs are for CI artifacts and should be used to validate grouped changes. Do not
+publish a new tag for every small UI copy or layout change; publish when there
+is a useful feature or test batch for phone-side validation.
+
+Release APKs must be identical across the public GitHub and Gitea download
+channels. Treat the GitHub Release APK as the canonical build artifact, then
+mirror that same APK byte-for-byte to the matching Gitea Release. The Gitea
+`latest.json` should point to the Gitea APK URL, but it must keep the same
+`versionCode`, `versionName`, and `sha256` as the GitHub manifest. A Gitea-built
+APK is only a compile check unless its SHA-256 exactly matches the GitHub
+release APK.

 ## Native Roadmap

 To converge with the upstream mobile design, the next implementation should add
 native Android modules in this order:

-1. richer native layouts for kanban, group messages, timeline, and preferences
+1. richer native layouts for group messages, timeline, and preferences
 2. `TerminalCore` with ANSI parsing, cursor state, colors, and dirty rows
 3. configurable shortcut bar backed directly by WebSocket `input`
@@ -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.
@@ -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"
@@ -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}"
@@ -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}"
@@ -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"
Author	SHA1	Message	Date
Codex	6a1052d437	Insert uploaded image paths Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 11m50s Details	2026-07-11 08:11:46 +00:00
Codex	7e028b09d4	Reduce terminal key overflow Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m17s Details	2026-07-11 08:01:21 +00:00
Codex	f6e801defc	Rearrange terminal composer controls Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 12m15s Details	2026-07-11 03:12:52 +00:00
Codex	90f2088265	Support mixed Gitea runners Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m12s Details	2026-07-10 16:18:55 +00:00
Codex	0d0f218d52	Compact terminal input controls Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-10 15:54:51 +00:00
Codex	01f2c66f48	Refine terminal input controls Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m32s Details	2026-07-10 15:11:12 +00:00
Codex	8fda3fa2da	Align primary UI with v0 design Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m54s Details	2026-07-10 14:23:25 +00:00
Codex	69f40e7d36	Apply v0 tmux management UI Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-10 10:47:27 +00:00
Codex	bc918e7664	Use full terminal text width Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m19s Details	2026-07-10 09:11:03 +00:00
Codex	aba3930417	Fix TLS socket wrapper compilation Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-10 03:57:57 +00:00
Codex	4476f41aa6	Reconnect terminal websockets automatically Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Has been cancelled Details	2026-07-10 03:51:42 +00:00
Codex	5122683761	Compact terminal composer controls Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-10 02:43:11 +00:00
Codex	924835dd55	Fix terminal enter and ungrouped sessions Gitea Smoke / smoke (push) Successful in 1s Details Gitea Android APK / build (push) Successful in 11m55s Details	2026-07-09 16:36:52 +00:00
Codex	9fd7b02522	Ignore local Android tool cache Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 11m55s Details	2026-07-09 10:02:29 +00:00
Codex	8e871a3ce6	Add preview APK update channel	2026-07-09 10:01:14 +00:00
Codex	df29546ff9	Move terminal key pager into composer Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 11m57s Details	2026-07-09 00:19:35 +00:00
Codex	bbd6fe3f5f	Refresh native UI styling Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m17s Details	2026-07-08 23:50:48 +00:00
Codex	7e87adfc8d	Add terminal group switcher Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m52s Details	2026-07-08 23:39:17 +00:00
Codex	87729df01f	Refine terminal keys and send input Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Failing after 8m37s Details	2026-07-08 23:19:48 +00:00
Codex	18ad29b501	Add Gitea release mirror script Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Has been cancelled Details	2026-07-08 23:11:58 +00:00
Codex	61e28645f1	Fix server flow and keyboard insets Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 12m16s Details	2026-07-08 15:30:13 +00:00
Codex	a3bc92ddb5	Prefer Gitea for Android builds Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-08 01:30:40 +00:00
Codex	1874d23716	Make terminal accessory bar paged Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android Compile Check / build (push) Successful in 12m27s Details	2026-07-08 01:14:25 +00:00
Codex	c4ec2fd2ef	Refine terminal input panel Gitea Android Compile Check / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 1s Details	2026-07-08 00:38:31 +00:00
Codex	ced6523c00	Improve terminal composer controls Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android Compile Check / build (push) Successful in 12m2s Details	2026-07-08 00:12:16 +00:00
Codex	2e8a0a164f	Use screen buffer for terminal rendering Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android Compile Check / build (push) Successful in 12m10s Details	2026-07-07 11:13:38 +00:00
Codex	c4713dccbd	Handle terminal control sequences Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android Compile Check / build (push) Successful in 12m18s Details	2026-07-07 10:55:06 +00:00
Codex	981e94efc3	Resize terminal to phone viewport Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android Compile Check / build (push) Successful in 11m58s Details	2026-07-07 04:39:08 +00:00
Codex	434cb67372	Add interactive UI feedback Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android Compile Check / build (push) Successful in 11m58s Details	2026-07-07 04:11:56 +00:00
Codex	10e8139a32	Document mirrored release APK policy Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android Compile Check / build (push) Has been cancelled Details	2026-07-07 04:00:00 +00:00
Codex	f9e465bed5	Add update source fallback checks Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 11m57s Details	2026-07-07 03:45:46 +00:00
Codex	7b13d42930	Move terminal writes off main thread Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 11m50s Details	2026-07-07 03:12:28 +00:00
Codex	72913c5571	Default updates to Gitea Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 11m48s Details	2026-07-07 01:37:18 +00:00
Codex	dd056c8027	Add projects page and smooth terminal input Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 12m19s Details	2026-07-06 18:49:28 +00:00
Codex	16086a593f	Show build type and update host Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Successful in 11m56s Details	2026-07-06 13:17:34 +00:00
Codex	c683f135e3	Add sessions page status panel Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-06 13:12:01 +00:00
Codex	1585d9ee07	Add app settings permission shortcut Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 1s Details	2026-07-06 13:06:56 +00:00
Codex	149d675910	Expand about protocol details Gitea Android APK / build (push) Failing after 1s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-06 13:01:55 +00:00
Codex	0609c73d35	Resolve manual update links from selected source Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Has been cancelled Details	2026-07-06 12:56:08 +00:00
Codex	79fd148511	Make main toolbar page contextual Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Has been cancelled Details	2026-07-06 12:50:09 +00:00
Codex	147cec7c6b	Restrict releases to version tags Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-06 12:43:11 +00:00
Codex	67968654cb	Resume pending APK install Gitea Android APK / build (push) Failing after 1s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-06 12:38:44 +00:00
Codex	fc1cf589a7	Document update release policy Gitea Smoke / smoke (push) Successful in 0s Details Gitea Android APK / build (push) Has been cancelled Details	2026-07-06 12:33:04 +00:00
Codex	e2d9810b34	Add update and about pages Gitea Android APK / build (push) Failing after 0s Details Gitea Smoke / smoke (push) Successful in 0s Details	2026-07-06 12:27:45 +00:00