feat: fingerprint hub, Samsung AVD overlay, firmware XSG, H.264, docs

- Add /api/fingerprint hub (revisions, revert, compare, extended JSON, consistency)
- AVD: medium_phone + config.ini Samsung sync on create/start/fingerprint updates
- SAMFW: XSG product segment, firmware_package UI + tests
- Auto-apply fingerprint + anti-detect after boot; anti_detect CPU/Frida tweaks
- Frontend: H.264 hook, touch auto mode, App Store loading, apply messages
- README: Recent updates (EN+AR); CHANGELOG Unreleased; Frida scripts

Made-with: Cursor

Author: code-root

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Fingerprint hub (`/api/fingerprint/*`), `extended_json`, revision snapshots / revert / compare, consistency checks on apply.
+- Samsung-oriented AVD `config.ini` overlay (`medium_phone` + Samsung manufacturer/LCD); sync on fingerprint updates and on start.
+- SAMFW Odin folder merge (e.g. XSG) with product-segment tweak; `backend/tests/test_firmware_xsg.py`.
+- Device create: optional `firmware_package`; UI firmware dropdown; default Samsung G996B preset.
+- Auto fingerprint + anti-detect apply after emulator boot; anti-detect CPU/characteristics improvements; Frida templates under `scripts/frida/`.
+- Optional H.264 WebSocket path (where enabled); touch **auto** mode on device screen; App Store install UX tweaks.
+- **README:** “Recent updates (March 2026)” (EN + AR) documenting the above.
+
 ## [1.0.1] — 2026-03-26
 
 ### Added

README.md

@@ -10,7 +10,7 @@
 ![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white)
 ![License](https://img.shields.io/badge/license-MIT-green)
 
-Web-based **Android Virtual Device (AVD) farm**: create emulated devices, **unique fingerprints** per instance, start/stop, **live screen** over WebSocket (JPEG), **touch/drag** via ADB, **APK store**, HTTP/SOCKS proxy, **SAMFW** firmware alignment presets, REST API + OpenAPI/Swagger.
+Web-based **Android Virtual Device (AVD) farm**: create emulated devices, **unique fingerprints** per instance, start/stop, **live screen** over WebSocket (**JPEG and optional H.264**), **touch/drag** via ADB, **APK store**, HTTP/SOCKS proxy, **SAMFW / Odin folder** firmware alignment, **fingerprint hub API** with revisions, **AVD hardware profile sync** for Samsung vs Pixel, REST API + OpenAPI/Swagger.
 
 **Suggested GitHub “About” description:**  
 *Android AVD farm — FastAPI + React: live WebSocket mirror, ADB input, per-device fingerprint spoofing, APK store, proxy, Docker, SAMFW presets.*
@@ -26,6 +26,7 @@ Web-based **Android Virtual Device (AVD) farm**: create emulated devices, **uniq
 3. [Live stream & control flow](#live-stream--control-flow)
 4. [Device lifecycle](#device-lifecycle)
 5. [Features (current release)](#features-current-release)
+5a. [Recent updates (March 2026)](#recent-updates-march-2026)
 6. [Tech stack](#tech-stack)
 7. [Quick start](#quick-start)
 8. [REST API & WebSocket](#rest-api--websocket)
@@ -157,6 +158,58 @@ stateDiagram-v2
 | **Security** | JWT, user/admin roles, device ownership |
 | **Docker** | Compose stack with Postgres / Redis / Nginx |
 | **CI** | GitHub Actions: backend, frontend, compose validation |
+| **H.264 stream** | Optional low-latency screen path over WebSocket (where enabled) |
+| **Fingerprint hub** | `/api/fingerprint/*` — revisions, revert, compare, validate, extended JSON |
+| **Anti-emulator props** | Layered `setprop` + console + Frida script template; auto-apply after boot |
+
+---
+
+### Recent updates (March 2026)
+
+This release focuses on **Samsung-aligned fingerprints**, **clearer AVD hardware identity**, **firmware package discovery**, and **operator-facing APIs/UI**.
+
+#### Fingerprint system
+
+- **`/api/fingerprint/{device_id}`** (hub): unified REST for full fingerprint documents, optional **`extended`** JSON (extra SIM, sensors, battery, PLMN, etc.), **`revision_label`** on writes.
+- **Revisions**: table `fingerprint_revisions` — list, **revert** to a snapshot, **compare** current vs a revision.
+- **Apply & randomize** on the hub run **consistency checks** before apply (422 on hard failures).
+- **`GET /api/fingerprint/profiles/list`** — device profile silhouettes for editors.
+- **Merge path**: `fingerprint_row_to_apply_dict()` merges SQL columns + `extended_json` for the spoofer (legacy `/api/devices/.../fingerprint` uses the same merge).
+- **Samsung extended props**: large `ro.product` / `ro.vendor` / CSC map via [`backend/core/fingerprint/samsung_enhanced.py`](backend/core/fingerprint/samsung_enhanced.py); many keys **fail on AVD** (expected — image is AOSP, not One UI). Apply response includes **`note`** and **`detail`** explaining this.
+- **Auto-apply on boot**: after a device **starts** successfully, the server runs **fingerprint + anti-detect apply** once (same as manual “Apply”), logged as `fingerprint_auto_apply`.
+
+#### SAMFW / Odin firmware folder names
+
+- **Odin-style directory** names such as `G996BXXSJHZA6_G996BOXMJHZA6_XSG` under [`firmware/`](firmware/) are parsed in [`backend/core/firmware/samfw.py`](backend/core/firmware/samfw.py) (AP, CSC, sales code, locale hints).
+- **`merge_firmware_into_fingerprint`** updates `ap_version`, `csc_version`, build fingerprint PDA segment; **XSG** maps fingerprint **product** segment to **`o1sxxx`** (non-EEA style).
+- **Tests**: [`backend/tests/test_firmware_xsg.py`](backend/tests/test_firmware_xsg.py).
+- **Create device**: optional **`firmware_package`** (ZIP or folder basename) in API; **web UI** loads options from **`GET /api/meta/firmware-packages`**.
+
+#### AVD hardware (Android Studio “Properties”)
+
+- Samsung fingerprints: AVD is created with **`medium_phone`** (SDK has no Samsung device id) then **`~/.android/avd/<name>.avd/config.ini`** is patched: **`hw.device.manufacturer=Samsung`**, **`hw.device.name=medium_phone`**, LCD **1080×2400** / **420** dpi for common **SM-G996B** class devices.
+- **Every device start** and **every fingerprint save path** (PUT, randomize, revert on hub + legacy PUT/randomize) calls **`sync_avd_hardware_with_fingerprint`** so the INI stays aligned after edits.
+
+#### Anti-detection
+
+- [`backend/core/fingerprint/anti_detect.py`](backend/core/fingerprint/anti_detect.py): **`ro.build.characteristics`** favours **`default`** for Samsung/qcom; **CPU ABI list** follows fingerprint **`cpu_abi_list_spoof`**; extra flags (`ro.boot.qemu`, virtual device, etc.); Frida template uses dynamic **CPU** placeholders.
+- **Random fingerprint IP** in the generator **avoids `10.0.2.x`** (classic emulator guest range) when synthesizing private IPs.
+
+#### Frontend
+
+- **New device** dialog: **firmware package** dropdown; **default preset** Samsung **G996B + Android 15** where applicable.
+- **Device screen**: touch mode **Auto** (short movement → tap, longer → swipe) for H.264/JPEG surfaces.
+- **Fingerprint editor**: apply result shows **Arabic summary** + expandable **detail** from API.
+- **App Store**: install-to-device flow improvements (loading feedback) where implemented.
+
+#### Frida
+
+- Template script and notes: [`scripts/frida/`](scripts/frida/) (optional runtime hooks — does not replace `setprop`).
+
+#### Limitations (unchanged but explicit)
+
+- **Google AVD system image** remains **AOSP / Google APIs** — not a Samsung stock ROM. Deep Samsung-only behavior may still require **physical devices** or **heavy Frida** per app.
+- **`tag.display` / Google APIs** in AVD metadata cannot become “Samsung” without a different system image.
 
 ---
 
@@ -366,6 +419,7 @@ CI badge points to **`code-root/emulator-android`**; change it if you fork under
 3. [رسم — تدفق البث والتحكم](#رسم--تدفق-البث-والتحكم)
 4. [رسم — دورة حياة الجهاز](#رسم--دورة-حياة-الجهاز)
 5. [المميزات](#المميزات)
+5أ. [التحديثات الأخيرة (مارس 2026)](#التحديثات-الأخيرة-مارس-2026)
 6. [المكدس التقني](#المكدس-التقني)
 7. [التشغيل السريع](#التشغيل-السريع)
 8. [API و WebSocket](#api-و-websocket)
@@ -388,7 +442,7 @@ CI badge points to **`code-root/emulator-android`**; change it if you fork under
 - تسجيل الدخول و**JWT**.
 - **أجهزة** في قاعدة البيانات لكل مالك؛ **بصمة** و**بروكسي** اختياري.
 - **Start** يشغّل **emulator (AVD)** أو يربط **ADB serial**.
-- **بث الشاشة:** اشتراك WebSocket (`subscribe_screenshots`)، `adb screencap` مع قفل لكل جهاز، JPEG، Base64 مع أبعاد الجهاز لتحويل إحداثيات اللمس.
+- **بث الشاشة:** اشتراك WebSocket (`subscribe_screenshots`)، `adb screencap` مع قفل لكل جهاز، **JPEG واختياري H.264**، Base64 مع أبعاد الجهاز لتحويل إحداثيات اللمس.
 - **لمس وسحب:** `tap` / `swipe` عبر WebSocket؛ **طابور تحكم** يُفرغ قبل اللقطة التالية؛ **دمج مقاطع السحب المتسلسلة** في `swipe` واحد عند الإمكان.
 - **مستودع APK:** رفع وتثبيت عبر ADB، بما في ذلك **split APKs** (`install-multiple`).
 
@@ -497,6 +551,57 @@ stateDiagram-v2
 | **أمان** | JWT، أدوار، امتلاك الأجهزة |
 | **Docker** | Compose كامل |
 | **CI** | GitHub Actions |
+| **بث H.264** | مسار فيديو اختياري عبر WebSocket عند التفعيل |
+| **Fingerprint hub** | `GET/PUT /api/fingerprint/...`، إصدارات، رجوع، مقارنة، JSON موسّع |
+| **إخفاء محاكي** | طبقات setprop + كونسول + قالب Frida؛ تطبيق تلقائي بعد الإقلاع |
+
+---
+
+### التحديثات الأخيرة (مارس 2026)
+
+ملخص بالعربية لنفس التغييرات التقنية في [Recent updates (March 2026)](#recent-updates-march-2026) أعلاه.
+
+#### البصمة وواجهات API
+
+- **`/api/fingerprint/{device_id}`**: جلب وتحديث كامل، حقل **`extended`** (JSON) لبيانات إضافية (شريحة ثانية، حساسات، بطارية، شبكة، …)، و**`revision_label`** عند الحفظ.
+- **جدول `fingerprint_revisions`**: حفظ نسخ؛ **استرجاع** نسخة سابقة؛ **مقارنة** الحالي مع نسخة.
+- **تطبيق وعشوائية** عبر الـ hub تشغّل **فحوصات تناسق** قبل التطبيق (خطأ 422 عند فشل جاد).
+- **`GET /api/fingerprint/profiles/list`**: قائمة ملفات أجهزة للمحرر.
+- **دمج للتطبيق**: `fingerprint_row_to_apply_dict` يدمج أعمدة SQL مع `extended_json` لمسار الـ spoofer (ومسارات `/api/devices/.../fingerprint` القديمة).
+- **سامسونج موسّع**: عشرات `ro.product` / `ro.vendor` / CSC عبر [`samsung_enhanced.py`](backend/core/fingerprint/samsung_enhanced.py) — على AVD يُرفض جزء كبير **وهذا متوقع** (الصورة AOSP وليست One UI). الاستجابة تتضمن **`note`** و **`detail`** لشرح ذلك.
+- **بعد تشغيل الجهاز**: يُنفَّذ **تطبيق البصمة + anti-detect** تلقائياً مرة واحدة، مع تسجيل `fingerprint_auto_apply`.
+
+#### فريموير SAMFW / مجلد Odin
+
+- أسماء مثل **`G996BXXSJHZA6_G996BOXMJHZA6_XSG`** تحت [`firmware/`](firmware/) تُحلّل في [`samfw.py`](backend/core/firmware/samfw.py) (AP، CSC، كود مبيعات، لغة/بلد).
+- **دمج البصمة** يحدّث `ap_version` / `csc_version` ومقطع الـ PDA في `build_fingerprint`؛ لـ **XSG** يُضبط مقطع المنتج إلى **`o1sxxx`**.
+- **اختبارات**: [`backend/tests/test_firmware_xsg.py`](backend/tests/test_firmware_xsg.py).
+- **إنشاء جهاز**: الحقل **`firmware_package`** في الـ API؛ الواجهة تعرض قائمة من **`GET /api/meta/firmware-packages`**.
+
+#### ملف AVD (خصائص المحاكي في Android Studio)
+
+- لبصمة **Samsung**: إنشاء AVD بملف **`medium_phone`** ثم تعديل **`config.ini`**: **`hw.device.manufacturer=Samsung`**, **`hw.device.name=medium_phone`**, شاشة تقريبية **1080×2400** و**420** dpi لموديلات مثل **SM-G996B**.
+- عند **كل تشغيل** وعند **كل تحديث للبصمة** (PUT، عشوائي، revert على الـ hub والمسار القديم) يُستدعى **`sync_avd_hardware_with_fingerprint`** لتحديث الـ INI.
+
+#### مكافحة كشف المحاكي
+
+- [`anti_detect.py`](backend/core/fingerprint/anti_detect.py): **`ro.build.characteristics`** مناسب لسامسونج؛ **ABI** من **`cpu_abi_list_spoof`**؛ أعلام إضافية؛ قالب Frida يستخدم قيم CPU من البصمة.
+- توليد **IP عشوائي** في البصمة **يتجنب `10.0.2.x`**.
+
+#### الواجهة الأمامية
+
+- إنشاء جهاز: قائمة **حزمة فريموير**؛ **افتراضي preset** سامسونج G996B + Android 15 حيث ينطبق.
+- شاشة الجهاز: وضع لمس **تلقائي** (لمسة قصيرة = نقرة، حركة أوضح = سحب).
+- محرر البصمة: بعد Apply تظهر **ملخص عربي** + **تفصيل** من الـ API.
+
+#### Frida
+
+- قوالب في [`scripts/frida/`](scripts/frida/) — اختياري، لا يغني عن `setprop`.
+
+#### حدود واضحة
+
+- صورة نظام المحاكي تبقى **Google APIs / AOSP** وليست روم Samsung كاملاً.
+- **`tag.display` = Google APIs** لا يتغير بدون تغيير صورة النظام.
 
 ---
 

backend/api/routes/devices.py

@@ -268,7 +268,18 @@ async def _create_avd_background(device_id: int, avd_name: str, api_level: int,
     async with AsyncSessionLocal() as db:
         try:
             avd = emulator_manager.avd_backend
-            success = await avd.create_avd(avd_name, api_level=api_level, arch=arch)
+            fp_row = await db.execute(
+                select(DeviceFingerprint).where(DeviceFingerprint.device_id == device_id)
+            )
+            fp = fp_row.scalar_one_or_none()
+            success = await avd.create_avd(
+                avd_name,
+                api_level=api_level,
+                arch=arch,
+                manufacturer=fp.manufacturer if fp else None,
+                brand=fp.brand if fp else None,
+                device_model=fp.device_model if fp else None,
+            )
             result = await db.execute(select(Device).where(Device.id == device_id))
             device = result.scalar_one_or_none()
             if device:
@@ -324,6 +335,7 @@ async def start_device(
         raise HTTPException(status_code=400, detail="Device is already running")
 
     device.status = DeviceStatus.booting
+    device.adb_serial = None
     await db.flush()
     await db.refresh(device)
     await ws_manager.broadcast(device_id, {"type": "status", "status": "booting", "device_id": device_id})
@@ -335,26 +347,76 @@ async def start_device(
 
 async def _start_device_background(device_id: int):
     from db.database import AsyncSessionLocal
+    from core.fingerprint.spoofer import FingerprintSpoofer
+    from core.fingerprint.merge import fingerprint_row_to_apply_dict
+    from core.fingerprint.samsung_enhanced import merge_profile_defaults_for_apply
+
     async with AsyncSessionLocal() as db:
         try:
             result = await db.execute(select(Device).where(Device.id == device_id))
             device = result.scalar_one_or_none()
             if not device:
                 return
+            owner_id = device.owner_id
             success, info = await emulator_manager.start(device)
+            adb_serial = None
+            console_port = None
             if success:
                 device.status = DeviceStatus.running
                 device.pid = info.get("pid")
                 device.adb_port = info.get("adb_port")
                 device.adb_serial = info.get("adb_serial")
                 device.console_port = info.get("console_port")
+                adb_serial = device.adb_serial
+                console_port = device.console_port
             else:
                 device.status = DeviceStatus.error
             await db.commit()
             await ws_manager.broadcast(
                 device_id,
                 {"type": "status", "status": device.status.value, "device_id": device_id, "adb_serial": device.adb_serial}
             )
+
+            # بعد الإقلاع: تطبيق البصمة + طبقة إخفاء المحاكي تلقائياً (يتطلب adb root كالمعتاد)
+            if success and adb_serial:
+                fp_row = await db.execute(
+                    select(DeviceFingerprint).where(DeviceFingerprint.device_id == device_id)
+                )
+                fp = fp_row.scalar_one_or_none()
+                if fp:
+                    try:
+                        raw = fingerprint_row_to_apply_dict(
+                            fp, {"console_port": console_port}
+                        )
+                        raw.pop("_extended_raw", None)
+                        merged = merge_profile_defaults_for_apply(raw)
+                        spoofer = FingerprintSpoofer()
+                        adb_tool = ADBTool()
+                        report = await spoofer.apply(adb_tool, adb_serial, merged)
+                        n_ok, n_fail = len(report.get("applied", [])), len(report.get("failed", []))
+                        await _log_operation(
+                            db,
+                            device_id,
+                            owner_id,
+                            "fingerprint_auto_apply",
+                            OperationStatus.success,
+                            f"applied={n_ok} failed={n_fail}",
+                        )
+                        await db.commit()
+                    except Exception as ex:
+                        logger.warning("fingerprint_auto_apply device=%s: %s", device_id, ex)
+                        try:
+                            await _log_operation(
+                                db,
+                                device_id,
+                                owner_id,
+                                "fingerprint_auto_apply",
+                                OperationStatus.failure,
+                                str(ex)[:500],
+                            )
+                            await db.commit()
+                        except Exception:
+                            pass
         except Exception as e:
             logger.error(f"Start device {device_id} failed: {e}")
             async with AsyncSessionLocal() as db2:
@@ -382,6 +444,7 @@ async def stop_device(
 
     device.status = DeviceStatus.stopped
     device.pid = None
+    device.adb_serial = None
     await db.flush()
     await db.refresh(device)
     await ws_manager.broadcast(device_id, {"type": "status", "status": "stopped", "device_id": device_id})
@@ -405,6 +468,7 @@ async def restart_device(
 
     device.status = DeviceStatus.booting
     device.pid = None
+    device.adb_serial = None
     await db.flush()
     await db.refresh(device)
     background_tasks.add_task(_start_device_background, device_id)
@@ -445,6 +509,12 @@ async def get_screenshot(
         png_bytes = await adb_tool.screenshot(device.adb_serial)
         return Response(content=png_bytes, media_type="image/png")
     except Exception as e:
+        err = str(e).lower()
+        if "not found" in err and ("device" in err or "adb:" in err):
+            raise HTTPException(
+                status_code=503,
+                detail="ADB device not connected — emulator may have stopped or serial is stale.",
+            )
         raise HTTPException(status_code=500, detail=f"Screenshot failed: {e}")