diff --git a/docs/renderer-parity.md b/docs/renderer-parity.md index e594a8e..cad8797 100644 --- a/docs/renderer-parity.md +++ b/docs/renderer-parity.md @@ -4,24 +4,35 @@ Parity is currently uneven by design. The shared surface contract is forming, but the browser reference is the first renderer that can be used as a practical comparison oracle. +See [runtime-app-parity-roadmap.md](./runtime-app-parity-roadmap.md) for the +generic Eve app plan across web, Fensalir Direct2D, iOS/UIKit, and +Android/Kotlin. Repixelizer is the first style-parity target. + ## Current State | Renderer | Status | Proof | Gap | | --- | --- | --- | --- | -| Browser | First reference runner | `web/` renders live VoidBot and Fensalir fixture surfaces | Needs visual regression fixtures and command round-trip tests | -| iOS / EveCanvas | Native proof | Renders Odin's fullscreen interface wall from `surface.root`, generic provider trees, and a custom VoidBot cockpit with avatar images | Needs visual regression fixtures for the native Odin wall | -| Android / Periwinkle | Device-edge proof | APK builds and shows broker/sensor status | Install blocked until device allows ADB sideload; dashboard rendering is not implemented | -| Fensalir Direct2D | Documented landing zone | Existing `AquariumUiDocument` and `DirectWriteOverlay` path | Needs adapter from Eve surface document to `AquariumUiDocument` | +| Web reference | First generic app target | `web/` renders live VoidBot and fixture surfaces | Needs provider picker, Repixelizer fixture, visual regression fixtures, and command round-trip tests | +| iOS / UIKit | Native proof | Renders Odin's fullscreen interface wall from `surface.root`, generic provider trees, and a custom VoidBot cockpit with avatar images | Needs provider picker, Repixelizer style token lowering, and visual parity fixtures | +| Android / Kotlin | Device-edge proof | APK builds and shows broker/sensor status | Needs provider picker, full surface tree rendering, style token lowering, asset image lowering, and command controls | +| Fensalir Direct2D | Documented landing zone | Existing `AquariumUiDocument` and `DirectWriteOverlay` path | Needs adapter from Eve surface document to `AquariumUiDocument` and DirectWrite/Direct2D token lowering | | Flutter | Candidate shared native path | Not installed locally | Needs toolchain and client scaffold | ## Spawned Surfaces -The browser reference runner spawns two surfaces: +The browser reference runner currently exposes hardcoded fixture/live tabs: - `VoidBot Live`: connects to Mimir's `/eve/deck` broker and opens `voidbot.swarm`. - `Fensalir Direct2D`: loads `web/fixtures/fensalir-client-surface.json`, a recorded surface describing the Direct2D client lowering path. +- `Sai VN Surface`: loads `web/fixtures/sai-vn-surface.json`. +- `Huginn .cc`: compiles `web/fixtures/huginn-cc-surface.eve`. +- `Reactive DSL`: compiles `web/fixtures/reactive-composition.eve`. + +Those tabs are temporary probes. The runtime app target is a provider picker +fed by `gamecult.eve.provider_advertisement.v1`, with fixtures represented as +local advertisements. Start it with: diff --git a/docs/runtime-app-parity-roadmap.md b/docs/runtime-app-parity-roadmap.md new file mode 100644 index 0000000..7c9a7f1 --- /dev/null +++ b/docs/runtime-app-parity-roadmap.md @@ -0,0 +1,204 @@ +# Eve Runtime App Parity Roadmap + +Eve should exist as one generic app per supported runtime: + +- Web reference +- Fensalir Direct2D / DirectWrite +- iOS / UIKit +- Android / Kotlin + +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. + +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, Direct2D, +iOS, and Android before expanding into broader product coverage. + +## 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: + +- Native 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, 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. +- Visual parity screenshot source. + +First cuts: + +- Replace hardcoded tabs with a provider picker. +- Represent existing fixtures as provider advertisements. +- 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. + +### 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. + +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 / Kotlin + +Role: + +- Native Kotlin Eve app and Periwinkle device edge. + +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 preserve the pixel-art profile; +- background, panel, text, muted text, accent, border, and shadow tokens lower + visibly; +- 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; +- 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 visual oracle until a better cross-runtime +snapshot harness exists.