Fixes: stop sync, restore and undo losing data, and fix dates, publishing, offline maps and the e2e suite

.github/workflows/android-apk.yml

@@ -1,8 +1,12 @@
-# Build an installable Android debug APK and upload it as a downloadable
-# artifact — so an APK can be obtained with NO local Android toolchain: push (or
-# run this workflow manually), open the run, and download `postcards-debug-apk`.
+# Build an installable Android APK and upload it as a downloadable artifact — so
+# an APK can be obtained with NO local Android toolchain: push (or run this
+# workflow manually), open the run, and download `postcards-apk`. On main it is
+# also published at a permanent download URL (the release step below).
+# With the signing secrets set (docs/NATIVE-BUILDS.md) the APK is a release build
+# signed with one stable key, so each one installs as an update over the last;
+# without them (forks) it is the debug build, signed with a throwaway key.
 # Local headless build: `pnpm --filter postcards apk:debug` (see docs/NATIVE-BUILDS.md).
-name: Android APK (debug)
+name: Android APK
 
 on:
   push:
@@ -46,31 +50,72 @@ jobs:
       - name: Sync the Android project
         # Copies the fresh dist/ into the committed android/ project + updates plugins.
         run: pnpm --filter postcards exec cap sync android
-      - name: Assemble the debug APK
+      - name: Assemble the APK
+        id: apk
         working-directory: apps/postcards/android
+        env:
+          KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          POSTCARDS_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          POSTCARDS_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          POSTCARDS_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
         run: |
           chmod +x ./gradlew
-          ./gradlew --no-daemon assembleDebug
+          # The run number only grows, so every APK has a higher versionCode than
+          # the one it replaces.
+          version="$(node -p "require('../package.json').version")-${GITHUB_SHA::7}"
+          props=(-PversionCode="$GITHUB_RUN_NUMBER" -PversionName="$version")
+          if [ -n "$KEYSTORE_BASE64" ]; then
+            export POSTCARDS_KEYSTORE_FILE="$RUNNER_TEMP/postcards.jks"
+            printf '%s' "$KEYSTORE_BASE64" | base64 -d > "$POSTCARDS_KEYSTORE_FILE"
+            ./gradlew --no-daemon assembleRelease "${props[@]}"
+            cp app/build/outputs/apk/release/app-release.apk "$RUNNER_TEMP/postcards.apk"
+            echo "signing=release" >> "$GITHUB_OUTPUT"
+          else
+            ./gradlew --no-daemon assembleDebug "${props[@]}"
+            cp app/build/outputs/apk/debug/app-debug.apk "$RUNNER_TEMP/postcards.apk"
+            echo "signing=debug" >> "$GITHUB_OUTPUT"
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
       - name: Upload the APK
         uses: actions/upload-artifact@v4
         with:
-          name: postcards-debug-apk
-          path: apps/postcards/android/app/build/outputs/apk/debug/app-debug.apk
+          name: postcards-apk
+          path: ${{ runner.temp }}/postcards.apk
           if-no-files-found: error
 
       # Also publish it to the Releases page so it's downloadable without opening
-      # the Actions run. One rolling prerelease ("debug-latest") holds the newest
-      # build: delete + recreate so its tag always points at the current commit.
+      # the Actions run. One rolling release ("android-latest") holds the newest
+      # build: delete + recreate so its tag always points at the current commit,
+      # while the download URL stays the same:
+      #   https://github.com/<owner>/<repo>/releases/download/android-latest/postcards.apk
       # main only — feature-branch pushes still get the run artifact above.
-      - name: Publish the APK to the rolling debug release
+      - name: Publish the APK to the rolling release
         if: github.ref == 'refs/heads/main'
         env:
           GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.apk.outputs.version }}
+          SIGNING: ${{ steps.apk.outputs.signing }}
         run: |
-          gh release delete debug-latest --yes --cleanup-tag 2>/dev/null || true
-          gh release create debug-latest \
-            "apps/postcards/android/app/build/outputs/apk/debug/app-debug.apk#postcards-debug.apk" \
-            --title "Latest debug APK" \
-            --notes "Automated debug build from ${{ github.sha }}. Debug/unsigned — not for production." \
-            --prerelease \
-            --target "${{ github.sha }}"
+          if [ "$SIGNING" = release ]; then
+            updates="Each new version installs over the previous one and keeps your places."
+          else
+            updates="This is a debug build signed with a one-off key: to install a newer one, export your data (Settings, Your data), uninstall this one, install the new APK and import the file."
+          fi
+          cat > "$RUNNER_TEMP/notes.md" <<EOF
+          Postcards for Android, version $VERSION, built from $GITHUB_SHA.
+
+          **Download:** [postcards.apk](https://github.com/$GITHUB_REPOSITORY/releases/download/android-latest/postcards.apk) — this link always points to the newest build.
+
+          **Install**
+          1. Open the link above on your Android phone (Android 5.1 or newer) and download the APK.
+          2. Open the downloaded file. If Android asks, allow your browser or file manager to *install unknown apps*, then go back and tap **Install**.
+          3. $updates
+
+          Your places stay on your phone: no account, no server, no tracking.
+          EOF
+          gh release delete android-latest --yes --cleanup-tag 2>/dev/null || true
+          gh release create android-latest "$RUNNER_TEMP/postcards.apk" \
+            --title "Postcards for Android" \
+            --notes-file "$RUNNER_TEMP/notes.md" \
+            --latest \
+            --target "$GITHUB_SHA"

.github/workflows/tests.yml

@@ -36,3 +36,10 @@ jobs:
         run: pnpm --filter postcards exec playwright install --with-deps chromium
       - name: E2E tests (incl. a11y gate)
         run: pnpm --filter postcards test:e2e
+      - name: Upload e2e traces
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-test-results
+          path: apps/postcards/test-results/
+          retention-days: 14

AGENTS.md

@@ -37,11 +37,12 @@ observed working:
    a key added to `en.ts` must be added to `fr.ts` and `ko.ts` (and removing one
    means removing it from all three), or tsc fails.
 3. `npx vitest run` — full unit suite green.
-4. `npx playwright test` — e2e green. `smoke`/`photo`/`countryscope`/`import-csv`
-   can flake under full-suite CPU load; re-run the file in isolation to confirm,
-   CI retry absorbs it.
-5. For any UI change, **screenshot and eyeball it** (Chromium is at
-   `/opt/pw-browsers/chromium-1194/chrome-linux/chrome`).
+4. `npx playwright test` — e2e green. On a host whose network interfaces churn
+   (many docker containers, for one), Chromium aborts in-flight requests with
+   `net::ERR_NETWORK_CHANGED`, and a spec can find the app never booted (the
+   reload message or a blank page); re-run the file, and CI's retry absorbs it.
+5. For any UI change, **screenshot and eyeball it** (Playwright's Chromium,
+   from `npx playwright install chromium` in `apps/postcards`).
 6. Commit with a clear message. **Never** put the model identifier in commits,
    PRs, or code — chat only.
 7. Deploy: push HEAD to the feature branch **and** fast-forward the deployed
@@ -70,7 +71,14 @@ Cmd/Ctrl+Shift+R) before re-implementing.
   user action. Optional egress (map tiles, guides, photos) is opt-in and off by
   default; **Offline mode** is the master switch that forces zero egress.
 - The GitHub sync token stays on-device: never in exports, published sites, or
-  logs. The `connect-src` CSP in `index.html` is the backstop.
+  logs. The `connect-src` CSP in `index.html` keeps a script in the page from
+  sending it to any host outside its list; it does not stop a request to
+  `api.github.com`, which the list allows, carrying the token to a repository
+  of the script's choosing. The token's safety also depends on the app being
+  the only app served from its origin, since every page of an origin shares its
+  localStorage: `offware-apps.github.io` currently also serves another app, and
+  a custom domain or another dedicated origin removes that dependency. Hence
+  the fine-grained token, one repository, Contents read and write only.
 - Imports are validated + sanitized, never executed. One portable JSON file.
 - WCAG 2.1 AA, keyboard-first; every interactive control carries a `title`
   (plus `aria-label` when icon-only).

README.md

@@ -2,6 +2,8 @@
 
 -> offware-apps.github.io/Postcards/ 
 
+-> Android: [download postcards.apk](https://github.com/offware-apps/Postcards/releases/download/android-latest/postcards.apk) (newest build; open it on the phone and allow installing unknown apps)
+
 <div align="center">
 
 # Postcards

apps/postcards/android/app/build.gradle

@@ -7,17 +7,37 @@ android {
         applicationId "coop.samourai.postcards"
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
-        versionCode 1
-        versionName "1.0"
+        // CI passes -PversionCode (the run number, so each build installs as an
+        // update over the last) and -PversionName (app version + commit).
+        versionCode((project.findProperty("versionCode") ?: "1") as Integer)
+        versionName(project.findProperty("versionName") ?: "1.0")
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
         aaptOptions {
              // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
              // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
             ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
+    // One stable key signs every release build, so Android accepts each new APK
+    // as an update and keeps the app's data. CI writes the keystore from
+    // repository secrets (docs/NATIVE-BUILDS.md); without them there is no
+    // release signing and CI builds the debug APK instead.
+    def keystoreFile = System.getenv("POSTCARDS_KEYSTORE_FILE")
+    signingConfigs {
+        if (keystoreFile) {
+            release {
+                storeFile file(keystoreFile)
+                storePassword System.getenv("POSTCARDS_KEYSTORE_PASSWORD")
+                keyAlias System.getenv("POSTCARDS_KEY_ALIAS")
+                keyPassword System.getenv("POSTCARDS_KEY_PASSWORD")
+            }
+        }
+    }
     buildTypes {
         release {
+            if (keystoreFile) {
+                signingConfig signingConfigs.release
+            }
             minifyEnabled false
             proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
         }

apps/postcards/android/app/src/main/res/values/ic_launcher_background.xml

@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <color name="ic_launcher_background">#FFFFFF</color>
+    <color name="ic_launcher_background">#4338CA</color>
 </resources>

apps/postcards/android/app/src/main/res/values/strings.xml

@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='utf-8'?>
 <resources>
-    <string name="app_name">Place\'Been</string>
-    <string name="title_activity_main">Place\'Been</string>
+    <string name="app_name">Postcards</string>
+    <string name="title_activity_main">Postcards</string>
     <string name="package_name">coop.samourai.postcards</string>
     <string name="custom_url_scheme">coop.samourai.postcards</string>
 </resources>

apps/postcards/index.html

@@ -4,22 +4,29 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <meta name="color-scheme" content="dark light" />
-    <!-- Content-Security-Policy — the ONE control the "token stays on device"
-         promise rests on. The GitHub sync token lives in this origin's
-         localStorage; the crucial defence is a strict `connect-src` (+ img-src,
-         object-src 'none', form-action 'none'): an injected or dependency-borne
-         script cannot POST the token to any host but the few the app legitimately
-         talks to (api.github.com + GitHub-raw for community data packs, OSM tiles,
-         Wikimedia — never an arbitrary host), nor smuggle it out via an <img>,
-         form or <object>. Delivered as
+    <!-- Content-Security-Policy. The GitHub sync token lives in this origin's
+         localStorage. A strict `connect-src` (+ img-src, object-src 'none',
+         form-action 'none') holds every request a script in this page makes to
+         the few hosts the app talks to (api.github.com + GitHub-raw for
+         community data packs, OSM tiles, Wikimedia — never an arbitrary host),
+         and none leaves via an <img>, form or <object>. What it does not hold:
+         api.github.com is on the list and serves every repository, so a script
+         running here can still send the token there, to a repository of its
+         choosing. Nor does it reach beyond this document: every page served
+         from the same origin shares its localStorage, so the token is only as
+         contained as the origin is dedicated to this app. offware-apps.github.io
+         currently also serves another app; a custom domain or another dedicated
+         origin removes that dependency, and a token scoped to the one sync
+         repository (Contents read and write only) bounds it meanwhile.
+         Delivered as
          a meta because GitHub Pages sends no headers and the Capacitor WebView
          never sees them for the bundled index.html — the only portable channel.
          script-src keeps 'unsafe-inline' ONLY because the Publish PREVIEW renders
          the generated reader in a `sandbox="allow-scripts"` srcdoc iframe, which
          inherits this policy and is all inline script; that frame has an opaque
          origin and cannot read this origin's token, and static hosting offers no
-         per-request nonce, so 'unsafe-inline' here does not widen the credential's
-         blast radius — the connect-src backstop still contains any exfiltration.
+         per-request nonce, so 'unsafe-inline' here does not widen what can
+         reach the token — that frame's requests keep to the same connect-src.
          NOTE: `frame-ancestors`/`sandbox` are ignored in a meta CSP, so there is
          no clickjacking protection on a header-less static host (a non-issue on
          native). connect-src omits self-hosted GitHub Enterprise apiBase hosts;
@@ -61,6 +68,9 @@
     <meta name="theme-color" content="#4338ca" />
     <meta name="description" content="Remember the places you've been — private, offline, in a file you own." />
     <title>Postcards</title>
+    <!-- Before the module entry, so a failed download of the app's own code shows
+         a reload message instead of a blank page (see the file). -->
+    <script src="%BASE_URL%boot-guard.js"></script>
     <!-- Apply the saved colour-theme choice before first paint, so an explicit
          Light/Dark selection never flashes the wrong palette while the app
          bundle loads. First-party, inert: it only reads our own localStorage key

apps/postcards/playwright.config.ts

@@ -1,10 +1,6 @@
 import { defineConfig, devices } from "@playwright/test";
-import { existsSync } from "node:fs";
 
-// Uses the preinstalled Chromium in this environment when present; elsewhere
-// (CI) Playwright's own installed browser is used.
 // Run with: pnpm --filter postcards test:e2e
-const LOCAL_CHROMIUM = "/opt/pw-browsers/chromium-1194/chrome-linux/chrome";
 
 export default defineConfig({
   testDir: "./tests/e2e",
@@ -17,6 +13,10 @@ export default defineConfig({
   use: {
     baseURL: "http://localhost:4173",
     trace: "on-first-retry",
+    // Every test starts a fresh context, so an allowed service worker would
+    // install and precache the whole app in each one. The specs that exercise
+    // the installed app opt back in with test.use({ serviceWorkers: "allow" }).
+    serviceWorkers: "block",
     // Seed the "intro seen" flag so the first-run welcome modal never auto-opens
     // over the app during tests (it would block the very first interaction). The
     // real first-run intro is exercised by users, not the suite.
@@ -43,13 +43,7 @@ export default defineConfig({
   projects: [
     {
       name: "chromium",
-      use: {
-        ...devices["Desktop Chrome"],
-        // Use the environment's preinstalled Chromium instead of downloading.
-        ...(existsSync(LOCAL_CHROMIUM)
-          ? { launchOptions: { executablePath: LOCAL_CHROMIUM } }
-          : {}),
-      },
+      use: { ...devices["Desktop Chrome"] },
     },
   ],
 });