Wire Workspace Manager V2 UAT to real template manifest and preserve generated game manifest output - PR_26127_001-workspace-manager-v2-uat-template-manifest

Author: DavidQ

docs/dev/reports/PR_26127_001-workspace-manager-v2-uat-template-manifest.md

@@ -0,0 +1,55 @@
+# PR_26127_001-workspace-manager-v2-uat-template-manifest
+
+## Scope
+
+- Read `docs/dev/PROJECT_INSTRUCTIONS.md` before implementation.
+- Renamed the template source manifest from `games/_template/game.manifest.json` to `games/_template/workspace-manager-v2-template.manifest.json`.
+- Added real UAT manifest `games/_template/workspace-manager-v2-UAT.manifest.json`.
+- Updated Workspace Manager V2 UAT button flow to load the real UAT manifest from disk instead of constructing UAT manifest data in code.
+- Updated new-game scaffold logic so generated games still receive `game.manifest.json` created from `workspace-manager-v2-template.manifest.json`.
+- Added canonical V2 launch tiles for `tools/templates-v2`, `tools/asset-manager-v2`, `tools/workspace-manager-v2`, `tools/palette-manager-v2`, and `tools/preview-generator-v2`.
+
+## Validation
+
+- `npm run test:workspace-v2` - PASS, 24 Playwright tests.
+- Explicit schema validation:
+  - `games/_template/workspace-manager-v2-UAT.manifest.json` - PASS against `tools/schemas/workspace.manifest.schema.json`.
+  - `games/_template/workspace-manager-v2-template.manifest.json` - PASS against `tools/schemas/workspace.manifest.schema.json`.
+- `git diff --check` - PASS with only Git line-ending warnings.
+- Full samples smoke test skipped by request; this PR is Workspace V2/tool UAT scoped.
+
+## Playwright Impacted
+
+Yes. This PR changes Workspace Manager V2 UAT loading, workspace tool launch tiles, and Tool Template V2 workspace nav when launched from Workspace Manager V2.
+
+Validated behavior:
+- UAT button loads `games/_template/workspace-manager-v2-UAT.manifest.json`.
+- Asset Manager V2 no longer receives direct `?workspace=UAT` access and still launches through Workspace Manager V2 session/context.
+- Five canonical V2 tool tiles render and become launch-ready after a schema-valid manifest is active.
+- Tool Template V2 launched from Workspace Manager V2 shows only `Return to Workspace`.
+- Workspace Manager V2 self tile restores the active session by `hostContextId`.
+- Import/export manifest behavior remains schema-gated.
+
+Expected pass behavior:
+- Workspace Manager V2 logs successful UAT manifest load from `games/_template/workspace-manager-v2-UAT.manifest.json`.
+- Canonical V2 tiles launch through session/context without direct workspace query fallback.
+- Return to Workspace restores the active manifest/session.
+
+Expected fail behavior:
+- Direct Asset Manager V2 workspace query launch remains blocked by the launch guard.
+- Invalid manifests block export and log the exact schema failure.
+
+## Manual Validation Notes
+
+1. Open `/tools/workspace-manager-v2/index.html?workspace=uat`.
+2. Confirm the UAT button is visible.
+3. Click UAT and confirm Status logs loading from `/games/_template/workspace-manager-v2-UAT.manifest.json`.
+4. Confirm tool tiles are present for First-Class Tool Starter V2, Asset Manager V2, Workspace Manager V2, Palette Manager V2, and Preview Generator V2.
+5. Launch Asset Manager V2 and confirm it opens through `launch=workspace` plus `hostContextId`, not `?workspace=uat`.
+6. Use Return to Workspace and confirm the active Asteroids UAT session is restored.
+
+Out of scope:
+- Full samples smoke test.
+- Deprecated `tools/workspace-v2`.
+- Sample JSON alignment.
+

games/_template/game.manifest.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "tools/schemas/workspace.manifest.schema.json",
+  "documentKind": "workspace-manifest",
+  "schema": "html-js-gaming.project",
+  "version": 1,
+  "id": "workspace-manager-v2-UAT-Asteroids",
+  "name": "Workspace Manager V2 UAT Context",
+  "gameId": "Asteroids",
+  "gameRoot": "games/Asteroids/",
+  "assetsPath": "games/Asteroids/assets",
+  "tools": {
+    "palette-manager-v2": {
+      "$schema": "tools/schemas/tools/palette-manager-v2.schema.json",
+      "schema": "html-js-gaming.palette",
+      "version": 1,
+      "id": "workspace-manager-v2-uat-sample",
+      "name": "Workspace Manager V2 UAT Sample Palette",
+      "source": "Workspace Manager V2 temporary UAT sample",
+      "sourceId": "games/_template/workspace-manager-v2-UAT.manifest.json",
+      "locked": true,
+      "swatches": [
+        {
+          "symbol": "V",
+          "hex": "#7C3AED",
+          "name": "Signal Violet!",
+          "source": "UAT Sample",
+          "tags": ["ui", "accent"]
+        },
+        {
+          "symbol": "G",
+          "hex": "#22C55E",
+          "name": "Success Green",
+          "source": "UAT Sample",
+          "tags": ["success", "hud"]
+        },
+        {
+          "symbol": "A",
+          "hex": "#F59E0B",
+          "name": "Alert Amber",
+          "source": "UAT Sample",
+          "tags": ["warning", "hud"]
+        }
+      ]
+    },
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "id": "asset-manager-v2.uat.registry",
+      "name": "Asset Manager V2 UAT Registry",
+      "source": "workspace-manager-v2",
+      "assets": {}
+    }
+  }
+}

games/_template/workspace-manager-v2-UAT.manifest.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "tools/schemas/workspace.manifest.schema.json",
+  "documentKind": "workspace-manifest",
+  "schema": "html-js-gaming.project",
+  "version": 1,
+  "id": "workspace-manager-v2-template",
+  "name": "Workspace Manager V2 Template",
+  "gameId": "_template",
+  "gameRoot": "games/_template/",
+  "assetsPath": "games/_template/assets",
+  "tools": {
+    "palette-manager-v2": {
+      "$schema": "tools/schemas/tools/palette-manager-v2.schema.json",
+      "schema": "html-js-gaming.palette",
+      "version": 1,
+      "id": "palette._template.default",
+      "name": "_template Palette",
+      "source": "manifest",
+      "swatches": [
+        {
+          "symbol": "0",
+          "hex": "#F8FAFC",
+          "name": "Template Light"
+        },
+        {
+          "symbol": "1",
+          "hex": "#0F172A",
+          "name": "Template Dark"
+        }
+      ]
+    },
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "id": "asset-manager-v2._template.registry",
+      "name": "_template Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {}
+    }
+  }
+}

games/_template/workspace-manager-v2-template.manifest.json

@@ -119,6 +119,35 @@ function Write-JsonFile {
     [System.IO.File]::WriteAllText($Path, $json + [Environment]::NewLine, [System.Text.Encoding]::UTF8)
 }
 
+function ConvertTo-WorkspaceManifestForGame {
+    param(
+        [Parameter(Mandatory = $true)]
+        [object]$TemplateManifest,
+        [Parameter(Mandatory = $true)]
+        [string]$GameId,
+        [Parameter(Mandatory = $true)]
+        [string]$GameName
+    )
+
+    $manifest = $TemplateManifest | ConvertTo-Json -Depth 40 | ConvertFrom-Json
+    $manifest.id = "workspace-manager-v2-$GameId"
+    $manifest.name = "$GameName Workspace Manager V2 Context"
+    $manifest.gameId = $GameId
+    $manifest.gameRoot = "games/$GameId/"
+    $manifest.assetsPath = "games/$GameId/assets"
+
+    if ($null -ne $manifest.tools.'palette-manager-v2') {
+        $manifest.tools.'palette-manager-v2'.id = "palette.$GameId.default"
+        $manifest.tools.'palette-manager-v2'.name = "$GameName Palette"
+    }
+    if ($null -ne $manifest.tools.'asset-manager-v2') {
+        $manifest.tools.'asset-manager-v2'.id = "asset-manager-v2.$GameId.registry"
+        $manifest.tools.'asset-manager-v2'.name = "$GameName Asset Manager V2 Registry"
+    }
+
+    return $manifest
+}
+
 function New-EmptyAssetRefs {
     return [ordered]@{
         assetIds = @()
@@ -220,6 +249,25 @@ Get-ChildItem -LiteralPath $TemplatePath -Force | ForEach-Object {
     Copy-Item -LiteralPath $_.FullName -Destination $targetGamePath -Recurse -Force
 }
 
+$workspaceManifestTemplatePath = Join-Path $TemplatePath "workspace-manager-v2-template.manifest.json"
+if (-not (Test-Path -LiteralPath $workspaceManifestTemplatePath)) {
+    throw "Workspace Manager V2 template manifest not found: $workspaceManifestTemplatePath"
+}
+$workspaceManifestTemplate = Get-Content -LiteralPath $workspaceManifestTemplatePath -Raw | ConvertFrom-Json
+$gameManifestPath = Join-Path $targetGamePath "game.manifest.json"
+$generatedWorkspaceManifest = ConvertTo-WorkspaceManifestForGame -TemplateManifest $workspaceManifestTemplate -GameId $normalizedGameId -GameName $DisplayName
+Write-JsonFile -Value $generatedWorkspaceManifest -Path $gameManifestPath
+$templateOnlyManifestFiles = @(
+    "workspace-manager-v2-template.manifest.json",
+    "workspace-manager-v2-UAT.manifest.json"
+)
+foreach ($templateOnlyManifestFile in $templateOnlyManifestFiles) {
+    $copiedTemplateOnlyManifestPath = Join-Path $targetGamePath $templateOnlyManifestFile
+    if (Test-Path -LiteralPath $copiedTemplateOnlyManifestPath) {
+        Remove-Item -LiteralPath $copiedTemplateOnlyManifestPath
+    }
+}
+
 $assetsRoot = Join-Path $targetGamePath "assets"
 Ensure-Directory -Path $assetsRoot
 
@@ -329,6 +377,7 @@ $requiredPaths = @(
     (Join-Path $assetsRoot "tilemaps\data"),
     (Join-Path $assetsRoot "parallax\data"),
     (Join-Path $assetsRoot "vectors\data"),
+    $gameManifestPath,
     $manifestPath,
     $projectManifestPath
 )
@@ -341,5 +390,6 @@ if ($missing.Count -gt 0) {
 Write-Host "Created game scaffold: $normalizedGameId"
 Write-Host "Template source: $TemplatePath"
 Write-Host "Game path: $targetGamePath"
+Write-Host "Game manifest: $gameManifestPath"
 Write-Host "Asset manifest: $manifestPath"
 Write-Host "Tool project scaffold: $projectManifestPath"

scripts/PS/New-Game-from-Template.ps1

@@ -1006,7 +1006,7 @@ test.describe("Asset Manager V2", () => {
         assetsPath: "games/Asteroids/assets",
         gameRoot: "games/Asteroids/",
         ok: true,
-        sourceId: "?workspace=UAT",
+        sourceId: "games/_template/workspace-manager-v2-UAT.manifest.json",
         swatchCount: 3
       });
 
@@ -1243,7 +1243,7 @@ test.describe("Asset Manager V2", () => {
     });
 
     try {
-      await expect(page.locator("#workspaceToolTiles [data-workspace-tool-id]")).toHaveCount(3);
+      await expect(page.locator("#workspaceToolTiles [data-workspace-tool-id]")).toHaveCount(5);
       await page.locator("#activeGameSelect").selectOption("Asteroids");
       await expect(page.locator("#workspaceContextOutput")).toContainText('"gameRoot": "games/Asteroids/"');
       await expect(page.locator("#workspaceContextOutput")).toContainText('"assetsPath": "games/Asteroids/assets"');

tests/playwright/tools/AssetManagerV2.spec.mjs

@@ -140,7 +140,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#seedUatManifestButton")).toBeHidden();
       await expect(page.locator("#loadAsteroidsButton")).toHaveText("Load Asteroids");
       await expect(page.locator("#launchAssetManagerV2Button")).toHaveCount(0);
-      await expect(page.locator("#workspaceToolTiles [data-workspace-tool-id]")).toHaveCount(3);
+      await expect(page.locator("#workspaceToolTiles [data-workspace-tool-id]")).toHaveCount(5);
       expect(await page.locator("#workspaceToolTiles [data-workspace-tool-id]").evaluateAll((tiles) => tiles.every((tile) => tile.disabled))).toBe(true);
       await expect(page.locator("#activeGameSelect option")).toHaveText([
         "Select a game",
@@ -170,20 +170,29 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#workspaceContextOutput")).not.toContainText('"workspaceMetadata"');
       await expect(page.locator("#workspaceContextOutput")).not.toContainText("samples/");
       await expect(page.locator("#exportManifestButton")).toBeEnabled();
+      const templateTile = page.locator('[data-workspace-tool-id="templates-v2"]');
       const assetTile = page.locator('[data-workspace-tool-id="asset-manager-v2"]');
+      const workspaceTile = page.locator('[data-workspace-tool-id="workspace-manager-v2"]');
       const paletteTile = page.locator('[data-workspace-tool-id="palette-manager-v2"]');
       const previewTile = page.locator('[data-workspace-tool-id="preview-generator-v2"]');
+      await expect(templateTile).toBeEnabled();
+      await expect(templateTile).toContainText("First-Class Tool Starter V2");
+      await expect(templateTile).toContainText("Canonical V2 template");
       await expect(assetTile).toBeEnabled();
       await expect(assetTile).toContainText("Asset Manager V2");
       await expect(assetTile).toContainText("Ready to launch");
       await expect(assetTile).toContainText("13 managed assets");
+      await expect(workspaceTile).toContainText("Workspace Manager V2");
+      await expect(workspaceTile).toContainText("Active workspace surface");
       await expect(paletteTile).toContainText("11 palette swatches");
       await expect(previewTile).toContainText("Schema-valid manifest");
       const tileLayout = await page.locator("#workspaceToolTiles [data-workspace-tool-id]").evaluateAll((tiles) => tiles.map((tile) => ({
         height: Math.round(tile.getBoundingClientRect().height),
         width: Math.round(tile.getBoundingClientRect().width)
       })));
       expect(tileLayout).toEqual([
+        { height: 118, width: 180 },
+        { height: 118, width: 180 },
         { height: 118, width: 180 },
         { height: 118, width: 180 },
         { height: 118, width: 180 }
@@ -324,6 +333,16 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#exportManifestButton")).toBeEnabled();
       await expect(page.locator("#statusLog")).toHaveValue(/OK Restored Asteroids workspace from session context workspace-manager-v2-/);
 
+      await page.locator('[data-workspace-tool-id="templates-v2"]').click();
+      await expect(page).toHaveURL(/templates-v2\/index\.html.*launch=workspace/);
+      await expect(page.locator('[data-launch-mode-nav="tool"]')).toBeHidden();
+      await expect(page.locator('[data-launch-mode-nav="workspace"]')).toBeVisible();
+      await expect(page.locator('[data-launch-mode-nav="workspace"]').getByRole("button")).toHaveText(["Return to Workspace"]);
+      await page.locator("#returnToWorkspaceButton").click();
+      await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
+      await page.locator('[data-workspace-tool-id="workspace-manager-v2"]').click();
+      await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
+      await expect(page.locator("#activeGameSelect")).toHaveValue("Asteroids");
       await page.locator('[data-workspace-tool-id="palette-manager-v2"]').click();
       await expect(page).toHaveURL(/palette-manager-v2\/index\.html.*launch=workspace/);
       await expect(page.locator('[data-launch-mode-nav="tool"]')).toBeHidden();
@@ -442,6 +461,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
   test("owns temporary UAT manifest seeding and launches Asset Manager V2 through session context", async ({ page }) => {
     const server = await openWorkspaceManagerV2(page, "?workspace=uat");
     const pageErrors = [];
+    const uatManifest = JSON.parse(await readFile("games/_template/workspace-manager-v2-UAT.manifest.json", "utf8"));
 
     page.on("pageerror", (error) => {
       pageErrors.push(error.message);
@@ -451,14 +471,22 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#seedUatManifestButton")).toBeVisible();
       await expect(page.locator("#exportManifestButton")).toBeDisabled();
       await page.locator("#seedUatManifestButton").click();
+      const uatManifestValidation = await page.evaluate(async (manifest) => {
+        const { WorkspaceManagerV2ContextService } = await import("/tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js");
+        return new WorkspaceManagerV2ContextService().validateGeneratedManifest(manifest);
+      }, uatManifest);
+      expect(uatManifestValidation).toEqual({ ok: true });
       await expect(page.locator("#activeGameSelect")).toHaveValue("Asteroids");
       await expect(page.locator("#activePaletteSummary")).toContainText("Workspace Manager V2 UAT Sample Palette has 3 active colors.");
       await expect(page.locator("#activeAssetRegistrySummary")).toHaveText("Schema-ready Asset Manager V2 manifest payload contains 0 managed assets.");
+      await expect(page.locator('[data-workspace-tool-id="templates-v2"]')).toContainText("Canonical V2 template");
       await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toContainText("0 managed assets");
+      await expect(page.locator('[data-workspace-tool-id="workspace-manager-v2"]')).toContainText("Active workspace surface");
       await expect(page.locator('[data-workspace-tool-id="palette-manager-v2"]')).toContainText("3 palette swatches");
+      await expect(page.locator('[data-workspace-tool-id="preview-generator-v2"]')).toContainText("Schema-valid manifest");
       await expect(page.locator("#workspaceContextOutput")).toContainText('"id": "workspace-manager-v2-UAT-Asteroids"');
-      await expect(page.locator("#workspaceContextOutput")).toContainText('"sourceId": "?workspace=UAT"');
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Seeded temporary UAT Workspace Manager V2 manifest workspace-manager-v2-UAT-Asteroids\./);
+      await expect(page.locator("#workspaceContextOutput")).toContainText('"sourceId": "games/_template/workspace-manager-v2-UAT.manifest.json"');
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded UAT Workspace Manager V2 manifest workspace-manager-v2-UAT-Asteroids from \/games\/_template\/workspace-manager-v2-UAT\.manifest\.json\./);
 
       await page.locator('[data-workspace-tool-id="asset-manager-v2"]').click();
       await expect(page).toHaveURL(/asset-manager-v2\/index\.html.*launch=workspace/);

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -46,6 +46,7 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
       <button id="workspaceImportManifestButton" type="button">Import manifest</button>
       <button id="workspaceCopyManifestButton" type="button">Copy manifest</button>
       <button id="workspaceExportManifestButton" type="button">Export manifest</button>
+      <button id="returnToWorkspaceButton" type="button" hidden>Return to Workspace</button>
     </nav>
 
     <main class="tool-starter app-shell" data-tool-id="tool-template-v2">