From a067a2fd01efa2720969e72f1d21b9df07cebccf Mon Sep 17 00:00:00 2001 From: Ilia Denisov Date: Mon, 13 Jul 2026 14:05:43 +0200 Subject: [PATCH] chore(android): de-anchor ANDROID_PLAN.md from the docs, re-enable the APK workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reword every code comment and doc that referenced ANDROID_PLAN.md or its stage anchors (§E, G-step-0, O1) so the living docs no longer depend on the plan file: .claude/CLAUDE.md, deploy/README.md, docs/ARCHITECTURE.md, docs/TESTING.md, ui/README.md, ui/android/.gitignore, ui/e2e/native.spec.ts, ui/src/lib/netstate.ts. Re-enable the manual signed-APK workflow (android-build.yaml.disabled -> android-build.yaml; the CI host already has the Android SDK; workflow_dispatch-only, so it does not auto-run on this PR). Add docs/ICONS.md — the single-master icon/logo format reference (web, PWA, Android, future iOS, store listings). --- .claude/CLAUDE.md | 8 +- ...build.yaml.disabled => android-build.yaml} | 6 +- deploy/README.md | 2 +- docs/ARCHITECTURE.md | 4 +- docs/ICONS.md | 111 ++++++++++++++++++ docs/TESTING.md | 2 +- ui/README.md | 2 +- ui/android/.gitignore | 2 +- ui/e2e/native.spec.ts | 4 +- ui/src/lib/netstate.ts | 2 +- 10 files changed, 127 insertions(+), 16 deletions(-) rename .gitea/workflows/{android-build.yaml.disabled => android-build.yaml} (97%) create mode 100644 docs/ICONS.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 88f7760..845e75d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -30,7 +30,7 @@ on it**, and prefer the authoritative docs where they overlap. Add to this file ## Native Android build (Capacitor) -The native Android app (`ANDROID_PLAN.md`) is a Capacitor 8 wrapper of the `ui` SPA, scaffolded under +The native Android app is a Capacitor 8 wrapper of the `ui` SPA, scaffolded under `ui/` (a Node project outside `go.work`). Hard-won bring-up facts — verify against current code: - **Capacitor 8 needs JDK 21, not 17.** `@capacitor/android` compiles at `VERSION_21`; a JDK 17 Gradle @@ -234,9 +234,9 @@ The native Android app (`ANDROID_PLAN.md`) is a Capacitor 8 wrapper of the `ui` `--pg1-user=scrabble`. - **Offline mode** — the robot brain, move generator/validator/scorer and DAWG reader are **JS ports** of the Go engine, bundled client-side and **parity-pinned** by golden tests. Multi-phase; native - offline-first bundles the dictionaries (see `ANDROID_PLAN.md`). + offline-first bundles the dictionaries. - **VK ID web login** — raw OAuth 2.1 against `id.vk.com`, a **separate VK "Web" app** from the Mini App, server-side confidential code exchange. - **Email relay** — Selectel SMTP + confirm / link / unlink / deletion codes + alerts. -- **Native Android** — see `ANDROID_PLAN.md` (Capacitor bundle model, client-version gate, - offline-first, RuStore). +- **Native Android** — Capacitor bundle model, client-version gate, offline-first, RuStore; the + design lives in `docs/ARCHITECTURE.md` (§2 gate, §3 identity, §13 native build). diff --git a/.gitea/workflows/android-build.yaml.disabled b/.gitea/workflows/android-build.yaml similarity index 97% rename from .gitea/workflows/android-build.yaml.disabled rename to .gitea/workflows/android-build.yaml index 8eb9463..d995407 100644 --- a/.gitea/workflows/android-build.yaml.disabled +++ b/.gitea/workflows/android-build.yaml @@ -5,9 +5,9 @@ # # Signing degrades gracefully: with the ANDROID_KEYSTORE_* secrets present the APK is signed; without # them build.gradle produces an UNSIGNED release APK (so a dry run still proves the whole pipeline). -# The keystore is a publication prerequisite — see deploy/README.md (Android build/release runbook) and -# ANDROID_PLAN.md §E. The toolchain is self-provisioned here (JDK 21 + a cached Android SDK), so the -# runner host needs nothing pre-installed. +# The keystore is a publication prerequisite — see deploy/README.md (Android build/release runbook). +# The toolchain is self-provisioned here (JDK 21 + a cached Android SDK), so the runner host needs +# nothing pre-installed. name: android-build run-name: "android build ${{ github.sha }}" diff --git a/deploy/README.md b/deploy/README.md index 4386976..f95f3f4 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -241,7 +241,7 @@ that survives losing the host. ## Android app build & release (RuStore) The standalone Android app is built by a **manual** workflow, never automatically, and is separate from the -web/prod rollout — a signed APK uploaded to RuStore by hand. Full plan: [`../ANDROID_PLAN.md`](../ANDROID_PLAN.md). +web/prod rollout — a signed APK uploaded to RuStore by hand. The build/release runbook follows. - **Trigger:** `Actions → android-build → Run workflow` from **`master`**, input `confirm=build` (mirrors `prod-deploy`). **Tag the release first** (`git tag vX.Y.Z` on `master`) — the workflow refuses anything diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2204315..c0f08e6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1541,8 +1541,8 @@ hidden in the MVP (`VITE_PAYMENTS_DISABLED`). The APK is built by a **manual** ` the dicts, and assembles a **release APK** artifact — signed when the `ANDROID_KEYSTORE_*` secrets are present, unsigned otherwise. `versionCode`/`versionName` are deterministic from the release tag `vMA.MI.PA` (`versionCode = MA*1_000_000 + MI*1_000 + PA`, `versionName = "MA.MI.PA"`). The runner is a host-executor -with a host-provisioned Android SDK; RuStore upload is manual. Full plan + runbook: -[`../ANDROID_PLAN.md`](../ANDROID_PLAN.md), [`../deploy/README.md`](../deploy/README.md). +with a host-provisioned Android SDK; RuStore upload is manual. Runbook: +[`../deploy/README.md`](../deploy/README.md). ## 14. CI & branches diff --git a/docs/ICONS.md b/docs/ICONS.md new file mode 100644 index 0000000..53abc44 --- /dev/null +++ b/docs/ICONS.md @@ -0,0 +1,111 @@ +# Icon & logo asset map + +> Single reference for every icon/logo format the project ships, and the +> single-master workflow a rebrand should follow. Goal: one vector master → +> regenerate every target, miss nothing. The iOS / iPadOS rows are **future** +> (no iOS shell exists yet) but are listed so a rebrand covers them in one pass. + +## Current state — three drifting sources + +The «Э» mark is emitted today by three independent pipelines that visually drift +(the favicon is a rounded bordered tile, the maskable is a full-bleed square, the +Android launcher is an upscale). The rebrand collapses them onto one master. + +1. **Web favicon set** — `assets/icons/build/generate.js` composes SVG from font + glyph outlines (`assets/icons/build/glyphs.json`) and rasterises with the `ui` + package's Playwright chromium → + `ui/public/{favicon.svg, favicon.ico, apple-touch-icon.png, og-image.png}`. +2. **PWA icons** — `ui/public/{icon-192, icon-512, icon-maskable-512}.png` are + hand-placed and covered by **no** generator (the main drift source). +3. **Android** — `capacitor-assets generate --android` (`pnpm android:assets`) + expands `ui/assets/icon.png` into the launcher + splash matrix under + `ui/android/app/src/main/res/`. + +## Source masters (author once; commit) + +The minimum set the designer supplies so every target below regenerates: + +| Master | Size | Format | Background | Need | Drives | +|---|---|---|---|---|---| +| Vector mark | — | SVG | transparent | required | `favicon.svg`; the canonical shape | +| App icon | 1024×1024 | PNG | opaque | required | Android legacy, PWA raster, iOS, store icons | +| Adaptive foreground | 1024×1024 | PNG | transparent | recommended | Android/iOS adaptive foreground — mark inside the ~66 % safe area (outer third is masked) | +| Adaptive background | 1024×1024 | PNG | opaque | recommended | Android/iOS adaptive background layer | +| Maskable | 512×512 | PNG | opaque | recommended | PWA `maskable` (mark inside the maskable safe zone) | +| Splash | 2732×2732 (+ a `-dark` variant) | PNG | opaque | optional | Android/iOS splash / launch screen | +| OG card | 1200×630 | PNG | opaque | optional | link-preview card (mark **plus** wordmark text) | + +Capacitor reads the adaptive/splash masters from `ui/assets/`: +`icon.png`, `icon-foreground.png`, `icon-background.png`, `splash.png`, +`splash-dark.png`. Without the foreground/background pair it insets the single +`icon.png` into the adaptive safe zone (today's poorer look). + +## Generated targets (full coverage) + +### Web — `ui/public/`, via `node assets/icons/build/generate.js` + +| File | Size | Note | +|---|---|---| +| `favicon.svg` | vector | canonical vector output | +| `favicon.ico` | 32×32 | PNG-in-ICO; answers the blind `/favicon.ico` probe | +| `apple-touch-icon.png` | 180×180 | opaque full-bleed; iOS Safari home-screen (iOS masks its own corners) | +| `og-image.png` | 1200×630 | link-preview card; has the wordmark, referenced by absolute URL | + +### PWA — `ui/public/`, referenced by `manifest.webmanifest` + +| File | Size | `purpose` | +|---|---|---| +| `icon-192.png` | 192×192 | `any` | +| `icon-512.png` | 512×512 | `any` | +| `icon-maskable-512.png` | 512×512 | `maskable` | + +### Android — `ui/android/app/src/main/res/`, via `pnpm android:assets` + +Generated per density mdpi→xxxhdpi (exact px tool-managed); **do not hand-edit**: + +- `mipmap-*/ic_launcher.png` — legacy square (48 / 72 / 96 / 144 / 192) +- `mipmap-*/ic_launcher_round.png` — legacy round +- `mipmap-*/ic_launcher_foreground.png` + `ic_launcher_background.png` — adaptive layers +- `mipmap-anydpi-v26/ic_launcher.xml` + `ic_launcher_round.xml` — adaptive descriptors +- `drawable*/splash.png` — splash (portrait/landscape × light/night × density) + +### iOS / iPhone / iPad — FUTURE, via `capacitor-assets generate --ios` + +No iOS shell today; listed so the rebrand covers it. Same masters produce +`App/App/Assets.xcassets/AppIcon.appiconset`: + +- Modern (Xcode 14+): a single **1024×1024** marketing icon; Xcode derives the rest. +- Full asset-catalog px (if a full set is emitted): 20, 29, 40, 58, 60, 76, 80, + 87, 120, 152, 167, 180, 1024 — iPhone {40, 58, 60, 80, 87, 120, 180}, iPad + {20, 29, 40, 76, 152, 167}, App Store marketing {1024}. +- Splash: `splash-2732x2732.png` (+ dark) → the launch storyboard. +- iOS icons are **opaque, no alpha, no rounded corners** (the OS applies the mask). + +### Store-listing art — uploaded by hand (outside the repo) + +| Store | Asset | Spec | +|---|---|---| +| RuStore (now) | app icon | 512×512 PNG | +| RuStore | screenshots | phone, per the RuStore listing spec | +| RuStore | promo / feature graphic | per the RuStore listing spec | +| App Store (future) | marketing icon | 1024×1024 | +| App Store (future) | screenshots | per device class | +| Google Play (future) | icon / feature graphic | 512×512 / 1024×500 | + +## Regenerate + +```sh +cd assets/icons && node build/generate.js # web favicon set + og card -> ui/public/ +cd ui && pnpm android:assets # Android launcher + splash +cd ui && node_modules/.bin/capacitor-assets generate --ios # future, once the iOS shell exists +``` + +## Open items for the rebrand + +- Decide how the new vector master feeds `assets/icons/` — retarget the generator + onto the supplied vector, or drop in the output files and keep the generator for + the OG card only. +- Bring `icon-192 / icon-512 / icon-maskable-512` under a generator (today + hand-placed — the main drift source). +- Add `ui/assets/icon-foreground.png` + `icon-background.png` for a proper adaptive + icon (today a single inset `icon.png`). diff --git a/docs/TESTING.md b/docs/TESTING.md index 83a993d..eec3152 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -40,7 +40,7 @@ tests or touching CI. in the **offline guest lobby** (not `/login`), plays a local vs_ai move from the **bundled** dawg tier (`playwright.config.ts` bundles the dicts into `dist-e2e/dict/`), starts a hotseat game, and drives `window.__native.reconcile()` to prove online lights up — the device-local game stays listed in the - **unified lobby** (closing G-step-0) — and Profile hides the Telegram/VK link buttons. + **unified lobby** — and Profile hides the Telegram/VK link buttons. The **version-gate** spec (`e2e/update.spec.ts`) drives the `__update` hook to prove both tiers — the hard *Update / Play offline* notice (and that "Play offline" drops into the offline lobby) and the soft dismissable *update available* nudge in the lobby; `retry.test.ts` covers the `FailedPrecondition → diff --git a/ui/README.md b/ui/README.md index d3c71c4..80d88db 100644 --- a/ui/README.md +++ b/ui/README.md @@ -35,7 +35,7 @@ The **native (Capacitor) build** additionally reads `VITE_DICT_VERSION` (the bun the offline path requests, matching the packaged DAWGs), `VITE_PAYMENTS_DISABLED=1` (hide in-app purchases in the RuStore MVP), `VITE_RUSTORE_URL` (the update overlay's store target; empty until published) and `VITE_APP_VERSION` (`git describe --tags` → the `X-Client-Version` gate header) — all wired by -`.gitea/workflows/android-build.yaml`; see `ANDROID_PLAN.md`. +`.gitea/workflows/android-build.yaml`. The build has **two entries**: the game SPA (`index.html`, served at `/app/` and `/telegram/`) and a lightweight landing page (`landing.html`, served at `/`). diff --git a/ui/android/.gitignore b/ui/android/.gitignore index 18ab5c9..e29877b 100644 --- a/ui/android/.gitignore +++ b/ui/android/.gitignore @@ -53,7 +53,7 @@ captures/ .idea/navEditor.xml # Keystore files -# Release signing material must never be committed (see ANDROID_PLAN.md — keystore loss/leak risk). +# Release signing material must never be committed (keystore loss/leak risk). *.jks *.keystore diff --git a/ui/e2e/native.spec.ts b/ui/e2e/native.spec.ts index 92026da..d3d8666 100644 --- a/ui/e2e/native.spec.ts +++ b/ui/e2e/native.spec.ts @@ -67,14 +67,14 @@ test.describe('native offline-first', () => { // returns: reconciliation silently mints + adopts a server guest and clears the auto-offline, so // online lights up — the offline tint drops, the seeded online game (vs Ann) appears and Stats // re-enables. The local game STAYS visible in the unified lobby alongside the server games — a - // reconciled guest keeps its device-local games (this closes G-step-0). + // reconciled guest keeps its device-local games. await page.getByRole('button', { name: /Back|Назад/i }).click(); await expect(page.locator('button.tab').nth(2)).toBeVisible(); await expect(page.locator('.rowwrap').filter({ hasText: '🤖' })).toBeVisible(); // the local vs_ai game, listed while offline await page.evaluate(() => (window as unknown as { __native: { reconcile(): void } }).__native.reconcile()); await expect(page.locator('header.nav.offline')).toHaveCount(0); await expect(page.getByText('Ann', { exact: false }).first()).toBeVisible({ timeout: 15000 }); - await expect(page.locator('.rowwrap').filter({ hasText: '🤖' })).toBeVisible(); // still listed online — the reconciled guest keeps it (G-step-0) + await expect(page.locator('.rowwrap').filter({ hasText: '🤖' })).toBeVisible(); // still listed online — the reconciled guest keeps it await expect(page.locator('button.tab').nth(1)).toBeEnabled(); // The native sign-in surface is guest + email only: on Profile the Telegram + VK LINK buttons are diff --git a/ui/src/lib/netstate.ts b/ui/src/lib/netstate.ts index 1ed6ead..894e963 100644 --- a/ui/src/lib/netstate.ts +++ b/ui/src/lib/netstate.ts @@ -1,4 +1,4 @@ -// The pure net-state machine (O1 of the offline-model redesign). A single reducer replaces the old +// The pure net-state machine. A single reducer replaces the old // two-layer connection.svelte.ts / offline.svelte.ts split: connectivity and the client-version gate // collapse into one detected `state`, with an explicit hysteresis buffer so a brief network blip does // not thrash the chrome. It is a pure function of (previous snapshot, event, config) — no timers, no