Regalia v1.2.1

[YDW99]

What's Changed

• fix;docs;style;build by @YDW99 in fix;docs;style;build #43

Full Changelog: v1.2.0...v1.2.1

---

Regalia v1.2.1 — Release Notes

A standalone, open-source chess app for Android — play offline against Stockfish 18, analyze your games, and explore openings. No account, no network, no tracking.

---

📦 Download

File	Size	Description
Regalia-v1.2.1-release.apk	~75 MB	Release APK — arm64-v8a only, Android 6.0+
Regalia-v1.2.1-manual-zh.html	~972 KB	Chinese user manual (self-contained HTML)
Regalia-v1.2.1-manual-en.html	~1.1 MB	English user manual (self-contained HTML)

⚠️ The engine binary is NOT included in the source tarball.
If you build from source, download the official Stockfish 18 arm64-v8a-dotprod binary separately. See BUILDING.md for instructions.

---

✨ What's New in v1.2.1

v1.2.1 is a same-version refinement release — no new features, no new permissions, no versionCode bump. It is the result of 15 rounds of iterative quality improvement on top of the v1.2.0 architecture refactor, driven by first-principles code audits, SonarCloud static analysis, and guidance from three reference PDFs (AI Code Generation Defect Prevention, Android WebView Development, SonarCloud Perfect Review).

🎯 Highlights

• 3 SonarCloud Bugs fixed (PR fix;docs;style;build #43): 2 real S3923 "if/else identical" issues + 1 S2757 false-positive refactor
• 152 empty catch blocks eliminated (S108): 146 in chess.src/*.js + 6 in stats.html — all now log module-tagged console.warn
• God Function refactors (S3776): renderInternal 347→23 lines, _renderDialogs 181→31 lines, _renderReviewMode 612→561 lines
• 53 typeof modernizations (S2703): typeof x === 'undefined' → x === undefined for declared variables; true globals (crypto, AndroidBridge) correctly preserved
• 2 user-reported bugs fixed: review eval chart not refreshing + stats page data completeness
• 25 style unifications (S3523/S1154): parseFloat → Number.parseFloat, String.fromCharCode → String.fromCodePoint
• 4 nested ternary refactors (S3358) + 2 duplicate CSS selector merges (S3646)

---

♟️ Features

Core Gameplay

Feature	Description
Stockfish 18 engine	World-class chess engine, arm64-v8a-dotprod build (ARMv8.6-A DOTPROD instruction set for accelerated NNUE inference)
8 difficulty levels	Level 1 (beginner) → Level 7 (Skill Level mode) → Level 8 (⚙️ custom engine config)
Chess960 (Fischer Random)	Full Chess960 support with SP-ID selector, back-rank preview, Shredder-FEN castling rights
Time controls	Untimed / Sudden Death / Fischer Increment / Bronstein Delay / US Delay
Ponder mode	Engine thinks on opponent's time for faster response
Undo/Redo	Full move history navigation with redo stack
Setup mode	Custom board positions with manual castle-rights (🔁) and en-passant (⚡) markers

Analysis & Review

Feature	Description
Review mode	Step through your game move-by-move with eval bar, trend chart, and move slider
Analyze All	Batch-evaluate every move in the background; long-press to prioritize a specific step
Evaluation trend chart	SVG line chart showing eval progression; auto-centers on the active move
Visual annotations	[%csl] square highlights (B/R/G/Y) + [%cal] arrows; supports multi-color per square
Control heatmap	🌗/🌈 Board coloring showing piece control influence per square
Critical moves	Auto-detected moves where evaluation changed significantly
Statistics page	📊 Full-game statistics: move quality distribution, eval trend, opening classification, PGN text

PGN Support

Feature	Description
PGN import/export	Standard PGN (1994 spec) with NAG, [%csl]/[%cal], [%eval], [%clk], [%emt]
PGN cache manager	📚 Save/load games locally with tags; partial-eval coverage dialog
FEN import/export	Copy/paste FEN positions; setup-mode FEN with Shredder castling for Chess960
ECO opening classifier	500+ openings with search, family filter, and AI book moves
Lichess Syzygy tablebase	7-piece endgame tablebase queries (WDL/DTZ) via TLS-pinned API

User Experience

Feature	Description
Bilingual UI	🇨🇳 Chinese / 🇬🇧 English, toggle from header; persists across sessions
Dark/Light theme	Auto-follows system setting; optimized palettes for both modes
Sensor anti-shake	Board stabilization via sensor fusion (optical-image-stabilization principle)
Haptic feedback	Distinct vibration patterns for piece move, capture, check, game-over
Sound system	Per-piece-type sound effects with move/capture/check/game-over variations
Coordinate labels	a-h file labels + 1-8 rank labels + per-square coordinates on all boards
Responsive layout	Portrait + landscape; notch/cutout/R-corner safe-area insets
SAF file picker	Storage Access Framework for PGN export/import (no storage permission needed on API 29+)

---

🔒 Privacy & Security

Regalia is designed to be private by design.

• 🚫 No account — no registration, no login, no user identification
• 🚫 No tracking — no analytics, no telemetry, no crash reporting to remote servers
• 🚫 No ads — no advertising SDKs, no ad network connections
• 🌐 Offline-first — all gameplay is local; only optional tablebase queries use network (TLS-pinned)
• 🔐 WebView hardened:
  • setAllowFileAccess(false)
  • setAllowFileAccessFromFileURLs(false)
  • setAllowUniversalAccessFromFileURLs(false)
  • @JavascriptInterface annotation on all exposed methods
  • URL scheme whitelist + sandbox path validation (JsBridgeGateway)
  • TLS 1.2+ enforcement + SPKI SHA-256 certificate pinning (TlsSecurityHelper)
• 📁 Scoped storage — all file I/O via SAF content URIs (no direct file path access on API 29+)

Permissions

Permission	Why
INTERNET	Optional Lichess Syzygy tablebase queries (7-piece endgame)
ACCESS_NETWORK_STATE	Check network availability before tablebase queries
WAKE_LOCK	Keep engine alive during long analysis (foreground service, 30-min timeout)
VIBRATE	Haptic feedback on moves/captures/checks
FOREGROUND_SERVICE	Engine stability service (keeps Stockfish process alive)
FOREGROUND_SERVICE_SPECIAL_USE	Android 14+ FGS subtype declaration (chess_engine_analysis)
POST_NOTIFICATIONS	Android 13+ foreground service notification
WRITE_EXTERNAL_STORAGE (maxSdk 28)	Legacy PGN export on Android 9 and below
READ_EXTERNAL_STORAGE (maxSdk 32)	Legacy PGN import on Android 12 and below

See PRIVACY.md for the full privacy policy.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Java Layer                            │
│  ┌──────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │ MainActivity │──│ StockfishNative  │──│ EngineProcess │  │
│  │  (WebView    │  │  (Facade,        │  │  Manager      │  │
│  │   host)      │  │   @JsInterface)  │  │  (chmod)      │  │
│  └──────────────┘  └──────────────────┘  └───────────────┘  │
│         │                    │                    │          │
│         │           ┌────────┴────────┐    ┌──────┴──────┐   │
│         │           │ JsBridgeGateway │    │EngineHealth │   │
│         │           │ (sandbox + UCI  │    │  Monitor    │   │
│         │           │  whitelist)     │    └─────────────┘   │
│         │           └─────────────────┘                      │
│         │                                                    │
│  ┌──────┴──────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │ StatsActivity│  │ EngineService│  │ ChessWebViewClient│   │
│  │ (stats page) │  │ (FGS, keep-  │  │ (load, crash      │   │
│  └─────────────┘  │  alive)      │  │  recovery)         │   │
│                   └──────────────┘  └───────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   JNI Bridge      │
                    │  (engine_jni.cpp) │
                    └─────────┬─────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      JS Layer (WebView)                      │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │game-logic  │ │ chess960 │ │  pgn-    │ │ worker-pool  │  │
│  │  .js       │ │   .js    │ │standard  │ │    .js       │  │
│  │(rules,i18n)│ │(SP-ID,   │ │  .js     │ │(Web Workers) │  │
│  └────────────┘ │Shredder) │ │(encode/  │ └──────────────┘  │
│                 └──────────┘ │ decode)  │                    │
│  ┌────────────┐ ┌──────────┐ └──────────┘ ┌──────────────┐  │
│  │state-store │ │ai-bridge │ ┌──────────┐ │  eco-data    │  │
│  │   .js      │ │   .js    │ │tablebase │ │    .js       │  │
│  │(Redux-like)│ │(engine,  │ │   .js    │ │(ECO openings)│  │
│  └────────────┘ │ eval,PGN)│ │(Syzygy)  │ └──────────────┘  │
│                 └──────────┘ └──────────┘                    │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  ui.js  (rendering, dialogs, review, interaction)    │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Source Code Stats

Component	Files	Lines
Java	18	~10,300
JavaScript	9	~20,700
C++ (JNI)	1	~100
HTML/CSS template	1	~1,300
Total	29	~32,400

---

🔧 Build & Verification

Build Environment

Tool	Version
JDK	Temurin 21.0.5+11
Android SDK	API 35, Build-Tools 34.0.0
NDK	27.2.12479018
CMake	3.22.1
Gradle	8.11.1 (wrapper)
AGP	8.7.3
minSdk	23 (Android 6.0)
targetSdk	35 (Android 15)

APK Signature

Verified using v1 scheme (JAR signing): true
Verified using v2 scheme (APK Signature Scheme v2): true
Verified using v3 scheme (APK Signature Scheme v3): true

✅ v1 + v2 + v3 signatures all enabled — compatible with Xiaomi HyperOS 3 and all Android 6.0+ devices.

Engine Integrity

The Stockfish 18 arm64-v8a-dotprod binary is verified by three-way SHA-256 match:

Source binary:    8f7116d3f1a7004a6581d4fb0c1ff891ce095bab6d45e52f1578897cf23b61b5
jniLibs copy:     8f7116d3f1a7004a6581d4fb0c1ff891ce095bab6d45e52f1578897cf23b61b5
APK-internal:     8f7116d3f1a7004a6581d4fb0c1ff891ce095bab6d45e52f1578897cf23b61b5

✅ All three match — the engine binary is the official Stockfish 18 dotprod build, unmodified.

---

📜 License

Regalia is a combined work under dual licensing:

Component	License
Original application code (UI, WebView, services, build scripts, manuals)	AGPL v3
DroidFish-derived code (engine management, game logic, PGN parsing, UI patterns)	GPL v3
Stockfish 18 engine binary (libstockfish.so)	GPL v3
ECO opening data	CC0 (data) / AGPL v3 (code)
Application icons	AI-generated / AGPL v3

Per GPL v3 Section 13, these licenses are compatible for combination. Each component retains its original license. Since AGPL v3 imposes stricter network interaction provisions (Section 13), its obligations effectively extend to the entire combined work.

License Files

File	Description
LICENSE	AGPL v3 full text (alias for GitHub/F-Droid auto-detection)
LICENSE-AGPL v3	AGPL v3 full text (application)
LICENSE-GPL v3	GPL v3 full text (engine + DroidFish-derived)
LICENSE-Apache v2.0	Apache v2.0 (Gradle)
NOTICE	Third-party component notices + version history
NOTICE-DroidFish	Original DroidFish notice
NOTICE-gradle	Gradle notice

---

📚 Documentation

Document	Description
README.md	Project overview, directory tree, licensing
BUILDING.md	Full build instructions (engine download, keystore, Gradle)
PRIVACY.md	Privacy policy (permissions, data flow, security)
SECURITY_FIXES.md	Security fix history
UBIQUITOUS_LANGUAGE.md	Domain terminology glossary (80+ chess/engine/PGN/UI terms)
CONTRIBUTING-zh.md	Contribution guidelines (Chinese)
CONTRIBUTING-en.md	Contribution guidelines (English)
Manual/Regalia-v1.2.1-manual-zh.html	Chinese user manual
Manual/Regalia-v1.2.1-manual-en.html	English user manual

Each source directory also has a README.license file classifying every file's license:

src/main/README.license
src/main/assets/README.license
src/main/assets/chess.src/README.license
src/main/java/com/Regalia/README.license
src/main/cpp/README.license
src/main/res/README.license
Manual/README.license

---

🔄 Version History Summary

v1.2.1 (versionCode 121) — Current Release

Same-version refinement, 15 rounds of quality improvement:

📖 Click to expand full changelog

Round 15 (2026.7.14) — Final Perfection

• S3776 _renderReviewMode partial extraction (612→561 lines): _buildRvFileLabels, _buildRvRankLabels, _prepareRvVisualAnnotations
• S108 stats.html empty catches (6 sites): console.warn('[Stats]', e.message)
• PDF-guided audit: AI Defect Guide ✓, WebView Guide ✓, SonarCloud Guide ✓

Round 14 (2026.7.14) — _renderDialogs + typeof

• S3776 _renderDialogs refactor (181→31 lines): 8 per-dialog helpers
• S2703 typeof audit (53 conversions): declared vars → direct === undefined; true globals preserved

Round 13 (2026.7.14) — renderInternal God Function

• S3776 renderInternal refactor (347→23 lines): _buildRenderHTML, _saveScrollState, _restoreScrollState, _postRenderFinalize

Round 12 (2026.7.14) — SonarCloud PR #43

• 3 SonarCloud Bugs fixed (S3923 ×2 real, S2757 ×1 false-positive refactor)
• S108 empty catches (146 sites across 5 JS files)
• S3358 nested ternary (2 sites), S3646 duplicate CSS (2 sites)
• S3523 parseFloat (7 sites), S1154 fromCharCode (18 sites)

Round 11 (2026.7.14) — 2 User-Reported Bugs

• Bug Welcome to Regalia Discussions! #1: review eval chart not refreshing on eval completion
• Bug A flaw #2: stats page data completeness varied by selected move (10-min safety timeout)
• Review-report non-false-positive defects (5 items)

Round 10 (2026.7.14) — Deep review-D/E/F fix

• 13 P2/P3 items: concurrency hardening, URL scheme case-insensitivity, HapticHelper dead-code removal, magic-number extraction, build-config cleanup

Round 9 (2026.7.13) — First-principles code review

• 22 items (7 P1 + 11 P2 + 4 P3) from 6 parallel review agents covering ~32K lines

Round 8 (2026.7.13) — TDZ white-screen bug fix

• state-store.js DEEP_CLONE_MAX_DEPTH declaration moved to IIFE top (TDZ violation fix)

Round 7 (2026.7.13) — Phase 62 revert + security hardening

• Phase 62 imported flag control reverted; secureRandomInt safe-fail; structured postJsCallback

Rounds 1-6 (2026.7.12-13) — Initial defect fix + 4 parallel review agents

• P0 TOCTOU race fix, P1 Chess960 symmetry, P1 eval-mode option leak, P1 sandbox hardening, 16+ critical fixes

v1.2.0 (versionCode 120) — Previous Release

Architecture refactor major version:

• Java God Module split: StockfishNative.java (5,443→4,492 lines) → Facade + 11 manager/helper classes
• JS God Module split: ui.js (8,245→8,061 lines) → 4 new modules + sub-function decomposition
• SonarCloud: All 42 Bugs fixed, 5 Vulnerabilities fixed, _buildPGNString decomposed
• Review board coordinate labels (Phase 77→83)

---

🚀 Install

From Pre-built APK

1. Download Regalia-v1.2.1-release.apk to your Android device (arm64-v8a, Android 6.0+)
2. Allow "Install from unknown sources" in Settings if prompted
3. Tap the APK to install

Build from Source

# 1. Extract source
tar xzf Regalia-v1.2.1-src.tar.gz
cd Regalia-v1.2.1-src

# 2. Download Stockfish 18 arm64-v8a-dotprod binary (NOT in tarball)
mkdir -p src/main/jniLibs/arm64-v8a
tar xf stockfish-android-armv8-dotprod.tar
cp stockfish/stockfish-android-armv8-dotprod src/main/jniLibs/arm64-v8a/libstockfish.so
chmod +x src/main/jniLibs/arm64-v8a/libstockfish.so

# 3. Configure SDK path
echo "sdk.dir=/path/to/Android/SDK" > local.properties

# 4. Configure keystore (see BUILDING.md §Signing)

# 5. Build chess.html (merge JS modules)
python3 build-chess.py

# 6. Build release APK
./gradlew assembleRelease -x lint -x lintRelease -x lintVitalRelease --no-daemon

See BUILDING.md for full instructions.

---

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING-en.md (or CONTRIBUTING-zh.md for Chinese) before submitting a pull request.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Code Quality

• All JavaScript modules must pass node --check
• state-store.js must load cleanly in a Node vm context (no TDZ violations)
• Follow the existing code style: _camelCase for private functions, camelCase for public
• Add JSDoc comments for all new functions
• Update NOTICE, README.md, and the relevant README.license for any new files

---

📄 Citation

If you use Regalia in your research or project, please cite:

@software{regalia_chess,
  title  = {Regalia: A Standalone Open-Source Chess App for Android},
  author = {Regalia Contributors},
  year   = {2026},
  version= {1.2.1},
  url    = {https://github.com/YDW99/Regalia},
  note   = {Powered by Stockfish 18 (arm64-v8a-dotprod). AGPL v3 + GPL v3 dual-licensed.}
}

---

🙏 Acknowledgments

• Stockfish — The world-class chess engine that powers Regalia's analysis
• DroidFish — Peter Österlund's Android chess app; Regalia's engine management and game logic are derived from DroidFish
• Lichess — For the Syzygy tablebase API and ECO opening data
• All contributors who have helped shape Regalia through code reviews, bug reports, and feature suggestions

---

⚠️ Disclaimer

"Regalia" is used solely as a project name for this open-source chess app. No trademark rights are claimed. Anyone is free to fork and rename their own version.

Chess piece symbols (♔♕♖♗♘♙ ♚♛♜♝♞♟) are Unicode characters and are rendered using the device's system fonts.

This software is provided "as is", without warranty of any kind. See the license files for complete terms.

---

📊 Stats

Metric	Value
Version Code	121
Version Name	1.2.1
APK Size	78,137,493 bytes (~75 MB)
Source Tarball	4,751,464 bytes (~4.6 MB)
Source Files	112 (excluding build artifacts)
Total Lines of Code	~32,400
Java Files	18
JavaScript Files	9
Minimum Android	6.0 (API 23)
Target Android	15 (API 35)
Architecture	arm64-v8a only
Engine	Stockfish 18 (dotprod)
Signatures	v1 + v2 + v3
License	AGPL v3 + GPL v3

---

♔ Built with care for chess enthusiasts who value privacy, openness, and quality. ♚

---

AI-GEN

---

This discussion was created from the release Regalia v1.2.1.