Stabilize active game lifecycle controls and dirty-state actions - PR_26130_034-active-game-lifecycle-controls

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,42 +1,71 @@
-# Codex Commands - PR_26126_037-preview-generator-v2-remove-shared-and-consolidate-common
+# Codex Commands - PR_26130_034-active-game-lifecycle-controls
 
-```bash
-codex run "Create PR_26126_037-preview-generator-v2-remove-shared-and-consolidate-common. Fix Preview Generator V2 based on audit findings. Preserve existing behavior exactly. Remove all tools/shared dependencies from Preview Generator V2, consolidate safe repeated CSS declarations into common styles, update Preview Generator V2 to consume those common styles, verify Playwright, do not modify samples, do not add schema, do not modify start_of_day folders, and produce required reports."
+```text
+codex
+
+Changes:
+Create PR_26130_034-active-game-lifecycle-controls.
+Read docs/dev/PROJECT_INSTRUCTIONS.md first.
+Limit scope to Workspace Manager V2 / Preview Generator V2 lifecycle controls.
+Once a game/tool state is opened, disable repo destination selection and game dropdown.
+In Active Game bottom controls, add Save, Close, and Cancel buttons.
+Save button must be disabled when dirty is false and enabled when dirty is true.
+Close button must be disabled when dirty is true and enabled when dirty is false.
+Close clears the active session/toolState variable only when allowed.
+Cancel must warn the user that information will be lost when dirty is true, then clear the active session/toolState only after confirmation.
+Use toolState terminology in code/docs where applicable.
+No silent fallback.
+No unrelated files.
+No start_of_day changes.
+
+Validation:
+Run npm run test:workspace-v2.
+Add/update Playwright coverage for opened-game control disabling, dirty-state Save/Close state, Close clearing clean state, and Cancel dirty warning.
+Do not run full samples smoke test; document skipped reason.
+
+Required reports:
+Create docs/dev/reports/codex_review.diff.
+Create docs/dev/reports/codex_changed_files.txt.
+Create docs/dev/reports/PR_26130_034-active-game-lifecycle-controls.md.
+Update docs/dev/codex_commands.md.
+Update docs/dev/commit_comment.txt.
+Produce required repo-structured ZIP under tmp/.
 ```
 
 ## Validation Commands
 
 ```powershell
-rg -n "tools/shared|../shared|../../tools/shared|platformShell|shared/" tools/preview-generator-v2 tools/common tests/playwright/PreviewGeneratorV2Baseline.spec.mjs
-if ($LASTEXITCODE -eq 1) { Write-Output "no tools/shared references found"; $global:LASTEXITCODE = 0 }
-rg -n "<link|<script|import .* from" tools/preview-generator-v2 tools/common tests/playwright/PreviewGeneratorV2Baseline.spec.mjs
-
-$files = Get-ChildItem -Path tools/preview-generator-v2 -Recurse -Filter *.js | Select-Object -ExpandProperty FullName
-foreach ($file in $files) {
-  node --check $file
-  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-}
-node --check tests/playwright/PreviewGeneratorV2Baseline.spec.mjs
-npx playwright test tests/playwright/PreviewGeneratorV2Baseline.spec.mjs --project=playwright --reporter=list
-git status --short -- samples tools/schemas start_of_day tests/results
-git diff --check -- tools/preview-generator-v2 tools/common tests/playwright docs/dev/codex_commands.md docs/dev/commit_comment.txt docs/dev/reports/preview_generator_v2_shared_removed.txt docs/dev/reports/preview_generator_v2_common_styles_applied.txt docs/dev/reports/preview_generator_v2_playwright_result.txt
+Get-Content -Path "docs/dev/PROJECT_INSTRUCTIONS.md"
+node --check "tools/workspace-manager-v2/js/WorkspaceManagerV2App.js"
+node --check "tools/workspace-manager-v2/js/controls/GameSelectorControl.js"
+node --check "tools/preview-generator-v2/PreviewGeneratorV2App.js"
+node --check "tests/playwright/tools/WorkspaceManagerV2.spec.mjs"
 npm run test:workspace-v2
+npm run codex:review-artifacts
 ```
 
 ## Playwright
 
-Playwright validates that Preview Generator V2 launches, the main shell/menu/status controls render, Generate Preview and Stop start disabled, Games is the default target source, a working accordion collapses/reopens, the common stylesheet loads, and the consolidated common style declarations are active.
+Playwright impacted: Yes.
 
-Expected pass behavior: the targeted Playwright test passes with one launched tool page and no page errors.
+`npm run test:workspace-v2` validates that opened Workspace Manager V2 game toolState locks repo destination and game selection, Preview Generator V2 workspace launch locks repo/game target controls, dirty toolState enables Save and disables Close, clean toolState disables Save and enables Close, Close clears clean active toolState data, and Cancel warns before discarding dirty toolState data.
 
-Expected fail behavior: the test fails if the tool cannot load, controls are missing, common styles are not applied, accordion behavior is broken, or page errors are emitted.
+Expected pass behavior: all Workspace Manager V2 Playwright tests pass with no page errors and the lifecycle buttons match dirty state.
+
+Expected fail behavior: the test fails if repo/game controls remain editable after opening a toolState, Save/Close invert dirty behavior, Close clears dirty data, or Cancel clears dirty data without confirmation.
 
 ## Test Notes
 
-`npm run test:workspace-v2` is not defined in the current `package.json`.
+`npm run test:workspace-v2` passed: 20 passed.
 
-## Manual Test
+Full samples smoke test skipped because this PR is limited to Workspace Manager V2 / Preview Generator V2 lifecycle controls and does not modify shared sample loading, sample JSON, or broadly impacted sample runtime behavior.
 
-Open `tools/preview-generator-v2/index.html`, confirm the tool shell looks unchanged, toggle Repo Destination, use Hide Header and Details/Show Header and Details, and confirm Generate Preview remains visible but disabled before required fields are complete.
+## Manual Test
 
-Full samples smoke test was skipped because this PR does not modify samples or shared sample loading.
+1. Open Workspace Manager V2.
+2. Pick the repo folder and select Asteroids.
+3. Confirm Pick Repo Folder and the game selector are disabled, Save is disabled, Close is enabled, and Cancel is enabled.
+4. Launch Palette Manager V2, make a palette edit, and return to Workspace Manager V2.
+5. Confirm Save is enabled, Close is disabled, and Cancel warns before discarding dirty toolState data.
+6. Save, then confirm Save is disabled and Close is enabled.
+7. Close and confirm the active game/toolState clears and repo/game selection can start over.

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Consolidate Preview Generator V2 shell styles without tools/shared - PR_26126_037-preview-generator-v2-remove-shared-and-consolidate-common
+Add active game lifecycle controls for Workspace V2 toolState flows - PR_26130_034-active-game-lifecycle-controls

docs/dev/reports/PR_26130_034-active-game-lifecycle-controls.md

@@ -0,0 +1,74 @@
+# PR_26130_034-active-game-lifecycle-controls
+
+## Scope
+
+- Workspace Manager V2 active game lifecycle controls.
+- Preview Generator V2 workspace-launched repo/game target locking.
+- Workspace V2 Playwright coverage for lifecycle control state transitions.
+
+## Changes
+
+- Added Active Game bottom controls: Save, Close, and Cancel.
+- Locked repo destination and game selection after an active toolState opens.
+- Save is enabled only when dirty toolState data exists.
+- Close is enabled only when active toolState data is clean.
+- Cancel warns with a confirmation dialog before discarding dirty toolState data.
+- Updated touched Workspace Manager V2 lifecycle code to use active toolState terminology.
+- Locked Preview Generator V2 workspace launch repo and game target controls.
+
+## Playwright
+
+Playwright impacted: Yes.
+
+Validated by `npm run test:workspace-v2`.
+
+Coverage added/updated:
+
+- Opened-game control disabling.
+- Dirty-state Save/Close enabled and disabled states.
+- Close clearing clean active toolState data.
+- Cancel dirty warning with dismissal and confirmation paths.
+- Preview Generator V2 workspace launch repo/game target lock.
+
+Expected pass behavior: Workspace Manager V2 and Preview Generator V2 lifecycle controls remain locked after toolState open, dirty state drives Save/Close correctly, Close only clears clean state, and Cancel requires confirmation before dirty discard.
+
+Expected fail behavior: Playwright fails if controls remain editable after open, Save/Close dirty state is inverted, Close clears dirty data, or Cancel discards dirty data without confirmation.
+
+## Validation
+
+- `node --check tools/workspace-manager-v2/js/WorkspaceManagerV2App.js` - PASS.
+- `node --check tools/workspace-manager-v2/js/controls/GameSelectorControl.js` - PASS.
+- `node --check tools/preview-generator-v2/PreviewGeneratorV2App.js` - PASS.
+- `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs` - PASS.
+- `npm run test:workspace-v2` - PASS, 20 passed.
+
+Initial `npm run test:workspace-v2` run failed because the new Cancel test used a rejected palette swatch symbol fixture. The fixture was corrected and the final required validation passed.
+
+## Coverage
+
+Playwright V8 coverage report: `docs/dev/reports/playwright_v8_coverage_report.txt`.
+
+Changed runtime JavaScript files are listed in the coverage report. Missing changed runtime JavaScript coverage is advisory and would be reported as WARN by the existing guardrail.
+
+## Full Samples Smoke
+
+Skipped. Reason: this PR is limited to Workspace Manager V2 / Preview Generator V2 lifecycle controls and does not modify shared sample loading, sample JSON, or broad sample runtime behavior.
+
+## Manual Validation
+
+1. Open Workspace Manager V2.
+2. Pick the repo folder and select a game.
+3. Confirm repo destination selection and game dropdown are disabled after the game/toolState opens.
+4. Confirm clean state disables Save and enables Close.
+5. Launch an editor tool, make a dirty change, and return.
+6. Confirm dirty state enables Save and disables Close.
+7. Click Cancel, dismiss the warning, and confirm the active toolState remains.
+8. Click Cancel again, accept the warning, and confirm the active toolState clears.
+9. Reopen a game, Save dirty data, then Close clean state and confirm the active toolState clears.
+
+## Out Of Scope
+
+- No start_of_day changes.
+- No sample JSON changes.
+- No full samples smoke test.
+- No engine core changes.