link1345 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026
diff --git a/.github/workflows/gua-tests.yml b/.github/workflows/gua-tests.yml
@@ -20,7 +20,7 @@ jobs:
     if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     permissions:
       contents: read
-    uses: link1345/gua-tester/.github/workflows/unity.yml@v2
+    uses: link1345/gua-tester/.github/workflows/unity.yml@v2.1
     with:
       project-path: .
       scene-path: Assets/Scenes/Main.unity
@@ -137,34 +137,35 @@ jobs:
         env:
           UNITY_OUTCOME: ${{ needs.unity-tests.result }}
           DEMO_OUTCOME: ${{ needs.visual-report-demo.result }}
-          VISUAL_REPORT_DEMO: ${{ inputs.visual-report-demo }}
         run: |
           $outcome = if ($env:UNITY_OUTCOME -in @("success", "failure", "cancelled")) {
             $env:UNITY_OUTCOME
           } else {
             "failure"
           }
-          if ($env:DEMO_OUTCOME -eq "failure" -or $env:VISUAL_REPORT_DEMO -eq "true") {
+          if ($env:DEMO_OUTCOME -eq "failure") {
             $outcome = "failure"
           }
           "value=$outcome" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
 
       - name: Upload pull-request visual report
         if: github.event_name == 'pull_request' && steps.visual-outcome.outputs.value == 'failure'
-        uses: link1345/gua-tester/visual-report@v2
+        uses: link1345/gua-tester/visual-report@v2.1
         with:
           artifact-path: downloaded
           test-outcome: ${{ steps.visual-outcome.outputs.value }}
+          include-comparisons-on-success: false
           upload-target: workflow
           workflow-artifact-name: gua-visual-report
 
       - name: Prepare latest main visual report
         id: pages-report
         if: always() && (github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch')
-        uses: link1345/gua-tester/visual-report@v2
+        uses: link1345/gua-tester/visual-report@v2.1
         with:
           artifact-path: downloaded
           test-outcome: ${{ steps.visual-outcome.outputs.value }}
+          include-comparisons-on-success: ${{ inputs.visual-report-demo || false }}
           upload-target: pages
 
   deploy-visual-report:

diff --git a/README-ja.md b/README-ja.md
@@ -0,0 +1,85 @@
+# Gua UI Lab for Unity
+
+日本語 | [English](README.md)
+
+これは [Gua](https://github.com/link1345/gua) のUnity版サンプルプロジェクトです。
+[`gua-sample-godot`](https://github.com/link1345/gua-sample-godot) と同じ画像素材、画面構成、操作フローをUnity 6のuGUIで再現しています。
+
+`Start`で2画面目へ移動し、6秒間の`Loading....`表示中は`Back`が無効になります。Loading終了後は`Back`で1画面目へ戻れます。`End`では終了確認が表示され、`Cancel`で戻り、`OK`で終了します。
+
+ウィンドウはリサイズ可能です。541×857のデザイン比率を維持して一様に拡大・縮小し、画面比率から余る領域は黒いレターボックスとして表示します。
+
+UI自動化にはGua v0.15.0のUnity UPMパッケージを使用しています。実行中は既定で `ws://127.0.0.1:8765` にGua bridgeを開き、標準uGUIツリーを自動的に公開します。ポートは環境変数 `GUA_BRIDGE_PORT` で変更できます。
+
+## 実行
+
+1. Unity Hubでこのディレクトリを開きます。
+2. Unity `6000.5.3f1`で `Assets/Scenes/Main.unity` を開きます。
+3. Playを押します。
+
+Guaの管理DLLとWindows x64ネイティブDLLを含む公式UPMパッケージ v0.15.0は `Packages/com.link1345.gua` に固定しています。そのため、隣接するGuaソースリポジトリへの参照や別途のパッケージダウンロードは不要です。
+
+## UIテスト
+
+Windows x64 Mono Playerをビルドしてから、NUnitで実際のPlayerとSemantic UI Treeを操作します。
+
+```powershell
+& "C:\Program Files\Unity\Hub\Editor\6000.5.3f1\Editor\Unity.exe" `
+  -batchmode -quit -projectPath $PWD `
+  -buildWindows64Player "$PWD\Builds\GuaUiLab.exe" `
+  -logFile "$PWD\unity-build.log"
+dotnet test tests\GuaUiLab.Unity.Tests.csproj
+```
+
+Playerを別の場所へ出力した場合は、`GUA_UNITY_PLAYER`にexeの絶対パスを指定します。失敗時のGua UI Tree、ログ、Unity Playerログ、スクリーンショットなどは `artifacts/gua` に保存されます。
+
+### Visual / Recording検証
+
+`Gua.Testing.Visual`で初期画面をレビュー済みPNGと比較し、画像欠落、配置ずれ、意図しないオーバーレイを検出します。基準画像を意図的に更新する場合だけ、差分を確認した上で次を実行します。
+
+```powershell
+$env:GUA_UPDATE_BASELINES = "1"
+dotnet test tests\GuaUiLab.Unity.Tests.csproj --filter TitleScreenMatchesReviewedVisualBaseline
+Remove-Item Env:GUA_UPDATE_BASELINES
+```
+
+`Gua.Testing.Recording`では`End` → `Cancel`のセマンティック操作を実際に記録し、JSONへの保存・再読込・同一Unity Playerセッションへの再生まで検証します。成功時の記録JSONはテスト出力ディレクトリの`artifacts/gua/recordings`に保存されます。
+
+Visual Report用の差分成果物をローカル生成する場合は、次を実行します。
+
+```powershell
+$env:GUA_VISUAL_REPORT_DEMO = "1"
+dotnet test tests\GuaUiLab.Unity.Tests.csproj --filter VisualReportViewerDemoProducesPixelDifferenceArtifact
+Remove-Item Env:GUA_VISUAL_REPORT_DEMO
+```
+
+## GitHub Actions
+
+`.github/workflows/gua-tests.yml`で[`link1345/gua-tester`](https://github.com/link1345/gua-tester) v2.1を使用し、`main`へのpushとpull requestでUnity 6のWindows x64 Mono PlayerをビルドしてUIテストを実行します。Unity Playerのビルドにはrepository secretsの`UNITY_EMAIL`、`UNITY_PASSWORD`と、Personal用の`UNITY_LICENSE`またはProfessional用の`UNITY_SERIAL`が必要です。
+
+forkからのpull requestではUnity credentialsを渡さず、Unity jobをスキップします。`pull_request_target`は使用しません。
+
+### Visual差分Viewer
+
+pull requestでVisual比較が失敗すると、`visual-report@v2.1`が`comparison.json`とPNGを静的Viewerへ変換し、`gua-visual-report`というActions artifactとして保存します。通常のUnity build log、Player、TRX、Gua診断・Visual成果物も`gua-tester` v2.1のworkflow artifactとして保存されます。
+
+`main`へのpushと手動実行では、最新結果をGitHub Pages artifactとしてアップロードし、専用jobからPagesへdeployします。repositoryのPages sourceを事前に **GitHub Actions** へ設定してください。
+
+手動実行で`visual-report-demo`を有効にすると、通常テストでビルド済みのUnity Playerを再利用し、`VisualReportViewerDemoProducesPixelDifferenceArtifact`でtitle画面とloading画面の意図的なpixel差分を生成します。テスト自体は期待した比較失敗を検証して成功し、ViewerにはExpected／Diff／Actualが表示されます。
+
+> [!WARNING]
+> screenshotにはゲーム画面へ描画された秘密情報や個人情報が含まれる可能性があります。特にpublic repositoryでPagesを有効にする前に、公開内容を確認してください。
+
+## Guaで公開する主要ノード
+
+| ID | 役割 | 画面 |
+| --- | --- | --- |
+| `start` | button | 1画面目 |
+| `end` | button | 1画面目 |
+| `loading` | text | 2画面目（Loading中のみ） |
+| `back` | button | 2画面目 |
+| `exit_question` | text | 終了確認 |
+| `cancel_exit` | button | 終了確認 |
+| `confirm_exit` | button | 終了確認 |
+
+Gua v0.15.0が最初に対応するUnity構成に合わせ、Windows x64・Monoを対象にしています。IL2CPPとWindows以外のPlayerはこのサンプルの検証対象外です。
diff --git a/README.md b/README.md
@@ -1,25 +1,26 @@
 # Gua UI Lab for Unity
 
-これは [Gua](https://github.com/link1345/gua) のUnity版サンプルプロジェクトです。
-[`gua-sample-godot`](https://github.com/link1345/gua-sample-godot) と同じ画像素材、画面構成、操作フローをUnity 6のuGUIで再現しています。
+English | [日本語](README-ja.md)
 
-`Start`で2画面目へ移動し、6秒間の`Loading....`表示中は`Back`が無効になります。Loading終了後は`Back`で1画面目へ戻れます。`End`では終了確認が表示され、`Cancel`で戻り、`OK`で終了します。
+This is a Unity sample project for [Gua](https://github.com/link1345/gua). It recreates the same visual assets, screen layout, and interaction flow as [`gua-sample-godot`](https://github.com/link1345/gua-sample-godot) using Unity 6 and uGUI.
 
-ウィンドウはリサイズ可能です。541×857のデザイン比率を維持して一様に拡大・縮小し、画面比率から余る領域は黒いレターボックスとして表示します。
+`Start` opens the second screen, where `Back` remains disabled during a six-second `Loading....` state. After loading finishes, `Back` returns to the first screen. `End` opens an exit confirmation dialog; `Cancel` closes it, and `OK` exits the application.
 
-UI自動化にはGua v0.15.0のUnity UPMパッケージを使用しています。実行中は既定で `ws://127.0.0.1:8765` にGua bridgeを開き、標準uGUIツリーを自動的に公開します。ポートは環境変数 `GUA_BRIDGE_PORT` で変更できます。
+The window is resizable. The UI scales uniformly while preserving its 541×857 design aspect ratio, and any space outside that ratio is rendered as black letterboxing.
 
-## 実行
+UI automation uses the Gua v0.15.0 Unity UPM package. At runtime, it opens a Gua bridge at `ws://127.0.0.1:8765` by default and automatically exposes the standard uGUI tree. Set the `GUA_BRIDGE_PORT` environment variable to use a different port.
 
-1. Unity Hubでこのディレクトリを開きます。
-2. Unity `6000.5.3f1`で `Assets/Scenes/Main.unity` を開きます。
-3. Playを押します。
+## Run the sample
 
-Guaの管理DLLとWindows x64ネイティブDLLを含む公式UPMパッケージ v0.15.0は `Packages/com.link1345.gua` に固定しています。そのため、隣接するGuaソースリポジトリへの参照や別途のパッケージダウンロードは不要です。
+1. Open this directory in Unity Hub.
+2. Open `Assets/Scenes/Main.unity` with Unity `6000.5.3f1`.
+3. Enter Play Mode.
 
-## UIテスト
+The official UPM package v0.15.0, including the managed assemblies and Windows x64 native libraries, is pinned in `Packages/com.link1345.gua`. No adjacent Gua source repository or separate package download is required.
 
-Windows x64 Mono Playerをビルドしてから、NUnitで実際のPlayerとSemantic UI Treeを操作します。
+## UI tests
+
+Build a Windows x64 Mono Player, then use NUnit to operate the real Player through its Semantic UI Tree.
 
 ```powershell
 & "C:\Program Files\Unity\Hub\Editor\6000.5.3f1\Editor\Unity.exe" `
@@ -29,21 +30,21 @@ Windows x64 Mono Playerをビルドしてから、NUnitで実際のPlayerとSema
 dotnet test tests\GuaUiLab.Unity.Tests.csproj
 ```
 
-Playerを別の場所へ出力した場合は、`GUA_UNITY_PLAYER`にexeの絶対パスを指定します。失敗時のGua UI Tree、ログ、Unity Playerログ、スクリーンショットなどは `artifacts/gua` に保存されます。
+If the Player was built elsewhere, set `GUA_UNITY_PLAYER` to the absolute path of its executable. On failure, the Gua UI Tree, logs, Unity Player log, screenshots, and other diagnostics are saved under `artifacts/gua`.
 
-### Visual / Recording検証
+### Visual and recording validation
 
-`Gua.Testing.Visual`で初期画面をレビュー済みPNGと比較し、画像欠落、配置ずれ、意図しないオーバーレイを検出します。基準画像を意図的に更新する場合だけ、差分を確認した上で次を実行します。
+`Gua.Testing.Visual` compares the initial screen with a reviewed PNG baseline to detect missing images, layout shifts, and unintended overlays. Only update the baseline intentionally after reviewing the difference:
 
 ```powershell
 $env:GUA_UPDATE_BASELINES = "1"
 dotnet test tests\GuaUiLab.Unity.Tests.csproj --filter TitleScreenMatchesReviewedVisualBaseline
 Remove-Item Env:GUA_UPDATE_BASELINES
 ```
 
-`Gua.Testing.Recording`では`End` → `Cancel`のセマンティック操作を実際に記録し、JSONへの保存・再読込・同一Unity Playerセッションへの再生まで検証します。成功時の記録JSONはテスト出力ディレクトリの`artifacts/gua/recordings`に保存されます。
+`Gua.Testing.Recording` records real semantic interactions for `End` → `Cancel`, saves them to JSON, reloads them, and replays them in the same Unity Player session. Successful recording files are saved under `artifacts/gua/recordings` in the test output directory.
 
-Visual Report用の差分成果物をローカル生成する場合は、次を実行します。
+To generate a local pixel-difference artifact for the Visual Report, run:
 
 ```powershell
 $env:GUA_VISUAL_REPORT_DEMO = "1"
@@ -53,31 +54,31 @@ Remove-Item Env:GUA_VISUAL_REPORT_DEMO
 
 ## GitHub Actions
 
-`.github/workflows/gua-tests.yml`で[`link1345/gua-tester`](https://github.com/link1345/gua-tester) v2を使用し、`main`へのpushとpull requestでUnity 6のWindows x64 Mono PlayerをビルドしてUIテストを実行します。Unity Playerのビルドにはrepository secretsの`UNITY_EMAIL`、`UNITY_PASSWORD`と、Personal用の`UNITY_LICENSE`またはProfessional用の`UNITY_SERIAL`が必要です。
+`.github/workflows/gua-tests.yml` uses [`link1345/gua-tester`](https://github.com/link1345/gua-tester) v2.1 to build a Unity 6 Windows x64 Mono Player and run UI tests on pushes to `main` and on pull requests. Building the Unity Player requires the repository secrets `UNITY_EMAIL`, `UNITY_PASSWORD`, and either `UNITY_LICENSE` for a Personal license or `UNITY_SERIAL` for a Professional license.
 
-forkからのpull requestではUnity credentialsを渡さず、Unity jobをスキップします。`pull_request_target`は使用しません。
+Pull requests from forks do not receive Unity credentials, so the Unity job is skipped. The workflow does not use `pull_request_target`.
 
-### Visual差分Viewer
+### Visual difference viewer
 
-pull requestでVisual比較が失敗すると、`visual-report@v2`が`comparison.json`とPNGを静的Viewerへ変換し、`gua-visual-report`というActions artifactとして保存します。通常のUnity build log、Player、TRX、Gua診断・Visual成果物も`gua-tester` v2のworkflow artifactとして保存されます。
+When a visual comparison fails in a pull request, `visual-report@v2.1` turns `comparison.json` and its PNGs into a static viewer and stores it as the `gua-visual-report` Actions artifact. The normal Unity build log, Player, TRX file, and Gua diagnostic and visual artifacts are also stored in the `gua-tester` v2.1 workflow artifact.
 
-`main`へのpushと手動実行では、最新結果をGitHub Pages artifactとしてアップロードし、専用jobからPagesへdeployします。repositoryのPages sourceを事前に **GitHub Actions** へ設定してください。
+On pushes to `main` and manual runs, the latest report is uploaded as a GitHub Pages artifact and deployed by a dedicated job. Configure the repository's Pages source as **GitHub Actions** first.
 
-手動実行で`visual-report-demo`を有効にすると、通常テストでビルド済みのUnity Playerを再利用し、`VisualReportViewerDemoProducesPixelDifferenceArtifact`でtitle画面とloading画面の意図的なpixel差分を生成します。テスト自体は期待した比較失敗を検証して成功し、ViewerにはExpected／Diff／Actualが表示されます。
+Enable `visual-report-demo` in a manual run to reuse the Unity Player from the normal test build and have `VisualReportViewerDemoProducesPixelDifferenceArtifact` generate an intentional pixel difference between the title and loading screens. The test succeeds after verifying the expected comparison failure, while the viewer displays Expected, Diff, and Actual images.
 
 > [!WARNING]
-> screenshotにはゲーム画面へ描画された秘密情報や個人情報が含まれる可能性があります。特にpublic repositoryでPagesを有効にする前に、公開内容を確認してください。
+> Screenshots may contain secrets or personal information rendered inside the game. Review what will be published before enabling Pages, especially in a public repository.
 
-## Guaで公開する主要ノード
+## Main nodes exposed through Gua
 
-| ID | 役割 | 画面 |
+| ID | Role | Screen |
 | --- | --- | --- |
-| `start` | button | 1画面目 |
-| `end` | button | 1画面目 |
-| `loading` | text | 2画面目（Loading中のみ） |
-| `back` | button | 2画面目 |
-| `exit_question` | text | 終了確認 |
-| `cancel_exit` | button | 終了確認 |
-| `confirm_exit` | button | 終了確認 |
-
-Gua v0.15.0が最初に対応するUnity構成に合わせ、Windows x64・Monoを対象にしています。IL2CPPとWindows以外のPlayerはこのサンプルの検証対象外です。
+| `start` | button | First screen |
+| `end` | button | First screen |
+| `loading` | text | Second screen, while loading |
+| `back` | button | Second screen |
+| `exit_question` | text | Exit confirmation |
+| `cancel_exit` | button | Exit confirmation |
+| `confirm_exit` | button | Exit confirmation |
+
+This sample targets Windows x64 and Mono, matching the initial Unity support in Gua v0.15.0. IL2CPP and non-Windows Players are outside the sample's validated scope.
diff --git a/tests/AdvancedValidationTests.cs b/tests/AdvancedValidationTests.cs
@@ -16,6 +16,7 @@ public sealed class AdvancedValidationTests
         Environment.GetEnvironmentVariable("GUA_VISUAL_VARIANT")
         ?? "windows-unity-6000.5.3f1-d3d11-541x700";
     private static readonly TimeSpan ShortTimeout = TimeSpan.FromSeconds(5);
+    private static readonly TimeSpan RecordingActionTimeout = TimeSpan.FromSeconds(15);
     private static readonly TimeSpan PollInterval = TimeSpan.FromMilliseconds(20);
     private static readonly string ProjectRoot = FindProjectRoot();
 
@@ -141,12 +142,12 @@ public async Task RecordedEndCancelJourneyRoundTripsAndReplays()
         await recorder.ClickAsync(
             new(Id: "end"),
             waitCondition: GuaWaitConditions.Visible("end"),
-            timeout: ShortTimeout,
+            timeout: RecordingActionTimeout,
             pollInterval: PollInterval);
         await recorder.ClickAsync(
             new(Id: "cancel_exit"),
             waitCondition: GuaWaitConditions.Visible("cancel_exit"),
-            timeout: ShortTimeout,
+            timeout: RecordingActionTimeout,
             pollInterval: PollInterval);
         await GuaAssertions.WaitForVisibleAsync(
             host.Context,
@@ -170,7 +171,7 @@ await GuaAssertions.WaitForVisibleAsync(
             new GuaReplayOptions
             {
                 TimingMode = GuaReplayTimingMode.PreferConditions,
-                ActionTimeout = ShortTimeout,
+                ActionTimeout = RecordingActionTimeout,
                 PollInterval = PollInterval,
             });
 

diff --git a/tests/baselines/title-screen/windows-unity-6000.5.3f1-d3d11-541x700.png b/tests/baselines/title-screen/windows-unity-6000.5.3f1-d3d11-541x700.png