@@ -0,0 +1,92 @@
+name: build-java
+
+# CI for the JavaFX desktop app (app/) + headless compute engine (engine/).
+#
+# The app is now Python-first: the Java bridge spawns the Python (FlowKit) engine
+# by default, with the legacy R engine kept as a fallback until it is retired. This
+# job therefore stands up BOTH engines so the test suite exercises the real data
+# path on each:
+#   * Python  — a venv at engine/py-env with FlowKit installed. PyEngineTest and the
+#               command tests auto-detect this exact path and run against it.
+#   * R       — R 4.4 + jsonlite so the JavaFX<->R ProtocolConformanceTest runs for
+#               real (it auto-skips if R is missing).
+#
+# Tests that need large FCS fixtures (test-assests/, gitignored) self-skip in CI via
+# JUnit assumptions — that is expected. The heavy Bioconductor/CytoExploreR stack is
+# NOT installed here; module integration tests get their own gated job later.
+#
+# This job does NOT produce the packaged StreamFLOW.exe — jpackage packaging
+# (app/package.ps1) is a separate release pipeline and is still being aligned with
+# the Python engine.
+
+on:
+  push:
+    paths:
+      - 'app/**'
+      - 'engine/**'
+      - '.github/workflows/build-java.yml'
+  pull_request:
+    paths:
+      - 'app/**'
+      - 'engine/**'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 25 (Microsoft, LTS)
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'microsoft'
+          java-version: '25'
+          cache: maven
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: pip
+
+      - name: Create engine venv + install FlowKit
+        shell: pwsh
+        run: |
+          # PyEngineTest / command tests expect the venv at engine\py-env (the same
+          # path run-dev.ps1 uses), so create it there exactly.
+          python -m venv engine\py-env
+          engine\py-env\Scripts\python.exe -m pip install --upgrade pip
+          # flowkit pulls flowio, flowutils, numpy, scipy, pandas; matplotlib is used
+          # by the render/stats commands; scikit-learn/umap-learn/openTSNE power the
+          # Dim. Reduction, Clustering and Classifier modules.
+          engine\py-env\Scripts\python.exe -m pip install flowkit matplotlib scikit-learn umap-learn openTSNE phenograph flowsom
+          engine\py-env\Scripts\python.exe -c "import flowkit; print('FlowKit', flowkit.__version__)"
+
+      - name: Set up R 4.4 (legacy engine fallback)
+        uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: '4.4'
+
+      - name: Install jsonlite
+        run: Rscript -e "install.packages('jsonlite', repos='https://cloud.r-project.org')"
+        shell: cmd
+
+      - name: Build and test (Python + R engine bridges)
+        working-directory: app
+        shell: cmd
+        run: >
+          mvn -B clean test
+          "-Dstreamflow.rscript=%RSCRIPT_PATH%"
+        env:
+          # r-lib/actions exposes R on PATH; resolve Rscript explicitly for the bridge.
+          # The Python tests self-configure via the engine\py-env path created above.
+          RSCRIPT_PATH: Rscript
+
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: surefire-reports
+          path: app/target/surefire-reports/
@@ -1,6 +1,7 @@
 # ── Internal / dev-only docs (kept locally, not for the public repo) ──────────
 AUDIT_REPORT.md
 BUILDING.md
+MANUAL_TESTING.md
 
 # ── Build outputs & dependencies ─────────────────────────────────────────────
 node_modules/
@@ -15,10 +16,45 @@ yarn-error.log
 # ── Bundled R runtime (≈1 GB, produced by the build, never committed) ─────────
 R-Portable/
 
+# ── Vendored dev tooling (large binaries kept locally, never committed) ───────
+# JDKs and Maven are set up by CI / the dev scripts, not stored in git.
+jdk-25.0.3+9/
+jdk-26.0.1/
+apache-maven-3.9.16/
+# Ikonli is consumed as a Maven dependency, not from its source tree.
+ikonli-master/
+# Vendored R package sources — cloned/extracted locally, installed into the R
+# library at build time, never committed (hundreds of MB of external source).
+engine/vendor/
+# Vendored Python package sources / wheels for the Python migration (large).
+python-migration/
+engine/py-vendor/
+# Python virtual environment for the engine (~500 MB, recreated by install scripts).
+engine/py-env/
+.venv/
+venv/
+env/
+
+# ── Python bytecode / caches ─────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+# claude-code-java toolkit (review skills/templates), not part of the app build.
+claude-code-java-main/
+
+# ── Java / Maven build output ────────────────────────────────────────────────
+target/
+*.class
+
 # ── Logs ─────────────────────────────────────────────────────────────────────
 *.log
 logs/
 install_log.txt
+# Captured stdout/stderr from install/build runs (engine_install.out, py_install.out, …)
+*.out
 
 # ── R session artifacts (RStudio / Rscript leave these behind) ───────────────
 .Rhistory
@@ -40,9 +76,19 @@ install_log.txt
 # Office / OneDrive lock files (this repo lives under OneDrive\Documents)
 ~$*
 
+# ── Large / private test data (FCS files, fixtures — never for the public repo) ─
+test-assests/
+test-assets/
+test-data/
+*.fcs
+
+# ── Local Claude Code config (personal permissions + machine-specific paths) ──
+.claude/
+
 # ── OS / editor cruft ────────────────────────────────────────────────────────
 Thumbs.db
 desktop.ini
 .DS_Store
 .vscode/
 .idea/
+*.iml
@@ -0,0 +1,4 @@
+target/
+*.class
+.idea/
+*.iml
@@ -0,0 +1,93 @@
+# StreamFLOW — Java desktop UI (Phase 0)
+
+Native JavaFX desktop front-end for the StreamFLOW flow-cytometry suite. The
+heavy compute stays in R (Bioconductor / CytoExploreR) running as a background
+process; Java owns the window, file dialogs, and async orchestration. See
+`../engine/streamflow_engine.R` for the R side and the project plan for the full
+architecture.
+
+This is **Phase 0**: the JavaFX ⇄ R bridge, the async job model, the app shell,
+and a developer console that proves the architecture end-to-end. The real
+analysis modules land in later phases.
+
+## Prerequisites
+
+The repo is **self-contained for building** — no system JDK or Maven needed:
+
+- **JDK**: bundled **Microsoft Build of OpenJDK 25 (LTS)** at `../jdk-25.0.3+9`.
+- **Maven**: bundled **Apache Maven 3.9.16** at `../apache-maven-3.9.16`.
+- The `build.ps1` / `run-dev.ps1` scripts pin `JAVA_HOME`, use the bundled Maven,
+  and set `MAVEN_OPTS` to trust the **Windows certificate store** (so Maven Central
+  works behind a TLS-intercepting proxy/AV — otherwise you'd get a PKIX
+  "unable to find valid certification path" error).
+- **R** is the only external requirement: `jsonlite` for Phase 0, and from Phase 1
+  on the full Bioconductor/CytoExploreR stack. In a packaged build this is the
+  bundled `R-Portable`; in dev, point the scripts at any Rscript with `-Rscript`.
+
+> The repo lives in a OneDrive-synced folder, which can transiently lock
+> `target/`; if `mvn clean` fails to delete it, just `rm -rf target` and retry.
+
+## Run the app (dev)
+
+```powershell
+# from app\
+./run-dev.ps1                                   # Rscript from PATH / bundled R-Portable
+./run-dev.ps1 -Rscript "C:\Program Files\R\R-4.4.2\bin\Rscript.exe"
+```
+
+Then in the **Developer / Engine Console**:
+- **Ping / R Version** — basic round-trip over the stdio JSON protocol.
+- **Sleep (5s, cancellable)** — start it, then click the nav items and drag the
+  window: the UI stays fully responsive while R works (the freeze fix). Hit
+  **Cancel** to prove cooperative cancellation.
+- **Trigger Error** — shows the real R error message surfaced to the UI.
+- **Noisy stdout** — R does `cat()`/`print()`; the JSON stream stays intact
+  (proves the `sink(stderr())` guard).
+
+## Verify (Phase 0 gate)
+
+```powershell
+# from app\  — runs the protocol conformance test against a real R engine
+./build.ps1 -Rscript "C:\Program Files\R\R-4.4.2\bin\Rscript.exe"
+```
+
+`ProtocolConformanceTest` asserts: ready handshake, echo/version round-trip,
+progress frames, cooperative cancel, error+traceback replies, malformed-request
+resilience, and that stray R stdout never corrupts the stream. (The test is
+skipped automatically if no Rscript is available.)
+
+Orphan-safety check (manual): launch the app, find the child `Rscript.exe` in
+Task Manager, kill the `java`/JavaFX process — the engine should exit on its own
+within seconds (stdin EOF), leaving no lingering R process.
+
+## Build a Windows app (jpackage)
+
+Produces a self-contained app-image (StreamFLOW.exe + bundled JRE + R), so end
+users need neither Java nor R:
+
+```powershell
+# 1) one-time / when R deps change — stage a minimal portable R (slow, ~1 GB):
+powershell -ExecutionPolicy Bypass -File engine\stage-r-portable.ps1
+# 2) build the app image (or add -Installer for an .exe, needs WiX):
+powershell -ExecutionPolicy Bypass -File app\package.ps1
+# output: app\target\dist\StreamFLOW\
+```
+
+The app resolves the bundled engine + R-Portable via `-Dstreamflow.appDir`
+(set by `package.ps1`). *Status: scripts are ready; the first packaged build still
+needs a validation run (jpackage classpath + runtime path).*
+
+## Layout
+
+```
+app/
+  pom.xml                         Maven build (OpenJFX, controlsfx, Jackson, JUnit)
+  run-dev.ps1 / build.ps1         JDK-pinned launchers
+  src/main/java/org/streamflow/
+    StreamFlowApp.java            JavaFX entry point
+    bridge/                       R process + stdio JSON protocol + async jobs
+    ui/MainController.java         shell controller (Phase 0 dev console)
+  src/main/resources/org/streamflow/ui/
+    main.fxml, streamflow-dark.css
+  src/test/java/.../ProtocolConformanceTest.java
+```
@@ -0,0 +1,44 @@
+# StreamFLOW (Java) — build & test
+# Pins JAVA_HOME to the bundled Microsoft JDK 25 (LTS), then compiles and runs
+# the protocol conformance test (Phase 0 verification gate).
+#
+# Usage:
+#   ./build.ps1                          # compile + test (test skips if R absent)
+#   ./build.ps1 -Rscript "C:\R\bin\Rscript.exe"   # run the conformance test against R
+#   ./build.ps1 -SkipTests
+#
+param(
+    [string]$Rscript = "",
+    [switch]$SkipTests
+)
+
+$ErrorActionPreference = "Stop"
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repo = Split-Path -Parent $here
+
+$jdk = Join-Path $repo "jdk-25.0.3+9"
+if (-not (Test-Path (Join-Path $jdk "bin\java.exe"))) {
+    throw "Microsoft JDK 25 not found at $jdk"
+}
+$env:JAVA_HOME = $jdk
+$env:PATH = "$jdk\bin;$env:PATH"
+Write-Host "JAVA_HOME = $env:JAVA_HOME"
+
+# Trust the Windows certificate store so Maven Central works behind a
+# TLS-intercepting proxy/AV (otherwise: PKIX 'unable to find valid cert path').
+$env:MAVEN_OPTS = "-Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL"
+
+# Prefer the bundled Maven; fall back to one on PATH.
+$mvn = Join-Path $repo "apache-maven-3.9.16\bin\mvn.cmd"
+if (-not (Test-Path $mvn)) {
+    if (Get-Command mvn -ErrorAction SilentlyContinue) { $mvn = "mvn" }
+    else { throw "Maven not found (looked for $mvn and PATH)." }
+}
+
+$goal = if ($SkipTests) { "compile" } else { "test" }
+$mvnArgs = @("-B", "-f", (Join-Path $here "pom.xml"), "clean", $goal)
+if ($Rscript -ne "") {
+    $mvnArgs += "-Dstreamflow.rscript=$Rscript"
+}
+Write-Host "Running: $mvn $($mvnArgs -join ' ')"
+& $mvn @mvnArgs
@@ -0,0 +1,70 @@
+# StreamFLOW — build a self-contained Windows app via jpackage.
+#
+# Produces an app-image (folder with StreamFLOW.exe + bundled JRE) that includes
+# the JavaFX app, BOTH engines' scripts, and two staged runtimes — a portable
+# Python (FlowKit, the default engine) and a portable R (for R-based plugins) — so
+# the end user needs no Java, Python, or R installed ("fat binary", ~1.5 GB).
+#
+#   1) when Python deps change:  powershell -File engine\stage-python.ps1
+#   2) when R deps change:       powershell -File engine\stage-r-portable.ps1
+#   3) build the app:            powershell -File app\package.ps1
+#       [-Installer]   also build an .exe/.msi installer (needs WiX on PATH)
+#
+# NOTE: first run needs validation (jpackage classpath + runtime path resolution).
+param([switch]$Installer)
+
+$ErrorActionPreference = "Stop"
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path     # app\
+$repo = Split-Path -Parent $here
+$jdk  = Join-Path $repo "jdk-25.0.3+9"
+$mvn  = Join-Path $repo "apache-maven-3.9.16\bin\mvn.cmd"
+$env:JAVA_HOME = $jdk
+$env:PATH = "$jdk\bin;$env:PATH"
+$env:MAVEN_OPTS = "-Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL"
+
+$rportable = Join-Path $here "target\R-Portable"
+if (-not (Test-Path (Join-Path $rportable "bin\Rscript.exe"))) {
+    throw "R-Portable not staged. Run: powershell -File engine\stage-r-portable.ps1"
+}
+
+$pyportable = Join-Path $here "target\python"
+if (-not (Test-Path (Join-Path $pyportable "python.exe"))) {
+    throw "Portable Python not staged. Run: powershell -File engine\stage-python.ps1"
+}
+
+# 1) Build the jar + collect runtime dependencies into target\libs.
+Write-Host "Building jar + collecting dependencies…"
+& $mvn -B -f (Join-Path $here "pom.xml") clean package `
+    dependency:copy-dependencies "-DoutputDirectory=target/libs" "-DincludeScope=runtime" "-DskipTests=true"
+Copy-Item (Join-Path $here "target\streamflow-2.0.0.jar") (Join-Path $here "target\libs\") -Force
+
+# 2) Stage app content (engine scripts + portable Python + R-Portable) next to the launcher.
+#    Excludes engine/vendor (R package SOURCE — only needed at R-Portable stage time)
+#    and engine/py-env (the dev venv — the relocatable target\python is bundled instead).
+$content = Join-Path $here "target\content"
+if (Test-Path $content) { Remove-Item -Recurse -Force $content }
+New-Item -ItemType Directory -Force -Path $content | Out-Null
+robocopy (Join-Path $repo "engine") (Join-Path $content "engine") /E /XD "vendor" "py-env" "__pycache__" /NFL /NDL /NJH /NJS | Out-Null
+robocopy $pyportable (Join-Path $content "python") /E /NFL /NDL /NJH /NJS | Out-Null
+robocopy $rportable (Join-Path $content "R-Portable") /E /NFL /NDL /NJH /NJS | Out-Null
+
+# 3) jpackage app-image (JavaFX runs from the classpath; the openjfx win jars carry natives).
+$dist = Join-Path $here "target\dist"
+if (Test-Path $dist) { Remove-Item -Recurse -Force $dist }
+$type = if ($Installer) { "exe" } else { "app-image" }
+Write-Host "Running jpackage ($type)…"
+& (Join-Path $jdk "bin\jpackage.exe") `
+    --type $type `
+    --name "StreamFLOW" `
+    --app-version "2.0.0" `
+    --input (Join-Path $here "target\libs") `
+    --main-jar "streamflow-2.0.0.jar" `
+    --main-class "org.streamflow.StreamFlowApp" `
+    --app-content $content `
+    --icon (Join-Path $repo "build\icon.ico") `
+    --dest $dist `
+    --java-options "-Dstreamflow.appDir=`$APPDIR\..\content" `
+    --java-options "-Dstreamflow.engine.kind=python" `
+    --vendor "StreamFLOW"
+
+Write-Host "Built -> $dist"
-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +target/
 +*.class
 +.idea/
 +*.iml