From 6feb53cb7808a6d5ae50b25a0423665f4ef6f2b0 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 18 Jul 2026 08:02:41 +0000 Subject: [PATCH] docs: align platform READMEs with embedded vs sidecar reality Add a Runtime mode line to every traverse-starter and doc-approval client README, rewrite web-react starter for embedded WASM, and stop describing sidecar-interim natives as the same path as embedded web. Co-authored-by: Enrico Piovesan --- apps/doc-approval/android-compose/README.md | 8 ++- apps/doc-approval/cli-rust/README.md | 4 +- apps/doc-approval/ios-swift/README.md | 6 +- apps/doc-approval/linux-gtk/README.md | 4 +- apps/doc-approval/macos-swift/README.md | 6 +- apps/doc-approval/web-react/README.md | 4 +- apps/doc-approval/windows-winui/README.md | 6 +- .../android-compose/README.md | 8 ++- apps/traverse-starter/cli-rust/README.md | 4 +- apps/traverse-starter/ios-swift/README.md | 6 +- apps/traverse-starter/linux-gtk/README.md | 4 +- apps/traverse-starter/macos-swift/README.md | 6 +- apps/traverse-starter/web-react/README.md | 55 ++++--------------- apps/traverse-starter/windows-winui/README.md | 6 +- 14 files changed, 60 insertions(+), 67 deletions(-) diff --git a/apps/doc-approval/android-compose/README.md b/apps/doc-approval/android-compose/README.md index 8eacec0..cd17d4b 100644 --- a/apps/doc-approval/android-compose/README.md +++ b/apps/doc-approval/android-compose/README.md @@ -1,12 +1,14 @@ # doc-approval (Android Compose) -Native Android submitter client for the `doc-approval` reference app. Phase 1 uses HTTP polling via Ktor — same flow as `web-react`. +**Runtime mode: HTTP sidecar (interim)** — Phase 1 HTTP polling via Ktor. Embedded WASM cutover is tracked in [#115](https://github.com/traverse-framework/reference-apps/issues/115). Requires `traverse-cli serve`. (Web React for this app is already embedded; do not copy its path here.) + +Native Android submitter client for the `doc-approval` reference app. ## Prerequisites - **Android Studio Ladybug+** (or compatible AGP 8.7 / Kotlin 2.0) -- **Android emulator** API 26+ (or physical device on same network as runtime) -- **Traverse runtime** running on your host machine +- **Android emulator** API 26+ (or physical device on same network as the sidecar) +- **Traverse HTTP sidecar** running on your host machine ```bash git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse diff --git a/apps/doc-approval/cli-rust/README.md b/apps/doc-approval/cli-rust/README.md index 5a2c87f..1cf84e0 100644 --- a/apps/doc-approval/cli-rust/README.md +++ b/apps/doc-approval/cli-rust/README.md @@ -1,6 +1,8 @@ # doc-approval (Rust CLI) -Terminal client for the `doc-approval` reference app. Uses `doc-approval-core-rs` with the public **`traverse-embedder`** SDK. No `traverse-cli serve` sidecar. +**Runtime mode: embedded** — `doc-approval-core-rs` + public `traverse-embedder`. No `traverse-cli serve` sidecar is required. + +Terminal client for the `doc-approval` reference app. **Note:** production bundle init uses `manifests/doc-approval/`. Unit tests use `EmbedderTestDouble`. diff --git a/apps/doc-approval/ios-swift/README.md b/apps/doc-approval/ios-swift/README.md index 7eae943..7598f40 100644 --- a/apps/doc-approval/ios-swift/README.md +++ b/apps/doc-approval/ios-swift/README.md @@ -1,11 +1,13 @@ # doc-approval (iOS) -Native iOS submitter client for the **doc-approval** reference app. Uses shared `DocApprovalCore` for HTTP command dispatch and SSE app-state events. +**Runtime mode: HTTP sidecar (interim)** — shared `DocApprovalCore` HTTP command dispatch + SSE. Embedded WASM cutover is tracked in [#114](https://github.com/traverse-framework/reference-apps/issues/114). Requires `traverse-cli serve`. + +Native iOS submitter client for the **doc-approval** reference app. ## Prerequisites - Xcode 16+ -- Traverse runtime locally (`cargo run -p traverse-cli -- serve`) +- Traverse HTTP sidecar locally (`cargo run -p traverse-cli -- serve`) ## Open and run diff --git a/apps/doc-approval/linux-gtk/README.md b/apps/doc-approval/linux-gtk/README.md index e4ba094..ad81012 100644 --- a/apps/doc-approval/linux-gtk/README.md +++ b/apps/doc-approval/linux-gtk/README.md @@ -1,6 +1,8 @@ # doc-approval (Linux GTK4) -Native Linux client for `doc-approval`. Uses `doc-approval-core-rs` with **`traverse-embedder`** (Phase 3). No sidecar URL. +**Runtime mode: embedded** — `doc-approval-core-rs` + public `traverse-embedder`. No `traverse-cli serve` sidecar is required. + +Native Linux client for `doc-approval`. **Note:** Zone 1 shows Embedded / Ready when `manifests/doc-approval/` resolves (or `DOC_APPROVAL_MANIFEST`). diff --git a/apps/doc-approval/macos-swift/README.md b/apps/doc-approval/macos-swift/README.md index e84e9ce..ec3a8bb 100644 --- a/apps/doc-approval/macos-swift/README.md +++ b/apps/doc-approval/macos-swift/README.md @@ -1,11 +1,13 @@ # doc-approval (macOS) -Native macOS submitter client for the **doc-approval** reference app. Uses shared `DocApprovalCore` for HTTP command dispatch and SSE app-state events. +**Runtime mode: HTTP sidecar (interim)** — shared `DocApprovalCore` HTTP command dispatch + SSE. Embedded WASM cutover is tracked in [#114](https://github.com/traverse-framework/reference-apps/issues/114). Requires `traverse-cli serve`. + +Native macOS submitter client for the **doc-approval** reference app. ## Prerequisites - Xcode 16+ -- Traverse runtime locally (`cargo run -p traverse-cli -- serve`) +- Traverse HTTP sidecar locally (`cargo run -p traverse-cli -- serve`) ## Open and run diff --git a/apps/doc-approval/web-react/README.md b/apps/doc-approval/web-react/README.md index 516dd7c..6c95a9f 100644 --- a/apps/doc-approval/web-react/README.md +++ b/apps/doc-approval/web-react/README.md @@ -1,6 +1,8 @@ # doc-approval (Web React UI) -React UI shell for the **doc-approval** reference application. Submitter surface: paste document text, run `doc-approval.pipeline` via the embedded Traverse host (or HTTP execute on platforms still on sidecar), and render runtime-provided analysis + recommendation fields. +**Runtime mode: embedded** — in-app WASM via the public embedder host (`FetchBundleLoader` + bundled `doc-approval` manifest). No `traverse-cli serve` sidecar is required. + +React UI shell for the **doc-approval** reference application. Submitter surface: paste document text, run `doc-approval.pipeline`, and render runtime-provided analysis + recommendation fields. ## Core Design Principles diff --git a/apps/doc-approval/windows-winui/README.md b/apps/doc-approval/windows-winui/README.md index 04e0ad4..f20c611 100644 --- a/apps/doc-approval/windows-winui/README.md +++ b/apps/doc-approval/windows-winui/README.md @@ -1,12 +1,14 @@ # doc-approval (Windows WinUI 3) -Native Windows submitter client for the `doc-approval` reference app. Phase 1 uses HTTP polling against the public Traverse HTTP/JSON API (spec 033) — same flow as `web-react`, `ios-swift`, and `android-compose`. +**Runtime mode: HTTP sidecar (interim)** — Phase 1 HTTP polling against the public Traverse HTTP/JSON API (spec 033). Embedded WASM cutover is tracked in [#116](https://github.com/traverse-framework/reference-apps/issues/116). Requires `traverse-cli serve`. (Web React for this app is already embedded; do not copy its path here.) + +Native Windows submitter client for the `doc-approval` reference app. ## Prerequisites - **Windows 10 1809+** (build 17763) or Windows 11 - **Visual Studio 2022** with the **Windows App SDK** and **.NET desktop development** workloads -- **Traverse runtime** running locally +- **Traverse HTTP sidecar** running locally ```bash git clone https://github.com/traverse-framework/Traverse.git C:\temp\traverse diff --git a/apps/traverse-starter/android-compose/README.md b/apps/traverse-starter/android-compose/README.md index 98468f6..0a0c649 100644 --- a/apps/traverse-starter/android-compose/README.md +++ b/apps/traverse-starter/android-compose/README.md @@ -1,12 +1,14 @@ # traverse-starter (Android Compose) -Native Android client for the `traverse-starter` reference app. Phase 1 uses HTTP polling via Ktor — same flow as `web-react`. +**Runtime mode: HTTP sidecar (interim)** — Phase 1 HTTP polling via Ktor against the public HTTP/JSON API. Embedded WASM cutover is tracked in [#115](https://github.com/traverse-framework/reference-apps/issues/115). Requires `traverse-cli serve`. (Web React is already embedded; do not copy its path here.) + +Native Android client for the `traverse-starter` reference app. ## Prerequisites - **Android Studio Ladybug+** (or compatible AGP 8.7 / Kotlin 2.0) -- **Android emulator** API 26+ (or physical device on same network as runtime) -- **Traverse runtime** running on your host machine +- **Android emulator** API 26+ (or physical device on same network as the sidecar) +- **Traverse HTTP sidecar** running on your host machine ```bash git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse diff --git a/apps/traverse-starter/cli-rust/README.md b/apps/traverse-starter/cli-rust/README.md index b7cb70a..891ea08 100644 --- a/apps/traverse-starter/cli-rust/README.md +++ b/apps/traverse-starter/cli-rust/README.md @@ -1,6 +1,8 @@ # traverse-starter (Rust CLI) -Terminal client for the `traverse-starter` reference app. Uses the shared `traverse-core-rs` crate with the public **`traverse-embedder`** SDK (Phase 3 embedded runtime). No `traverse-cli serve` sidecar is required. +**Runtime mode: embedded** — public `traverse-embedder` SDK via `traverse-core-rs`. No `traverse-cli serve` sidecar is required. + +Terminal client for the `traverse-starter` reference app. ## Prerequisites diff --git a/apps/traverse-starter/ios-swift/README.md b/apps/traverse-starter/ios-swift/README.md index e4971e9..7af16a5 100644 --- a/apps/traverse-starter/ios-swift/README.md +++ b/apps/traverse-starter/ios-swift/README.md @@ -1,11 +1,13 @@ # traverse-starter (iOS SwiftUI) -Native iOS client for the `traverse-starter` reference app. Uses shared [`TraverseCore`](../TraverseCore/) for HTTP command dispatch + SSE app state (same pattern as `web-react` after #43). +**Runtime mode: HTTP sidecar (interim)** — uses shared [`TraverseCore`](../TraverseCore/) for HTTP command dispatch + SSE. Embedded WASM cutover is tracked in [#114](https://github.com/traverse-framework/reference-apps/issues/114). Requires `traverse-cli serve`. + +Native iOS client for the `traverse-starter` reference app. ## Prerequisites - **Xcode 16+** with iOS 17 simulator -- **Traverse runtime** running locally or on your LAN +- **Traverse HTTP sidecar** running locally or on your LAN ```bash git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse diff --git a/apps/traverse-starter/linux-gtk/README.md b/apps/traverse-starter/linux-gtk/README.md index ec53cc0..f993f47 100644 --- a/apps/traverse-starter/linux-gtk/README.md +++ b/apps/traverse-starter/linux-gtk/README.md @@ -1,6 +1,8 @@ # traverse-starter (Linux GTK4) -Native Linux client for the `traverse-starter` reference app. Uses the shared `traverse-core-rs` crate with the public **`traverse-embedder`** SDK (Phase 3 embedded runtime). No `traverse-cli serve` sidecar is required. +**Runtime mode: embedded** — public `traverse-embedder` SDK via `traverse-core-rs`. No `traverse-cli serve` sidecar is required. + +Native Linux client for the `traverse-starter` reference app. ## Prerequisites diff --git a/apps/traverse-starter/macos-swift/README.md b/apps/traverse-starter/macos-swift/README.md index 86c57ef..352deb7 100644 --- a/apps/traverse-starter/macos-swift/README.md +++ b/apps/traverse-starter/macos-swift/README.md @@ -1,11 +1,13 @@ # traverse-starter (macOS SwiftUI) -Native macOS client for the `traverse-starter` reference app. Uses shared [`TraverseCore`](../TraverseCore/) for HTTP command dispatch + SSE app state (same pattern as `web-react` / `ios-swift`). +**Runtime mode: HTTP sidecar (interim)** — uses shared [`TraverseCore`](../TraverseCore/) for HTTP command dispatch + SSE. Embedded WASM cutover is tracked in [#114](https://github.com/traverse-framework/reference-apps/issues/114). Requires `traverse-cli serve`. + +Native macOS client for the `traverse-starter` reference app. ## Prerequisites - **Xcode 16+** on macOS -- **Traverse runtime** running locally +- **Traverse HTTP sidecar** running locally ```bash git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse diff --git a/apps/traverse-starter/web-react/README.md b/apps/traverse-starter/web-react/README.md index 4b7e094..5431272 100644 --- a/apps/traverse-starter/web-react/README.md +++ b/apps/traverse-starter/web-react/README.md @@ -1,52 +1,28 @@ # traverse-starter (Web React UI) -This is the React UI shell for the `traverse-starter` reference application. It is a thin presentation layer that connects to the Traverse runtime over the public HTTP/JSON API (spec 033). +**Runtime mode: embedded** — in-app WASM via the public `traverse-embedder-web` package (`BundleEmbedder` + `FetchBundleLoader`). No `traverse-cli serve` sidecar is required. + +React UI shell for the `traverse-starter` reference application. The UI submits note input and renders runtime-owned output only. ## Core Design Principles 1. **UI is a rendering layer only** — business fields (title, tags, note type, suggested next action, status) come from the runtime. The UI displays them; it does not compute them. -2. **Strict boundary isolation** — no private Traverse internals are imported. All communication uses public runtime surfaces. - -## Configuration & Runtime Discovery +2. **Strict boundary isolation** — no private Traverse internals are imported. All communication uses public embedder surfaces. -The app reads runtime settings from Vite env vars. Defaults match a local `traverse-cli serve` instance: +## Configuration | Variable | Default | Purpose | |---|---|---| -| `VITE_TRAVERSE_BASE_URL` | `http://127.0.0.1:8787` | Runtime base URL (`/healthz`, execute, poll, trace) | -| `VITE_TRAVERSE_WORKSPACE` | `local-default` | Workspace ID | -| `VITE_TRAVERSE_CAPABILITY_ID` | `traverse-starter.process` | Capability to execute | - -Legacy alias: `VITE_TRAVERSE_RUNTIME_URL` is accepted as a fallback for `VITE_TRAVERSE_BASE_URL`. - -Copy or edit `apps/traverse-starter/web-react/.env`: - -```bash -VITE_TRAVERSE_BASE_URL=http://127.0.0.1:8787 -VITE_TRAVERSE_WORKSPACE=local-default -VITE_TRAVERSE_CAPABILITY_ID=traverse-starter.process -``` - -On startup, the runtime writes `.traverse/server.json` with `base_url` and `workspace_default` — use those values if your port differs. - -See [docs/traverse-runtime.md](../../../docs/traverse-runtime.md) for pinned versions and Phase 1 vs Phase 2 requirements. +| `VITE_TRAVERSE_STARTER_MANIFEST` | `/bundles/traverse-starter/app.manifest.json` | FetchBundleLoader manifest path | -## Start the Traverse Runtime - -```bash -git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse -cd /tmp/traverse && git checkout v0.6.0 # or v0.3.0+ for Phase 1 HTTP only -cargo run -p traverse-cli -- serve -``` - -For active Traverse framework development: +Sync a local bundle (requires `TRAVERSE_REPO`): ```bash export TRAVERSE_REPO=/path/to/Traverse -cd "$TRAVERSE_REPO" && cargo run -p traverse-cli -- serve +bash scripts/ci/sync_web_starter_bundle.sh ``` -Do not commit `TRAVERSE_REPO` into app code — it is a local developer override only. +Optional **HTTP sidecar (Phase 1/2 interim)** is not the production path for this client. Prefer the embedded host above. Sidecar docs live in [`docs/traverse-runtime.md`](../../../docs/traverse-runtime.md) for platforms still blocked on [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116). ## Development Commands @@ -54,7 +30,7 @@ Run from the **repository root**: ```bash npm install -npm run dev # starts traverse-starter dev server +npm run dev # starts traverse-starter embedded web shell npm run build npm run typecheck npm run lint @@ -62,13 +38,4 @@ npm run test npm run test:coverage ``` -## Smoke Tests - -```bash -# Phase 1 — requires runtime at 127.0.0.1:8787 (or TRAVERSE_RUNTIME_URL) -bash scripts/ci/phase1_smoke.sh - -# Phase 2 — requires TRAVERSE_REPO pointing at Traverse main/v0.5.0+ -export TRAVERSE_REPO=/path/to/Traverse -bash scripts/ci/phase2_smoke.sh -``` +Open `http://localhost:5173`. When the embedded host is ready, submit a note and confirm runtime-owned fields render in the output panel. diff --git a/apps/traverse-starter/windows-winui/README.md b/apps/traverse-starter/windows-winui/README.md index e515dba..c8017c5 100644 --- a/apps/traverse-starter/windows-winui/README.md +++ b/apps/traverse-starter/windows-winui/README.md @@ -1,12 +1,14 @@ # traverse-starter (Windows WinUI 3) -Native Windows client for the `traverse-starter` reference app. Phase 1 uses HTTP polling against the public Traverse HTTP/JSON API (spec 033) — same flow as `web-react`, `ios-swift`, and `android-compose`. +**Runtime mode: HTTP sidecar (interim)** — Phase 1 HTTP polling against the public Traverse HTTP/JSON API (spec 033). Embedded WASM cutover is tracked in [#116](https://github.com/traverse-framework/reference-apps/issues/116). Requires `traverse-cli serve`. (Web React is already embedded; do not copy its path here.) + +Native Windows client for the `traverse-starter` reference app. ## Prerequisites - **Windows 10 1809+** (build 17763) or Windows 11 - **Visual Studio 2022** with the **Windows App SDK** and **.NET desktop development** workloads -- **Traverse runtime** running locally +- **Traverse HTTP sidecar** running locally ```bash git clone https://github.com/traverse-framework/Traverse.git C:\temp\traverse