hemx/examples/workout/README.md

Now-first Workout Copilot example

This is the phone-first local-first product exemplar for hemx. It shows a complete useful session: next action shown, set completed, rest/next state entered, progress updated, a mistyped set corrected and undone, workout finished, final export shared or replayed, and invalid input, replay failure, or host denial recovered without storing DOM patches or UI update payloads as truth. req: examples/001 req: local/001 req: local/003 req: local/004

Create

cargo run -p hemx-xtask -- workout new /tmp/my-workout-app
cargo check --manifest-path /tmp/my-workout-app/Cargo.toml

The created app is standalone: it points at local hemx crates, owns its command/event/projection state, and keeps Android/iOS signing outside the repo. req: examples/006

Run

cargo run -p hemx-xtask -- workout dev

Open http://127.0.0.1:3028.

If the port is busy, pick another address:

HEMX_WORKOUT_ADDR=127.0.0.1:3030 cargo run -p hemx-xtask -- workout dev

The server prints the URL it bound. A bind failure means another process owns the address; retry with HEMX_WORKOUT_ADDR instead of changing app code.

Test

cargo run -p hemx-xtask -- workout test

The E2E test starts the real HTTP binary, loads the page, checks the shared runtime asset, submits workout interactions, decodes hemx effect responses, and replays exported events back into a projection. Unit tests cover rest/next, finish, undo recovery, invalid input, replay failure, export replay, and host-result boundaries. req: test/001 req: examples/001

For the full repository gate:

cargo run -p hemx-xtask -- test

Deploy shape

The deployable artifact is the Rust server binary plus the generated hemx resources embedded by the build script:

cargo run -p hemx-xtask -- workout build
HEMX_WORKOUT_ADDR=0.0.0.0:8080 ./target/release/hemx-workout-example

Put a normal reverse proxy or platform router in front of that port. The app serves the shared hemx runtime through hemx-axum; there is no frontend build, Node runtime, Expo/Ionic/Tauri shell, or handwritten selector UI JavaScript to ship. req: axum_integration/005 req: examples/005

Mobile release kit

Use the canonical release command to build the production server binary and write Android/iOS shell metadata:

HEMX_WORKOUT_ORIGIN=https://workout.example.com \
  cargo run -p hemx-xtask -- workout mobile-release
HEMX_WORKOUT_ORIGIN=https://workout.example.com \
  cargo run -p hemx-xtask -- workout mobile-verify

The kit lands in target/hemx-mobile/workout unless HEMX_WORKOUT_MOBILE_OUT is set. workout mobile-verify reruns the Workout product tests before checking the release kit, so app value, recovery, local state, and host capability boundaries fail closed with the mobile artifacts. The kit records app identity, version, production origin, runtime asset policy, cache/offline state policy, secrets/signing boundaries, rollback expectations, Android TWA metadata, iOS WebView metadata, and any external blocker such as missing Android SDK, Xcode, store signing credentials, or Play/App Store submission account targets. See docs/recipes/mobile-release.md. req: examples/006

Boundaries proven

• Core workout logging works without network availability once the page/runtime is loaded: commands/events/projections are app truth, including rest/next, finish, invalid input, replay failure, and undo recovery. req: local/001
• Browser/PWA export uses the host capability contract and the host result returns through app code before UI effects. req: host/001 req: host/005
• Native-shell-shaped haptic acknowledgment uses the same host call/event path without giving the shell ownership of workout state. req: host/002
• Sync, backup, auth, AI/STT, provider policy, and conflict handling are not hidden in hemx core or the example runtime; they remain explicit app or integration decisions. req: local/002 req: local/003