diff --git a/README.md b/README.md index b383625..f148115 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Reference UI applications for the [Traverse](https://github.com/traverse-framewo **Architecture in one sentence:** This repo is UI-only. Each platform ships a **native UI shell** with an **embedded Traverse WASM runtime** (Phase 3 target). Business logic lives in bundled WASM agents; the UI starts workflows and renders runtime-provided output only. -> **Current state:** Phase 1/2 clients still use an HTTP dev sidecar (`traverse-cli serve`). Phase 3 migration is tracked on [Project 2](https://github.com/orgs/traverse-framework/projects/2). See [`docs/embedded-runtime-plan.md`](docs/embedded-runtime-plan.md). +> **Current state:** Web / Linux / CLI embed the WASM runtime (no sidecar). Apple / Android / Windows still use the HTTP sidecar interim until [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116). Start with [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md). ## Prerequisites @@ -14,39 +14,44 @@ Reference UI applications for the [Traverse](https://github.com/traverse-framewo - **Rust 1.94+** (to build and run the Traverse runtime) - **`gh` CLI** (for agents claiming Project 2 tickets) -## Getting Started (Phase 1/2 dev sidecar) +## Getting Started (embedded — production path) -Until Phase 3 embedded runtime lands, local development uses a separate Traverse process. +Business logic lives in WASM once; each UI shell only submits input and renders runtime-owned fields. **Web React, Linux GTK, and Rust CLI** already embed — no `traverse-cli serve` required. -**1. Clone and install** +Follow the guided walkthrough: **[`docs/getting-started-embedded.md`](docs/getting-started-embedded.md)**. + +**Quick start (Web):** ```bash git clone https://github.com/traverse-framework/reference-apps.git cd reference-apps npm install +export TRAVERSE_REPO=/path/to/Traverse # checkout with example WASM +bash scripts/ci/sync_web_starter_bundle.sh +npm run dev # traverse-starter embedded web shell ``` -**2. Start the Traverse dev sidecar** (separate terminal — not required in Phase 3) +Open `http://localhost:5173`. Submit a note when the embedded host is ready; confirm title / tags / note type / suggested next action / status come from the runtime. + +Other Vite apps (one at a time on port 5173): ```bash -git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse -cd /tmp/traverse && git checkout v0.6.0 -cargo run -p traverse-cli -- serve +npm run dev -w apps/doc-approval/web-react # embedded + pipeline +npm run dev -w apps/meeting-notes/web-react # meeting-notes +npm run dev -w apps/trace-explorer/web-react # trace-explorer ``` -The runtime listens on `http://127.0.0.1:8787` by default and writes `.traverse/server.json` with `base_url` and `workspace_default`. See [`docs/traverse-runtime.md`](docs/traverse-runtime.md) for pinned versions and API details. +### Dev sidecar (Phase 1/2 interim) -**3. Start a web client** (from the repo root; only one Vite app at a time on port 5173) +Apple / Android / Windows clients (and optional HTTP integration) still use a separate Traverse process until [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116) complete: ```bash -npm run dev # traverse-starter (default) -npm run dev -w apps/doc-approval/web-react # doc-approval -npm run dev -w apps/meeting-notes/web-react # meeting-notes -npm run dev -w apps/trace-explorer/web-react # trace-explorer +git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse +cd /tmp/traverse && git checkout v0.6.0 +cargo run -p traverse-cli -- serve ``` -Open `http://localhost:5173`. Submit input when the runtime health strip shows **Online**. - +The sidecar listens on `http://127.0.0.1:8787` and writes `.traverse/server.json`. See [`docs/traverse-runtime.md`](docs/traverse-runtime.md). Prefer the embedded guide above for platforms marked **Shipped (embedded)**. ## What You Will See ### traverse-starter @@ -96,8 +101,9 @@ Each app also ships native clients (iOS, macOS, Android, Windows, Linux, CLI) wh | [`apps/macos-demo/`](apps/macos-demo/) | Expedition macOS demo | | [`apps/youaskm3-starter-kit/`](apps/youaskm3-starter-kit/) | youaskm3 browser starter kit | | [`docs/adopted-platform-clients.md`](docs/adopted-platform-clients.md) | Canonical homes for adopted Traverse demos | +| [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md) | Embedded-first onboarding (Web + Linux/CLI) | | [`docs/embedded-runtime-plan.md`](docs/embedded-runtime-plan.md) | Phase 3 target — embedded runtime + multi-capability workflows | -| [`docs/traverse-runtime.md`](docs/traverse-runtime.md) | Dev sidecar setup (Phase 1/2) | +| [`docs/traverse-runtime.md`](docs/traverse-runtime.md) | Dev sidecar setup (Phase 1/2 interim) | | [`manifests/traverse-starter/`](manifests/traverse-starter/) | App manifest + component manifests (Phase 2) | | [`fixtures/`](fixtures/) | Shared UI demo fixtures (e.g. expedition session) | | [`scripts/ci/`](scripts/ci/) | Repository checks, smoke tests, coverage gate | diff --git a/apps/youaskm3-starter-kit/README.md b/apps/youaskm3-starter-kit/README.md index 52adbe1..40fef3c 100644 --- a/apps/youaskm3-starter-kit/README.md +++ b/apps/youaskm3-starter-kit/README.md @@ -17,6 +17,7 @@ Use this starter kit as the first place a downstream app developer looks when wi ## Included References +- [Embedded getting started (this repo)](../../docs/getting-started-embedded.md) — WASM-once / UI-shell model on Web + Linux/CLI - [Consumer bundle (Traverse)](https://github.com/traverse-framework/Traverse/blob/main/docs/app-consumable-consumer-bundle.md) - [Starter kit guide (this repo)](../../docs/youaskm3-starter-kit.md) - [Integration validation (Traverse)](https://github.com/traverse-framework/Traverse/blob/main/docs/youaskm3-integration-validation.md) diff --git a/docs/embedded-runtime-plan.md b/docs/embedded-runtime-plan.md index bd84157..382528e 100644 --- a/docs/embedded-runtime-plan.md +++ b/docs/embedded-runtime-plan.md @@ -10,6 +10,8 @@ App-References must demonstrate the **production-shaped** Traverse integration m Phase 1 (HTTP sidecar) and Phase 2 (CLI registration into a sidecar) remain valid **developer/integration** paths until Phase 3 lands. They are **not** the target production architecture. +**Hands-on onboarding (embedded platforms already shipped):** [`getting-started-embedded.md`](getting-started-embedded.md). + ## Architecture Boundary (unchanged) | Concern | Lives in | diff --git a/docs/getting-started-embedded.md b/docs/getting-started-embedded.md new file mode 100644 index 0000000..dbfc54f --- /dev/null +++ b/docs/getting-started-embedded.md @@ -0,0 +1,123 @@ +# Getting Started — Embedded Traverse Apps + +Build a Traverse app where **business logic lives once in WASM** and every UI shell only submits input and renders runtime-owned output. This guide uses platforms that already embed successfully today. + +> **Not this path?** Apple / Android / Windows clients still use the HTTP sidecar interim until [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116) land. See each platform README’s **Runtime mode** line and [`traverse-runtime.md`](traverse-runtime.md). + +## Mental model + +| Layer | Responsibility | Lives in | +|---|---|---| +| WASM agents + workflow | Business decisions (title, tags, recommendation, …) | Traverse examples / capabilities | +| App + component manifests | Bundle identity, component digests, workflow wiring | This repo — `manifests//` | +| Platform UI shell | Submit input, render runtime fields, show status | This repo — `apps///` | + +The UI **never** computes business fields. Same note in → same runtime-owned fields out, on every embedded platform. + +## Prerequisites + +- **Node.js 24+** (see `.nvmrc`) — for the Web React shell +- **Rust 1.78+** via [rustup](https://rustup.rs/) — for Linux GTK / CLI +- A local **Traverse** checkout with example WASM (set `TRAVERSE_REPO`) + +```bash +git clone https://github.com/traverse-framework/Traverse.git ../Traverse +export TRAVERSE_REPO="$(cd ../Traverse && pwd)" +``` + +## 1. Clone App-References and install + +```bash +git clone https://github.com/traverse-framework/reference-apps.git +cd reference-apps +npm install +``` + +## 2. Run embedded traverse-starter on Web (no sidecar) + +Sync the application bundle into the Vite public tree, then start the shell: + +```bash +export TRAVERSE_REPO=/path/to/Traverse +bash scripts/ci/sync_web_starter_bundle.sh +npm run dev # apps/traverse-starter/web-react +``` + +Open `http://localhost:5173`. When the runtime strip shows the embedded host is ready: + +1. Submit a fixed note, e.g. `Meeting with Alice about project X` +2. Confirm the output panel shows runtime-owned fields: **title**, **tags**, **note type**, **suggested next action**, **status** +3. Confirm you did **not** start `traverse-cli serve` + +Details: [`apps/traverse-starter/web-react/README.md`](../apps/traverse-starter/web-react/README.md). + +## 3. Run the same app on Linux GTK or CLI + +Link the public `traverse-embedder` crate from your Traverse checkout, then build: + +```bash +export TRAVERSE_REPO=/path/to/Traverse +bash scripts/ci/phase2_link_traverse.sh + +cd apps/traverse-starter +cargo test -p traverse-core-rs +``` + +**CLI:** + +```bash +cargo run -p traverse-starter-cli -- run --note "Meeting with Alice about project X" +cargo run -p traverse-starter-cli -- health +``` + +**Linux GTK** (Ubuntu 22.04+ with `libgtk-4-dev` / `libadwaita-1-dev`): + +```bash +sudo apt install libgtk-4-dev libadwaita-1-dev # once +cargo run -p traverse-starter-gtk +``` + +Submit the same note. Zone 1 should show **Embedded**; output fields must match the Web run (same runtime-owned shape). + +- [`apps/traverse-starter/cli-rust/README.md`](../apps/traverse-starter/cli-rust/README.md) +- [`apps/traverse-starter/linux-gtk/README.md`](../apps/traverse-starter/linux-gtk/README.md) + +## 4. Where to change business logic vs UI + +| Want to change… | Edit… | Do not… | +|---|---|---| +| Title / tags / next action rules | Traverse WASM agents + `traverse-starter.pipeline` workflow | Hard-code fields in React/Swift/Compose | +| Which components the app loads | `manifests/traverse-starter/` | Invent fake execute/poll stubs in the UI | +| Layout, copy, accessibility | `apps/traverse-starter//` | Import private Traverse internals | + +Showcase workflow: `traverse-starter.pipeline` (`validate` → `process` → `summarize`). See [`embedded-runtime-plan.md`](embedded-runtime-plan.md). + +## 5. Add another platform UI + +Checklist for a new shell (or promoting a sidecar client to embedded): + +1. Depend on the **public** platform embedder SDK (Web: `traverse-embedder-web`; Rust: `traverse-embedder`; others when [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116) ship) +2. Bundle `manifests//` + WASM artifacts for the host loader +3. Submit workflow input; subscribe to embedder events; render only runtime-owned fields +4. Document **Runtime mode: embedded** in that platform’s README +5. Keep HTTP sidecar docs only as an interim path until cutover + +## Platform matrix (current) + +| Platform | Runtime mode | Notes | +|---|---|---| +| Web React | **Embedded** | [#113](https://github.com/traverse-framework/reference-apps/issues/113) shipped | +| Linux GTK | **Embedded** | [#117](https://github.com/traverse-framework/reference-apps/issues/117) shipped | +| Rust CLI | **Embedded** | [#117](https://github.com/traverse-framework/reference-apps/issues/117) shipped | +| iOS / macOS | HTTP sidecar (interim) | Embed blocked on [#114](https://github.com/traverse-framework/reference-apps/issues/114) | +| Android | HTTP sidecar (interim) | Embed blocked on [#115](https://github.com/traverse-framework/reference-apps/issues/115) | +| Windows | HTTP sidecar (interim) | Embed blocked on [#116](https://github.com/traverse-framework/reference-apps/issues/116) | + +Same matrix for `doc-approval` (embedded Web / Linux / CLI with `doc-approval.pipeline`). Status labels in the root [`README.md`](../README.md) **Platform clients** table remain the source of truth. + +## Related docs + +- [`embedded-runtime-plan.md`](embedded-runtime-plan.md) — Phase 3 architecture +- [`traverse-starter-plan.md`](traverse-starter-plan.md) — app plan across phases +- [`traverse-runtime.md`](traverse-runtime.md) — **Dev sidecar (Phase 1/2 interim)** only +- [`youaskm3-starter-kit.md`](youaskm3-starter-kit.md) — browser consumer adoption path diff --git a/docs/traverse-starter-plan.md b/docs/traverse-starter-plan.md index 888a9be..7336ada 100644 --- a/docs/traverse-starter-plan.md +++ b/docs/traverse-starter-plan.md @@ -6,7 +6,7 @@ - **Phase 1**: UI → HTTP execute → poll → render runtime-provided structured output (dev sidecar) - **Phase 2**: app manifest → `traverse-cli app validate` → `traverse-cli app register` → sidecar loads capability → UI invokes it end-to-end -- **Phase 3**: native UI → **embedded in-app WASM runtime** → multi-capability workflow → render runtime-provided output (production target — see [`embedded-runtime-plan.md`](embedded-runtime-plan.md)) +- **Phase 3**: native UI → **embedded in-app WASM runtime** → multi-capability workflow → render runtime-provided output (production target — see [`embedded-runtime-plan.md`](embedded-runtime-plan.md); hands-on path: [`getting-started-embedded.md`](getting-started-embedded.md)) ## Architecture Boundary diff --git a/docs/youaskm3-starter-kit.md b/docs/youaskm3-starter-kit.md index 804d6d3..510e181 100644 --- a/docs/youaskm3-starter-kit.md +++ b/docs/youaskm3-starter-kit.md @@ -10,6 +10,8 @@ This youaskm3 starter kit and integration guide is the canonical browser-hosted Give a downstream app team one clear adoption path for Traverse without forcing them to reverse-engineer either repository. +For the **embedded reference-app** walkthrough (WASM once, UI shells everywhere — Web / Linux / CLI), start with [`getting-started-embedded.md`](getting-started-embedded.md). This youaskm3 kit is the **browser consumer-bundle** path for downstream hosts. + ## What to Install Downstream apps should adopt the versioned Traverse consumer bundle and the browser-targeted consumer package: