Thing/docs/runtime-app-parity-roadmap.md

# Eve Runtime App Parity Roadmap

Eve should exist as one generic app per supported runtime:

- Web reference
- Flutter shared graphical client
- Fensalir Direct2D / DirectWrite
- iOS / UIKit
- 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
sends commands through the advertised command boundary. The app is the renderer
and local input edge. It is not the provider and not a product-specific
dashboard.

Flutter is now the preferred shared graphical client candidate. It does not
promise byte-identical pixels across every platform, especially around text
rasterization, antialiasing, GPU backends, and device scale. It does promise a
much smaller parity problem than rebuilding the same CultUI anatomy in DOM,
UIKit, Android Views, and Direct2D by hand. The bet is that CultUI owns the UI
tree, style tokens, and control anatomy, while Flutter lowers that contract once
for Android, iOS, desktop, and possibly web.

Repixelizer is the first parity target. Its current browser GUI already carries
the product feel: pixel fonts, dark shell, blue panels, warm pixel accents,
scanlines, image comparison, upload flow, solver progress, and cleanup tools.
The Eve app family should make that surface recognizable across web, Flutter,
Direct2D, iOS, and Android before expanding into broader product coverage.
Recognizable means the fonts are present, spacing/partitioning is coherent,
colors and panels translate, control anatomy survives, and Repixelizer still
feels like Repixelizer. It does not mean screenshot bytes match across all text
engines.

## Authority Map

Owner:

- Eve owns the shared surface contract, provider picker behavior, renderer
  parity harness, local input capture, and runtime-specific lowering.
- Providers own accepted state, commands, style tokens, assets, and side
  effects.
- CultMesh owns publication, discovery delivery, subscriptions, freshness, and
  command transport.
- Odin indexes provider advertisements and helps runtimes discover available
  providers.

Inputs:

- `gamecult.eve.provider_advertisement.v1`
- `gamecult.eve.surface.v1`
- `gamecult.eve.command.v1`
- Runtime-local sensor/input events
- Runtime-local capabilities such as fonts, image sampling, pointer models, and
  GPU/text APIs

Outputs:

- Rendered UI in each target runtime
- Provider command documents or advertised command route calls
- Runtime capability/fidelity diagnostics
- Optional visual parity snapshots for comparison against the web reference

Derived State:

- Selected provider is local Eve app state unless the provider advertises a
  shared selection document.
- Runtime style objects are derived from `surface.styles.tokens`.
- Browser CSS variables, Flutter theme/drawing objects, UIKit colors/fonts,
  Android styles, and DirectWrite brushes are lowerings, not portable authority.
- Visual parity reports are diagnostics, not product truth.

Forbidden Writers:

- Renderer callbacks must not mutate provider state directly.
- Runtime-specific hardcoded colors, fonts, control labels, image sampling
  rules, and layout decisions must not override provider style tokens except as
  documented fallback behavior.
- Product-specific apps must not become the canonical UI when an Eve surface
  exists.
- Compatibility HTTP/browser routes must not replace provider advertisements.

Shared Paths:

- Opening a provider from the dropdown, deep link, command, or startup default
  should use the same provider selection primitive.
- Style tokens should flow through one token lowering path per runtime.
- Commands from buttons, touch gestures, pointer gestures, keyboard shortcuts,
  and future TUI actions should emit the same `gamecult.eve.command.v1` shape.
- Visual parity fixtures should use the same surface document consumed by live
  runtimes.

Deletion Line:

- Replace hardcoded browser tabs with provider advertisements once the first
  local advertisement source exists.
- Demote renderer-specific style shortcuts to fallbacks behind the token
  lowering path.
- Remove product-owned duplicate UI shells once the product surface is complete
  enough for Eve to be the normal app entry.

## Generic App Shell

Every runtime app should expose the same operator shape:

1. Discover providers from CultMesh/Odin, plus explicitly configured local
   fixtures during development.
2. Show a target picker listing provider title, provider id, freshness, kind,
   and primary surface mode.
3. Subscribe to the selected provider surface.
4. Lower `surface.root`, `surface.styles.tokens`, assets, commands, and
   diagnostics through the runtime renderer.
5. Publish commands through the advertised boundary.
6. Report capability gaps when a component, token, asset, command, or embedded
   engine cannot be faithfully lowered.

The browser reference can keep fixtures, but fixture selection should use the
same provider picker model as live providers. A fixture is just a local
advertisement with a local surface source.

## Runtime Targets

### Web Reference

Role:

- Canonical behavior oracle.
- Fastest fixture runner.
- Reference/debug lowering for CultUI authoring, providers, and command flow.

First cuts:

- Replace hardcoded tabs with a provider picker.
- Represent existing fixtures as provider advertisements.
- Load fallback provider entries from `web/local-provider-catalog.json` so
  local discovery data stays out of renderer code.
- Add Repixelizer fixture loading from `docs/fixtures/repixelizer.eve-surface.json`.
- Map the full Repixelizer style token set to CSS variables.
- Add screenshot capture for the Repixelizer first viewport and main app
  workflow states.

### Flutter Shared Graphical Client

Role:

- Preferred cross-platform graphical renderer experiment.
- Candidate shared body for Android, iOS, desktop, and possibly web.
- Primary place to prove CultUI partitions, standard controls, control anatomy,
  and Repixelizer style tokens can be lowered once instead of repeatedly
  reimplemented per native toolkit.

First cuts:

- Scaffold a generic Eve Flutter app with the same provider picker as web.
- Load the same local provider advertisements and local fixture surfaces during
  development.
- Consume conformance-export provider entries through `EveProviderCatalog` and
  select them through `EveProviderPicker`; this is the split-ready provider
  picker input shape, distinct from web-local fallback fixture discovery.
- Lower `surface.root` recursively into Flutter widgets/custom painters.
- Lower CultUI partitions, `fieldRow`, labels, cards, buttons, metrics, and
  slider anatomy from `control.box`, `control.part`, and `control.hitArea`.
- Map Repixelizer tokens to Flutter fonts, colors, borders, shadows, image
  sampling, and panel treatments.
- Package or load Repixelizer fonts and verify they render on every Flutter
  target.
- Emit commands through the same `gamecult.eve.command.v1` shape as web.
- Capture parity screenshots for the CultUI Inspector and Repixelizer fixtures.

### Fensalir Direct2D

Role:

- Native desktop/game-runtime lowering through existing DirectWrite/Direct2D
  overlay machinery.

First cuts:

- Build an adapter from `gamecult.eve.surface.v1` to `AquariumUiDocument`.
- Map common style tokens to DirectWrite fonts, brushes, panel fills, borders,
  and pixel-art image sampling flags.
- Render the Repixelizer shell, cards, metrics, upload/action controls, and
  image preview placeholders before implementing the full editor canvas.
- Emit command documents through the same advertised command boundary as web.

### iOS / UIKit

Role:

- Native multitouch Eve app and sensor edge when direct UIKit ownership earns
  its keep beyond Flutter.

First cuts:

- Put the provider picker in front of the current native dashboard view.
- Route selected provider surfaces through the generic `surface.root` lowerer.
- Map common style tokens to UIKit colors, fonts, borders, and image sampling.
- Package or load Repixelizer pixel fonts.
- Add visual parity fixtures for Repixelizer shell and progress states.

### 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. This body may publish sensors,
  observe CultMesh dashboard compatibility traffic, and test Android-specific
  integrations. It is not the GUI parity oracle.

First cuts:

- Connect provider picker to the existing broker/provider path.
- Finish `surface.root` traversal beyond status/dashboard proof.
- Map `surface.styles.tokens` before hardcoded tone/text/font fallback rules.
- Package or cache Repixelizer pixel fonts.
- Lower image asset refs to pixelated `ImageView` content.
- Lower command controls to upload/document picker and provider job routes.

## Repixelizer Parity Contract

Repixelizer parity starts with recognizability, not total editor feature
completion. Each runtime should first prove:

- provider picker can open Repixelizer;
- title/body fonts are present and preserve the pixel-art profile well enough
  to be recognizable;
- background, panel, text, muted text, accent, border, and shadow tokens lower
  visibly;
- partition structure, padding, gaps, and standard control anatomy lower without
  runtime-specific reinvention;
- shell frame, card hierarchy, metrics, and primary action controls match the
  surface structure;
- image assets render with pixelated sampling;
- commands route through provider-owned command paths;
- missing editor/canvas features are reported as capability gaps, not silently
  replaced with fake controls.

Only after those hold should the runtimes chase full comparison canvas,
pan/zoom, eyedropper, pencil, and upload parity.

## Verification

Minimum parity verification should cover:

- static fixture render for each runtime;
- responsive fixture render for phone, tablet, and desktop viewports where the
  runtime can be resized;
- provider picker selection and re-selection;
- style token snapshot against the Repixelizer token set;
- command emission shape for primary controls;
- capability gap report for unsupported components;
- screenshot or frame capture for the first viewport where the runtime supports
  it.

The web reference remains the fastest behavior/debug oracle. Flutter should
become the preferred graphical parity oracle if it proves the CultUI Inspector
and Repixelizer fixtures can stay recognizable across its target platforms with
less duplicate renderer work.

The first shared harness is documented in
[parity-testing-harness.md](./parity-testing-harness.md). It currently checks
semantic fixture parity and records runtime capture gaps; screenshot adapters
plug into that manifest as each runtime becomes capture-capable.