From 290b49d2e8f8133904a7054d3b86c13d398fe487 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 7 Jun 2026 05:24:35 +0100 Subject: [PATCH] Route Android parity through Flutter --- docs/parity-testing-harness.md | 16 ++-- docs/renderer-parity.md | 5 +- docs/runtime-app-parity-roadmap.md | 26 ++++++- scripts/capture-android-flutter-parity.ps1 | 85 ++++++++++++++++++++++ scripts/run-parity-smoke.ps1 | 51 +++++++------ tools/parity/parity-manifest.json | 20 +++-- tools/parity/render-contact-sheet.py | 14 ++-- 7 files changed, 168 insertions(+), 49 deletions(-) create mode 100644 scripts/capture-android-flutter-parity.ps1 diff --git a/docs/parity-testing-harness.md b/docs/parity-testing-harness.md index b4a6c6d..399038a 100644 --- a/docs/parity-testing-harness.md +++ b/docs/parity-testing-harness.md @@ -47,8 +47,8 @@ viewport matrix: - `desktop`: 1280 x 720 Device runtimes also capture native physical panel cases when the platform -adapter can control orientation without overriding size. Android currently -emits: +adapter can control orientation without overriding size. Android Flutter +currently emits: - `native-portrait`: Periwinkle at physical portrait resolution - `native-landscape`: Periwinkle at physical landscape resolution @@ -95,14 +95,17 @@ The harness tracks every target runtime: - iOS / UIKit: screenshot target through SSH and EveCanvas' `/var/mobile/Library/EveCanvas/capture-request` service. Current iOS capture is fixed-device until a simulator or device-resize adapter exists. -- Android / Kotlin: screenshot target through `adb install`, activity launch, - optional `adb shell wm size`, orientation control, and `adb exec-out - screencap`; the script restores device size and rotation after each viewport. - Windows / Flutter: screenshot target through the Flutter parity golden smoke, with phone, tablet, and desktop goldens. - Linux / Flutter: screenshot target through Nightwing over SSH. The smoke stages `flutter/eve_parity`, runs Flutter goldens on Nightwing, and pulls back phone, tablet, and desktop PNGs. +- Android / Flutter: screenshot target through the same Flutter renderer, + packaged as a debug APK, installed on Periwinkle through `adb`, and captured + with optional `adb shell wm size`, orientation control, and `adb exec-out + screencap`; the script restores device size and rotation after each viewport. +- Android / Kotlin device edge: compatibility body for CultMesh dashboard and + sensor experiments. It is not the GUI parity target. - Fensalir Direct2D: specialized native target, adapter/capture still missing. Pending runtimes are allowed. Silent fake parity is not. @@ -112,7 +115,8 @@ Pending runtimes are allowed. Silent fake parity is not. 1. Add screenshot comparison metrics that score structure, color tokens, bounding boxes, and text presence without pretending byte-identical pixels are the goal. -2. Normalize text scale and font loading across web, Flutter, Android, and iOS. +2. Normalize text scale and font loading across web, Flutter Android, Flutter + desktop, and iOS. 3. Give iOS a real `vn.stage` scene compositor instead of compact stacked fixture lowering. 4. Replace Flutter golden screenshots with native window captures once the diff --git a/docs/renderer-parity.md b/docs/renderer-parity.md index 16aca9e..b65afeb 100644 --- a/docs/renderer-parity.md +++ b/docs/renderer-parity.md @@ -6,7 +6,7 @@ comparison oracle. See [runtime-app-parity-roadmap.md](./runtime-app-parity-roadmap.md) for the generic Eve app plan across web, Flutter, Fensalir Direct2D, iOS/UIKit, and -Android/Kotlin. Repixelizer is the first style-parity target. +the Android Flutter device body. Repixelizer is the first style-parity target. Pixel parity is not byte-identical screenshot parity. Text rasterization, antialiasing, GPU backends, and device scale will differ. The target is @@ -25,8 +25,9 @@ current evidence surface for semantic parity and runtime capture gaps. | Web reference | Active reference/debug renderer | `web/` renders live VoidBot and fixture surfaces through the provider picker; compiles indentation CultUI; lowers partitions, field rows, and slider anatomy; Chrome headless capture emits phone/tablet/desktop PNGs | Needs command round-trip tests | | Windows / Flutter | Active shared graphical smoke target | `flutter/eve_parity` loads exported `gamecult.eve.surface.v1` fixture JSON and emits phone/tablet/desktop golden PNGs through `capture-flutter-parity.ps1` | Needs native window capture and tighter text/style normalization | | Linux / Flutter | Active shared graphical smoke target | Nightwing runs the Flutter parity goldens over SSH and returns phone/tablet/desktop PNGs | Needs native window capture and runner health checks | +| Android / Flutter | Active shared graphical smoke target | The same Flutter parity app is built as an APK, installed on Periwinkle, and captured at phone/tablet/desktop plus native physical panel orientations | Needs live provider picker and command transport beyond fixture assets | | iOS / UIKit | Active native screenshot target | SSH capture stages selected fixture JSON, EveCanvas renders it, and emits a PNG from `/var/mobile/Library/EveCanvas/latest-screenshot.png` | Needs real scene composition for `vn.stage`, Repixelizer token fidelity, and responsive/simulator capture | -| Android / Kotlin | Active device screenshot target | APK builds with selected fixture assets; Periwinkle captures phone/tablet/desktop plus native portrait/landscape PNGs through adb | Needs text scale/font normalization, image lowering, and command controls | +| Android / Kotlin device edge | Compatibility body | Native APK consumes CultMesh dashboard/sensor documents for edge experiments | Not the GUI CultUI parity target unless direct Android ownership earns its keep | | Fensalir Direct2D | Specialized native/game-runtime landing zone | Existing `AquariumUiDocument` and `DirectWriteOverlay` path | Needs adapter from Eve surface document to `AquariumUiDocument`, DirectWrite/Direct2D token lowering, and a clear reason to stay separate from Flutter for desktop UI | ## Spawned Surfaces diff --git a/docs/runtime-app-parity-roadmap.md b/docs/runtime-app-parity-roadmap.md index c12bd14..bf394a9 100644 --- a/docs/runtime-app-parity-roadmap.md +++ b/docs/runtime-app-parity-roadmap.md @@ -6,7 +6,8 @@ Eve should exist as one generic app per supported runtime: - Flutter shared graphical client - Fensalir Direct2D / DirectWrite - iOS / UIKit -- Android / Kotlin +- Android / Flutter +- Android / Kotlin device edge Each app presents the same provider picker, subscribes to the selected provider-owned Eve surface, lowers the same `gamecult.eve.surface.v1` tree, and @@ -193,12 +194,31 @@ First cuts: - Package or load Repixelizer pixel fonts. - Add visual parity fixtures for Repixelizer shell and progress states. -### Android / Kotlin +### Android / Flutter + +Role: + +- Primary Android GUI CultUI parity body through the shared Flutter renderer. +- Periwinkle screenshot target for responsive and physical-panel evidence. + +First cuts: + +- Build and install the Flutter parity APK during the smoke. +- Capture phone, tablet, desktop, native portrait, and native landscape shots + from Periwinkle. +- Add the same provider picker used by the web reference. +- Subscribe to selected provider-owned `gamecult.eve.surface.v1` documents + instead of the compact dashboard compatibility surface. +- Emit commands through the same advertised command boundary as web. + +### Android / Kotlin Device Edge Role: - Native Kotlin Eve app and Periwinkle device edge when direct Android - ownership earns its keep beyond Flutter. + ownership earns its keep beyond Flutter. This body may publish sensors, + observe CultMesh dashboard compatibility traffic, and test Android-specific + integrations. It is not the GUI parity oracle. First cuts: diff --git a/scripts/capture-android-flutter-parity.ps1 b/scripts/capture-android-flutter-parity.ps1 new file mode 100644 index 0000000..a14eaa7 --- /dev/null +++ b/scripts/capture-android-flutter-parity.ps1 @@ -0,0 +1,85 @@ +param( + [string] $FixtureId = "cultui-inspector", + [string] $OutputPath = "artifacts\parity\android-flutter-cultui-inspector.png", + [int] $Width = 0, + [int] $Height = 0, + [ValidateSet("portrait", "landscape", "natural")] + [string] $Orientation = "natural", + [int] $LaunchDelaySeconds = 4, + [switch] $SkipBuild, + [switch] $ForceInstall +) + +$ErrorActionPreference = "Stop" + +$projectRoot = Split-Path -Parent $PSScriptRoot +$flutterRoot = Join-Path $projectRoot "flutter\eve_parity" +$flutter = Join-Path $projectRoot "tools\deps\flutter\bin\flutter.bat" +$assetPath = Join-Path $flutterRoot "assets\current-surface.json" +$fontDir = Join-Path $flutterRoot "assets\fonts" +$repixelizerAssetDir = Join-Path $flutterRoot "assets\repixelizer" +$apkPath = Join-Path $flutterRoot "build\app\outputs\flutter-apk\app-debug.apk" + +if (-not (Test-Path $flutter)) { + throw "Flutter is not installed at $flutter" +} + +if (-not $SkipBuild) { + New-Item -ItemType Directory -Force (Split-Path -Parent $assetPath) | Out-Null + New-Item -ItemType Directory -Force $fontDir | Out-Null + New-Item -ItemType Directory -Force $repixelizerAssetDir | Out-Null + + Copy-Item -LiteralPath (Join-Path $projectRoot "tools\deps\flutter\bin\cache\artifacts\material_fonts\roboto-regular.ttf") -Destination (Join-Path $fontDir "Roboto-Regular.ttf") -Force + Copy-Item -LiteralPath (Join-Path $projectRoot "tools\deps\flutter\bin\cache\artifacts\material_fonts\roboto-bold.ttf") -Destination (Join-Path $fontDir "Roboto-Bold.ttf") -Force + curl.exe -L "https://repixelizer.gamecult.org/app/landing-assets/character-input.png" -o (Join-Path $repixelizerAssetDir "character-input.png") | Out-Host + curl.exe -L "https://repixelizer.gamecult.org/app/landing-assets/character-repixelized.png" -o (Join-Path $repixelizerAssetDir "character-repixelized.png") | Out-Host + + node .\tools\parity\export-fixture.mjs $FixtureId $assetPath | Out-Host + if ($LASTEXITCODE -ne 0) { + throw "Fixture export failed with exit code $LASTEXITCODE" + } + + Push-Location $flutterRoot + try { + & $flutter pub get + if ($LASTEXITCODE -ne 0) { + throw "Flutter pub get failed with exit code $LASTEXITCODE" + } + & $flutter build apk --debug "--dart-define=EVE_PARITY_FIXTURE=$FixtureId" + if ($LASTEXITCODE -ne 0) { + throw "Flutter Android APK build failed with exit code $LASTEXITCODE" + } + } finally { + Pop-Location + } +} + +if (-not (Test-Path $apkPath)) { + throw "Flutter Android APK not found: $apkPath" +} + +$captureArgs = @( + "-ExecutionPolicy", "Bypass", + "-File", ".\scripts\capture-android-screenshot.ps1", + "-OutputPath", $OutputPath, + "-ApkPath", $apkPath, + "-PackageName", "com.example.eve_parity", + "-ActivityName", ".MainActivity", + "-LaunchDelaySeconds", $LaunchDelaySeconds, + "-Orientation", $Orientation +) + +if ($Width -gt 0) { + $captureArgs += @("-Width", $Width) +} +if ($Height -gt 0) { + $captureArgs += @("-Height", $Height) +} +if ($ForceInstall -or -not $SkipBuild) { + $captureArgs += "-ForceInstall" +} + +powershell @captureArgs +if ($LASTEXITCODE -ne 0) { + throw "Android Flutter screenshot failed with exit code $LASTEXITCODE" +} diff --git a/scripts/run-parity-smoke.ps1 b/scripts/run-parity-smoke.ps1 index ed038d8..400fcdc 100644 --- a/scripts/run-parity-smoke.ps1 +++ b/scripts/run-parity-smoke.ps1 @@ -13,7 +13,7 @@ $runRoot = Join-Path $projectRoot (Join-Path $OutputDirectory $stamp) New-Item -ItemType Directory -Force $runRoot | Out-Null $manifest = Get-Content (Join-Path $projectRoot "tools\parity\parity-manifest.json") | ConvertFrom-Json $responsiveCases = @($manifest.responsiveCases) -$androidNativeCases = @($manifest.androidNativeCases) +$androidDeviceCases = @($manifest.androidDeviceCases) $results = [ordered]@{ schema = "gamecult.eve.parity_smoke.v1" @@ -101,36 +101,35 @@ try { -FixturePath $iosFixture } - New-Item -ItemType Directory -Force .\android\app\src\main\assets | Out-Null - node .\tools\parity\export-fixture.mjs $ProviderId .\android\app\src\main\assets\current-surface.json | Out-Host - if ($ProviderId -eq "repixelizer") { - New-Item -ItemType Directory -Force .\android\app\src\main\assets\repixelizer | Out-Null - curl.exe -L "https://repixelizer.gamecult.org/app/landing-assets/character-input.png" -o .\android\app\src\main\assets\repixelizer\character-input.png | Out-Host - curl.exe -L "https://repixelizer.gamecult.org/app/landing-assets/character-repixelized.png" -o .\android\app\src\main\assets\repixelizer\character-repixelized.png | Out-Host - } - powershell -ExecutionPolicy Bypass -File .\scripts\build-android.ps1 | Out-Host - if ($LASTEXITCODE -ne 0) { - throw "Android fixture APK build failed with exit code $LASTEXITCODE" - } - + $androidFlutterBuilt = $false foreach ($case in $responsiveCases) { - Invoke-Capture "android-$($case.id)" { - powershell -ExecutionPolicy Bypass -File .\scripts\capture-android-screenshot.ps1 ` - -OutputPath (Join-Path $runRoot "android-periwinkle-$($case.id).png") ` - -Width $case.width ` - -Height $case.height ` - -Orientation $case.orientation ` - -UseFixture ` - -ForceInstall + Invoke-Capture "android-flutter-$($case.id)" { + $args = @( + "-ExecutionPolicy", "Bypass", + "-File", ".\scripts\capture-android-flutter-parity.ps1", + "-FixtureId", $ProviderId, + "-OutputPath", (Join-Path $runRoot "android-flutter-periwinkle-$($case.id).png"), + "-Width", $case.width, + "-Height", $case.height, + "-Orientation", $case.orientation + ) + if ($androidFlutterBuilt) { + $args += "-SkipBuild" + } else { + $args += "-ForceInstall" + } + powershell @args + $androidFlutterBuilt = $true } } - foreach ($case in $androidNativeCases) { - Invoke-Capture "android-$($case.id)" { - powershell -ExecutionPolicy Bypass -File .\scripts\capture-android-screenshot.ps1 ` - -OutputPath (Join-Path $runRoot "android-periwinkle-$($case.id).png") ` + foreach ($case in $androidDeviceCases) { + Invoke-Capture "android-flutter-$($case.id)" { + powershell -ExecutionPolicy Bypass -File .\scripts\capture-android-flutter-parity.ps1 ` + -FixtureId $ProviderId ` + -OutputPath (Join-Path $runRoot "android-flutter-periwinkle-$($case.id).png") ` -Orientation $case.orientation ` - -UseFixture + -SkipBuild } } diff --git a/tools/parity/parity-manifest.json b/tools/parity/parity-manifest.json index 86c61b2..e655f9c 100644 --- a/tools/parity/parity-manifest.json +++ b/tools/parity/parity-manifest.json @@ -23,7 +23,7 @@ "deviceScale": 1 } ], - "androidNativeCases": [ + "androidDeviceCases": [ { "id": "native-portrait", "orientation": "portrait" @@ -186,13 +186,23 @@ } }, { - "id": "android-kotlin", - "title": "Android / Kotlin", + "id": "android-flutter", + "title": "Android / Flutter", "kind": "active", - "expectedPaths": ["android/app/src/main/java/org/gamecult/eve/MainActivity.kt", "scripts/build-android.ps1"], + "expectedPaths": ["flutter/eve_parity/lib/main.dart", "scripts/capture-android-flutter-parity.ps1"], "capture": { "status": "adb-png", - "note": "adb capture installs the current APK, launches MainActivity, and pulls a screencap from Periwinkle." + "note": "Builds the shared Flutter parity APK, installs it on Periwinkle, and pulls responsive plus physical-panel screencaps through adb." + } + }, + { + "id": "android-kotlin", + "title": "Android / Kotlin device edge", + "kind": "compatibility", + "expectedPaths": ["android/app/src/main/java/org/gamecult/eve/MainActivity.kt", "scripts/build-android.ps1"], + "capture": { + "status": "manual", + "note": "Native Kotlin remains a CultMesh sensor/dashboard compatibility body; it is not the GUI CultUI parity target." } }, { diff --git a/tools/parity/render-contact-sheet.py b/tools/parity/render-contact-sheet.py index 18f201e..01a0988 100644 --- a/tools/parity/render-contact-sheet.py +++ b/tools/parity/render-contact-sheet.py @@ -26,7 +26,7 @@ RUNTIME_ORDER = [ "Web reference", "Windows / Flutter", "Linux / Flutter", - "Android / Kotlin", + "Android / Flutter", "iOS / UIKit", ] @@ -91,12 +91,12 @@ def classify_target(target: dict) -> TargetShot: elif target_id.startswith("linux-"): runtime = "Linux / Flutter" column = target_id.removeprefix("linux-") - elif target_id.startswith("android-native-"): - runtime = "Android / Kotlin" - column = f"native {target_id.removeprefix('android-native-')}" - elif target_id.startswith("android-"): - runtime = "Android / Kotlin" - column = target_id.removeprefix("android-") + elif target_id.startswith("android-flutter-native-"): + runtime = "Android / Flutter" + column = f"native {target_id.removeprefix('android-flutter-native-')}" + elif target_id.startswith("android-flutter-"): + runtime = "Android / Flutter" + column = target_id.removeprefix("android-flutter-") elif target_id == "ios" or target_id.startswith("ios-"): runtime = "iOS / UIKit" column = "device"