Adopt Traverse platform reference clients (#151)

AGENTS.md

@@ -13,7 +13,7 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \
 
 - **Phase 3 embedded runtime** ([#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116)) — blocked on remaining consumable embedder SDKs: Traverse [#647](https://github.com/traverse-framework/Traverse/issues/647) (Swift), [#648](https://github.com/traverse-framework/Traverse/issues/648) (Kotlin), [#649](https://github.com/traverse-framework/Traverse/issues/649) (.NET). Rust (#650) and Web/TS (#646) embedder SDKs shipped; App-Refs [#117](https://github.com/traverse-framework/reference-apps/issues/117) Linux/CLI and [#113](https://github.com/traverse-framework/reference-apps/issues/113) web-react embed shipped.
 
-Ready: (none — claim from Project 2 when new Ready items appear).
+Ready: (none after #151 — claim from Project 2 when new Ready items appear).
 
 Update this section when a PR changes platform status (see PR template checklist).
 

CLAUDE.md

@@ -18,8 +18,16 @@ apps/
     windows-winui/       # WinUI 3 Windows client
     linux-gtk/           # GTK4 + Rust Linux client
     cli-rust/            # Rust CLI client
+  doc-approval/          # doc-approval clients (all platforms)
+  meeting-notes/         # meeting-notes clients
   trace-explorer/
     web-react/           # Trace Explorer — execution timeline debugger
+  react-demo/            # Expedition React browser demo (adopted from Traverse)
+  browser-consumer/      # Browser consumer façade
+  android-demo/          # Expedition Android demo
+  macos-demo/            # Expedition macOS demo
+  youaskm3-starter-kit/  # Downstream browser starter kit
+fixtures/                # Shared UI demo fixtures
 .agents/skills/
   app-refs-ops/          # Ops skill for executing Project 2 tickets
 .specify/memory/         # Constitution and governing principles

README.md

@@ -90,9 +90,16 @@ Each app also ships native clients (iOS, macOS, Android, Windows, Linux, CLI) wh
 | [`apps/doc-approval/`](apps/doc-approval/) | doc-approval clients (all platforms) |
 | [`apps/meeting-notes/`](apps/meeting-notes/) | meeting-notes clients (web-react shipped) |
 | [`apps/trace-explorer/web-react/`](apps/trace-explorer/web-react/) | Trace Explorer — execution timeline debugger |
+| [`apps/react-demo/`](apps/react-demo/) | Expedition React browser demo (adopted from Traverse) |
+| [`apps/browser-consumer/`](apps/browser-consumer/) | Browser consumer façade for downstream apps |
+| [`apps/android-demo/`](apps/android-demo/) | Expedition Android demo |
+| [`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/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) |
 | [`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 |
 
 ## Platform clients

apps/android-demo/README.md

@@ -0,0 +1,27 @@
+# Traverse Android Demo
+
+Checked-in Android (Compose) demo for Traverse expedition planning.
+
+Canonical home: **`traverse-framework/reference-apps`** (`apps/android-demo/`).
+
+What it does:
+
+- renders one approved expedition flow
+- shows ordered runtime state updates
+- shows the final trace summary and output panel
+- assumes the runtime exists outside the app process
+
+Fixture-driven rendering uses `app/src/main/assets/expedition-runtime-session.json`.
+
+## Build (machine with Android SDK)
+
+```bash
+cd apps/android-demo
+./gradlew :app:assembleDebug
+```
+
+## Validation
+
+```bash
+bash scripts/ci/android_demo_smoke.sh
+```

apps/android-demo/app/build.gradle.kts

@@ -0,0 +1,42 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.traverse.demo.android"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "com.traverse.demo.android"
+        minSdk = 28
+        targetSdk = 35
+        versionCode = 1
+        versionName = "0.1.0"
+    }
+
+    buildFeatures {
+        compose = true
+    }
+
+    composeOptions {
+        kotlinCompilerExtensionVersion = "1.5.14"
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+dependencies {
+    implementation(platform("androidx.compose:compose-bom:2024.09.02"))
+    implementation("androidx.activity:activity-compose:1.9.2")
+    implementation("androidx.compose.material3:material3")
+    implementation("androidx.compose.ui:ui")
+    implementation("androidx.compose.ui:ui-tooling-preview")
+}

apps/android-demo/app/src/main/AndroidManifest.xml

@@ -0,0 +1,16 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application
+        android:allowBackup="true"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.Material3.DayNight.NoActionBar">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>

apps/android-demo/app/src/main/assets/expedition-runtime-session.json

@@ -0,0 +1,9 @@
+{
+  "demo_id": "expedition.plan.v1",
+  "title": "Plan Expedition",
+  "request_id": "req-expedition-001",
+  "execution_id": "exec_req-expedition-001",
+  "trace_id": "trace_exec_req-expedition-001",
+  "status": "completed",
+  "summary": "Traverse evaluates the governed expedition workflow and assembles a final expedition plan."
+}

apps/android-demo/app/src/main/java/com/traverse/demo/android/MainActivity.kt

@@ -0,0 +1,99 @@
+package com.traverse.demo.android
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            MaterialTheme {
+                TraverseAndroidDemoScreen(sampleStateUpdates)
+            }
+        }
+    }
+}
+
+private val sampleStateUpdates = listOf(
+    DemoStateUpdate(
+        "Discovering capability",
+        "Looking up expedition.planning.plan-expedition@1.0.0 in the registry."
+    ),
+    DemoStateUpdate(
+        "Evaluating constraints",
+        "Confirming the approved expedition capability can run locally."
+    ),
+    DemoStateUpdate(
+        "Executing workflow",
+        "Traversing the approved expedition planning workflow."
+    ),
+    DemoStateUpdate(
+        "Completed",
+        "The expedition plan is ready for final review."
+    )
+)
+
+data class DemoStateUpdate(
+    val title: String,
+    val detail: String,
+)
+
+@Composable
+private fun TraverseAndroidDemoScreen(stateUpdates: List<DemoStateUpdate>) {
+    Scaffold { padding ->
+        LazyColumn(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(padding),
+            contentPadding = PaddingValues(16.dp),
+            verticalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+            item {
+                Card(modifier = Modifier.fillMaxWidth()) {
+                    Column(modifier = Modifier.padding(16.dp)) {
+                        Text("Traverse Android Demo", style = MaterialTheme.typography.headlineSmall)
+                        Text(
+                            "Plan Expedition",
+                            style = MaterialTheme.typography.titleMedium,
+                            modifier = Modifier.padding(top = 8.dp)
+                        )
+                        Text(
+                            "Runtime states and final trace summary render from the approved expedition demo fixture.",
+                            style = MaterialTheme.typography.bodyMedium,
+                            modifier = Modifier.padding(top = 8.dp)
+                        )
+                    }
+                }
+            }
+
+            items(stateUpdates) { update ->
+                Card(modifier = Modifier.fillMaxWidth()) {
+                    Column(modifier = Modifier.padding(16.dp)) {
+                        Text(update.title, style = MaterialTheme.typography.titleMedium)
+                        Text(
+                            update.detail,
+                            style = MaterialTheme.typography.bodyMedium,
+                            modifier = Modifier.padding(top = 6.dp)
+                        )
+                    }
+                }
+            }
+        }
+    }
+}

apps/android-demo/app/src/main/res/values/strings.xml

@@ -0,0 +1,3 @@
+<resources>
+    <string name="app_name">Traverse Android Demo</string>
+</resources>

apps/android-demo/build.gradle.kts

@@ -0,0 +1,4 @@
+plugins {
+    id("com.android.application") version "8.5.2" apply false
+    id("org.jetbrains.kotlin.android") version "1.9.24" apply false
+}

apps/android-demo/gradle.properties

@@ -0,0 +1,3 @@
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=true
+kotlin.code.style=official

apps/android-demo/settings.gradle.kts

@@ -0,0 +1,2 @@
+rootProject.name = "TraverseAndroidDemo"
+include(":app")

apps/browser-consumer/README.md

@@ -0,0 +1,24 @@
+# Traverse Browser Consumer Package
+
+Browser-targeted consumer façade for downstream apps such as `youaskm3`.
+
+Canonical home: **`traverse-framework/reference-apps`** (`apps/browser-consumer/`).
+
+It reuses the approved live browser adapter client from [`apps/react-demo/`](../react-demo/) and exposes a browser-safe subscription flow. Runtime ordering, trace visibility, and terminal outcomes come from Traverse public surfaces — not private app logic.
+
+## Quick Start
+
+```bash
+node -e "const client = require('./apps/browser-consumer'); console.log(client.APPROVED_BROWSER_CONSUMER_SESSION.title)"
+```
+
+## Validation
+
+Offline façade load is covered by `bash scripts/ci/youaskm3_starter_kit_smoke.sh`.
+
+Live adapter path (requires `TRAVERSE_REPO`):
+
+```bash
+export TRAVERSE_REPO=/path/to/Traverse
+bash scripts/ci/browser_consumer_package_smoke.sh
+```

apps/browser-consumer/index.js

@@ -0,0 +1,67 @@
+(function (root, factory) {
+  const client = factory();
+
+  if (typeof module === "object" && module.exports) {
+    module.exports = client;
+  }
+
+  if (root) {
+    root.TraverseBrowserConsumer = client;
+  }
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  let baseClient = null;
+
+  if (typeof require === "function") {
+    try {
+      baseClient = require("../react-demo/src/browser-adapter-client.js");
+    } catch {
+      baseClient = null;
+    }
+  }
+
+  if (!baseClient && typeof globalThis !== "undefined" && globalThis.TraverseReactDemoClient) {
+    baseClient = globalThis.TraverseReactDemoClient;
+  }
+
+  if (!baseClient) {
+    throw new Error(
+      "Traverse browser consumer requires the approved browser adapter client to be available.",
+    );
+  }
+
+  const APPROVED_BROWSER_CONSUMER_SESSION = {
+    ...baseClient.APPROVED_BROWSER_DEMO_SESSION,
+    title: "Traverse Browser Consumer",
+    summary:
+      "Traverse's browser-targeted consumer facade for downstream browser-hosted apps like youaskm3.",
+  };
+
+  function createBrowserConsumerState() {
+    return baseClient.createLiveDemoState();
+  }
+
+  function buildBrowserConsumerSubscriptionRequest() {
+    return baseClient.buildApprovedSubscriptionRequest();
+  }
+
+  function runBrowserConsumerSubscription(options = {}) {
+    return baseClient.runLiveBrowserSubscription(options);
+  }
+
+  function applyBrowserConsumerMessage(state, message, created) {
+    return baseClient.applyBrowserSubscriptionMessage(state, message, created);
+  }
+
+  function browserConsumerTraceSummary(trace, terminalResult) {
+    return baseClient.traceSummary(trace, terminalResult);
+  }
+
+  return {
+    APPROVED_BROWSER_CONSUMER_SESSION,
+    applyBrowserConsumerMessage,
+    browserConsumerTraceSummary,
+    buildBrowserConsumerSubscriptionRequest,
+    createBrowserConsumerState,
+    runBrowserConsumerSubscription,
+  };
+});

apps/browser-consumer/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "traverse-browser-consumer",
+  "version": "0.1.0",
+  "private": true,
+  "main": "index.js",
+  "description": "Traverse browser-targeted consumer facade for downstream browser-hosted apps."
+}

apps/macos-demo/Package.swift

@@ -0,0 +1,18 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+    name: "TraverseMacOSDemo",
+    platforms: [
+        .macOS(.v14),
+    ],
+    products: [
+        .executable(name: "TraverseMacOSDemoApp", targets: ["TraverseMacOSDemoApp"]),
+    ],
+    targets: [
+        .executableTarget(
+            name: "TraverseMacOSDemoApp",
+            path: "Sources/TraverseMacOSDemoApp"
+        ),
+    ]
+)