SuperAPI AI Directory

mobile-experimental-ios-parity

General & other

View repository

Updated 10-16 09:28

About this skill

Mobile Experimental/iOS Parity

Use this skill when src/mobile-experimental must match src/mobile/ios feature-wise while keeping Avalonia, MAUI, Android, and iOS platform heads idiomatic.

Feature parity means the same user outcome, compatible persisted data, comparable error handling, and platform-native presentation. It does not mean copying SwiftUI into Avalonia/MAUI or forcing identical visual chrome.

Non-negotiables

  • Treat src/mobile/ios as the behavioral contract.
  • Keep experimental code native to its stack:
    • Avalonia: .axaml, compiled bindings, avares:// assets, platform services from TopLevel, Android/iOS platform heads where needed.
    • MAUI: XAML pages, Shell navigation, FilePicker, Launcher, platform heads where needed.
    • Android platform heads: intents, content URI handling, scoped cache files, Android package metadata.
    • iOS platform heads: bundle IDs, URL schemes, share extension/app-group behavior, iOS appearance defaults.
  • Preserve cross-platform file/data contracts: .sxcu, .xsdc, upload queue/history records, destination IDs, generated URLs, and user-facing import messages where practical.
  • Do not let experimental convenience drift from production identity. App IDs, URL schemes, document types, app group IDs, logo, version display, and About links should match src/mobile/ios unless intentionally forked.
  • Use the Avalonia docs MCP rules at the start of Avalonia work. Avoid WPF-only patterns such as triggers, pack:// URIs, and DependencyProperty.

First pass

  1. Read AGENTS.md, this skill, and .ai/skills/mobile-android-ios-parity/SKILL.md for shared parity lessons.
  2. Inspect:
    • src/mobile/ios/README.md
    • src/mobile/ios/XerahSMobile
    • src/mobile/ios/ShareExtension
    • src/mobile-experimental/XerahS.Mobile.Ava
    • src/mobile-experimental/XerahS.Mobile.Maui
    • src/mobile-experimental/XerahS.Mobile.Core
    • src/mobile-experimental/XerahS.Mobile.iOS.ShareExtension
  3. Create a focused parity matrix before coding:
| Behavior | iOS source | Experimental source | Status | Native implementation plan |
| --- | --- | --- | --- | --- |
| About screen metadata and links | ... | ... | missing/partial/done | ... |

Keep rows observable. Avoid documenting unrelated implementation details.

Default parity checklist

  • App identity: bundle/application IDs, URL scheme, app group, display name, version/build, logo.
  • Launch/loading flow and top-level navigation.
  • Share receive/open-in-place for one and multiple files.
  • Accepted input types: images, video, audio, PDFs, text, arbitrary files, URLs, .sxcu, .xsdc.
  • Cache copies preserve useful file names and extensions and avoid overwrites.
  • .sxcu import updates or adds custom uploaders and navigates/statuses like iOS.
  • .xsdc import supports encrypted S3 destination configs or clearly preserves the pending passphrase flow.
  • Remote .sxcu deep link: xerahs://import-sxcu?url=....
  • Upload queue, progress, result URL/error display, copy actions, and persisted history.
  • S3 options: region, endpoint, path-style/custom domain, signed payload, public ACL.
  • Custom uploader options: method, headers, parameters, body, arguments, URL/deletion/thumbnail/error extraction.
  • HEIC/HEIF conversion with native platform APIs or documented unsupported behavior.
  • Settings validation and list/detail navigation.
  • About screen metadata, links, social links, and logo.
  • Native feel: Android Material-like touch sizes/system bars; iOS Cupertino-like typography, spacing, tint, navigation behavior.

Implementation rules

  • Prefer shared C# behavior in XerahS.Mobile.Core only when both Avalonia and MAUI need the same domain logic.
  • Keep UI in each app's native UI layer:
    • Avalonia views in XerahS.Mobile.Ava/Views, view models in XerahS.Mobile.Ava/ViewModels, platform APIs in Platforms/*.
    • MAUI pages in XerahS.Mobile.Maui/Views, view models in XerahS.Mobile.Maui/ViewModels, platform APIs in Platforms/*.
  • Do not put Avalonia or MAUI types into XerahS.Mobile.Core.
  • For Avalonia resources, use avares://XerahS.Mobile.Ava/... and ensure assets are AvaloniaResource.
  • For Avalonia URL opening, prefer TopLevel.GetTopLevel(control)?.Launcher.LaunchUriAsync(uri) from view code-behind when the launcher is inherently UI/platform-bound.
  • For Android share/open flows, avoid shell-only file:// assumptions; real parity needs content:// handling from Files/share sheet.
  • For app identity, match production iOS:
    • App/bundle ID: com.xerahs.xerahs.mobile
    • Share extension ID: com.xerahs.xerahs.mobile.ShareExtension
    • App group: group.com.xerahs.xerahs
    • URL scheme: xerahs

Build workflow

For Android build/deploy details, use .ai/skills/build-android/SKILL.md.

Common commands from src/mobile-experimental:

dotnet build XerahS.Mobile.Core/XerahS.Mobile.Core.csproj
dotnet build XerahS.Mobile.Ava/XerahS.Mobile.Ava.csproj -f net10.0-android
dotnet build XerahS.Mobile.Maui/XerahS.Mobile.Maui.csproj -f net10.0-android

Before push, also follow root AGENTS.md build integrity rules. Do not disable warnings-as-errors.

Commit workflow

Commit each completed parity slice before starting unrelated work when the tree is committable.

Good slice boundaries:

  • Skill/docs for experimental parity workflow.
  • App identity and platform metadata.
  • About screen parity.
  • .sxcu/.xsdc import behavior.
  • Share/open/deep-link intent routing.
  • Native-feel UI polish.

Use the root version prefix from Directory.Build.props and AGENTS.md, for example [vX.Y.Z] [Feature] Add experimental mobile About parity.

QA workflow

  • For Android experimental apps, use Test Android Apps: android-emulator-qa.
  • Build/install the exact app head being tested.
  • Launch by resolved package/activity, not stale old IDs.
  • Derive tap coordinates from the UI tree, not screenshots.
  • Verify About metadata, share/import status messages, Settings navigation, and History behavior with UI tree summaries where possible.
  • If emulator validation is limited by content URI grants, local cleartext HTTP, missing iOS signing, or platform workload constraints, state the limitation exactly.

Lessons learned

  • Experimental contains both Avalonia and MAUI heads. If a change is user-facing and both heads expose the same feature, update both or explicitly document why one head is out of scope.
  • App identity drifts easily in experimental projects. Always check .csproj, Android manifest/activity, iOS Info.plist, entitlements, and share extension IDs together.
  • Do not claim .sxcu/.xsdc parity just because upload accepts arbitrary files. Config imports must be classified before upload queueing.
  • MAUI and Avalonia can share import/domain code in XerahS.Mobile.Core, but each app should keep native navigation and launcher behavior in its own UI layer.
  • Remove debug-only labels or deployment IDs from mobile UI before calling it native-feeling.

Reporting

Final responses for this workflow should include:

  • The iOS behavior contract used.
  • Experimental heads changed: Avalonia, MAUI, shared core, platform heads.
  • Build/test commands run.
  • Emulator/device QA performed.
  • Remaining parity gaps or platform limitations.