Repair Workspace Manager pager button events

PR Details:
- Fixes Prev/Next click handling for the mounted Workspace Manager pager.
- Keeps resolved tool labels working.
- Updates selected and mounted tool on pager navigation.
- Ensures game launches work without requiring tool=.
- Avoids stale DOM references and duplicate event listeners.
- Does not restore legacy game query fallback.

Author: DavidQ

docs/dev/codex_rules.md

@@ -4,46 +4,35 @@ These rules OVERRIDE all other instructions.
 
 ## This PR
 
-Fix only:
-- Workspace Manager host/mount size
-- tool query resolution for pager/mount
+Fix only Workspace Manager pager button event behavior.
 
 Allowed:
-- targeted Workspace Manager CSS/layout changes
-- targeted Workspace Manager tool resolution changes
+- targeted pager event binding repair
+- targeted state update/remount repair
 - validation report
 
 Forbidden:
 - broad cleanup
 - unrelated refactoring
 - samples changes
-- game launch label changes
-- legacy query fallback
-- second SSoT
+- game route label changes
+- requiring `tool=` for game launch
+- restoring `gameId || game`
+- duplicate pager
+- top-shell pager restoration
 - new header/banner
 - start_of_day changes
 
-## Required Layout
+## Required Behavior
 
-Workspace Manager must fill the browser viewport/page area.
+Pager buttons must bind to rendered buttons inside mounted content.
 
-Do not leave:
-- tiny upper-left box
-- clipped mini pane
-- constrained host shell
-- blank mount container
+`?gameId=<id>&mount=game` must work without `tool=`.
 
-## Required Tool Resolution
-
-For valid:
-`tool=palette-browser`
-
-Pager must show resolved display name, not `No tool available`.
-
-## User-Approved Behavior
-
-If no explicit tool query exists:
-- first available tool may be selected/mounted on load.
+Prev/Next must:
+- update selected tool
+- update label
+- remount/activate selected tool
 
 ## Still Forbidden
 
@@ -55,13 +44,11 @@ Do not restore:
 
 ## Anti-Patterns Forbidden
 
+- stale DOM references
+- duplicate event listeners on repeated render
 - variable aliasing
 - pass-through variables
 - duplicate state
-- vague names
-- hidden query fallback
-- duplicated launch paths
-- silent redirects
 - silent caught errors
 - broad refactor
 - scope expansion

docs/dev/reports/workspace_pager_button_events_validation.md

@@ -0,0 +1,95 @@
+# BUILD_PR_LEVEL_20_26_REPAIR_WORKSPACE_PAGER_BUTTON_EVENTS Validation
+
+## Changed Files
+- `tools/Workspace Manager/main.js`
+- `docs/dev/reports/workspace_pager_button_events_validation.md`
+
+## Root Cause Of Non-Functioning Buttons
+- `main.js` captured pager nodes once at module load (`document.querySelector(...)`) before/without stable guarantees that the rendered pager nodes were the active nodes.
+- Button handlers were previously attached directly to those captured refs, so stale/null refs caused non-functional Prev/Next.
+
+## Repair Implemented
+- Added live pager ref refresh:
+  - `tools/Workspace Manager/main.js:113` `function refreshPagerRefs()`
+- Added delegated pager event binding with one-time guard:
+  - `tools/Workspace Manager/main.js:528` `function bindPagerDelegatedEvents()`
+  - `tools/Workspace Manager/main.js:529` guard: `if (pagerEventsBound || typeof document === "undefined") {`
+  - `tools/Workspace Manager/main.js:532` `pagerEventsBound = true;`
+  - `tools/Workspace Manager/main.js:534` delegated `click` listener
+  - `tools/Workspace Manager/main.js:558` delegated `change` listener
+
+## Proof Pager Label Still Resolves
+- Pager label source remains display-name based in platform shell:
+  - `tools/shared/platformShell.js:876` `data-tool-host-current-label>${escapeHtml(currentTool?.displayName || "Tool")}`
+- Runtime mount still updates label to active mounted tool display name:
+  - `tools/Workspace Manager/main.js:577` `onMounted(tool) {`
+  - `tools/Workspace Manager/main.js:578` `setCurrentLabel(tool.displayName);`
+
+## Proof NEXT Changes Selected Tool Label
+- Delegated NEXT handling:
+  - `tools/Workspace Manager/main.js:549` `if (target.closest("[data-tool-host-next]")) {`
+  - `tools/Workspace Manager/main.js:554` `mountSelectedTool("next");`
+- Selected tool id updates before mount:
+  - `tools/Workspace Manager/main.js:267` `function selectToolByOffset(offset) {`
+  - `tools/Workspace Manager/main.js:274` `writeSelectedToolId(toolIds[nextIndex]);`
+- Mounted label updates from `onMounted` (lines above).
+
+## Proof NEXT Remounts/Activates Selected Tool
+- NEXT path calls mount:
+  - `tools/Workspace Manager/main.js:554` `mountSelectedTool("next");`
+- `mountSelectedTool` calls runtime mount:
+  - `tools/Workspace Manager/main.js` mount flow (existing) performs `runtime.mountTool(...)`.
+
+## Proof PREV Changes Selected Tool Label
+- Delegated PREV handling:
+  - `tools/Workspace Manager/main.js:540` `if (target.closest("[data-tool-host-prev]")) {`
+  - `tools/Workspace Manager/main.js:545` `mountSelectedTool("prev");`
+- Selected tool id updates via offset logic:
+  - `tools/Workspace Manager/main.js:274` `writeSelectedToolId(toolIds[nextIndex]);`
+- Label updates via `onMounted`:
+  - `tools/Workspace Manager/main.js:578` `setCurrentLabel(tool.displayName);`
+
+## Proof PREV Remounts/Activates Selected Tool
+- PREV path explicitly remounts:
+  - `tools/Workspace Manager/main.js:545` `mountSelectedTool("prev");`
+
+## Proof Game Launch Works Without tool=
+- Game launch path reads `requestedToolId` then falls back to first available:
+  - `tools/Workspace Manager/main.js:696` `const requestedToolId = readRequestedToolIdFromQuery();`
+  - `tools/Workspace Manager/main.js:707` `const toolId = requestedToolId || (toolIds[0] || "");`
+  - `tools/Workspace Manager/main.js:721` `mountSelectedTool("popstate");`
+- Initial load path has same fallback:
+  - `tools/Workspace Manager/main.js:806` `const initialToolId = requestedToolId || (toolIds[0] || "");`
+  - `tools/Workspace Manager/main.js:836` `if (!mountSelectedTool("init")) {`
+
+## Proof tool= Is Not Required
+- Fallback to first available tool remains in both popstate/init paths:
+  - `tools/Workspace Manager/main.js:707`
+  - `tools/Workspace Manager/main.js:738`
+  - `tools/Workspace Manager/main.js:806`
+
+## Proof No Duplicate Event Listeners On Repeated Render
+- One-time bind guard prevents duplicate delegated listeners:
+  - `tools/Workspace Manager/main.js:529` `if (pagerEventsBound || typeof document === "undefined") {`
+  - `tools/Workspace Manager/main.js:532` `pagerEventsBound = true;`
+
+## Proof gameId || game Fallback Not Restored
+- `gameId` only is still used:
+  - `tools/Workspace Manager/main.js:328` `const gameId = (url.searchParams.get("gameId") || "").trim();`
+- Search checks:
+  - `NOT_FOUND gameId || game`
+  - `NOT_FOUND searchParams.get("game")`
+  - `NOT_FOUND searchParams.get('game')`
+
+## Proof Samples Remain Untouched
+- Check result: `SAMPLES_UNCHANGED`
+- Based on `git diff --name-only -- samples`.
+
+## Anti-Pattern Self-Check
+- Stale DOM ref binding removed from pager events: PASS
+- Delegated stable-parent handling added: PASS
+- Duplicate listener guard added: PASS
+- No `gameId || game` fallback restored: PASS
+- No requirement for `tool=` introduced: PASS
+- No samples changes: PASS
+- Scope stayed targeted to pager event repair: PASS

docs/operations/dev/codex_commands.md

@@ -1,4 +1,4 @@
-# Codex Commands — BUILD_PR_LEVEL_20_25_FIX_WORKSPACE_HOST_SIZE_AND_TOOL_RESOLUTION
+# Codex Commands — BUILD_PR_LEVEL_20_26_REPAIR_WORKSPACE_PAGER_BUTTON_EVENTS
 
 ## Model
 GPT-5.4 or GPT-5.3-codex
@@ -11,63 +11,58 @@ High
 ```text
 Read docs/dev/codex_rules.md first.
 
-Execute BUILD_PR_LEVEL_20_25_FIX_WORKSPACE_HOST_SIZE_AND_TOOL_RESOLUTION.
+Execute BUILD_PR_LEVEL_20_26_REPAIR_WORKSPACE_PAGER_BUTTON_EVENTS.
 
-Current UAT failure:
-- Page renders in the upper-left corner too small to use.
-- It should fill the browser page area top/bottom/left/right.
-- This is not browser fullscreen mode; it is full available page layout.
-- Pager shows: [PREV]No tool available[NEXT]
-- Example URL:
-  tools/Workspace Manager/index.html?gameId=Bouncing-ball&mount=game&tool=palette-browser
+Current UAT:
+- Pager now shows: [PREV]Palette Browser / Manager[NEXT]
+- This means tool label resolution works.
+- Buttons do not function.
 
 Goal:
-Fix Workspace Manager host/mount layout size and resolve selected tool query.
+Fix only the Workspace Manager pager button events.
 
-Required layout:
-- html/body/tool-host-page/tool-host-workspace/tool-host-workspace__mount must support full available browser size.
-- No tiny fixed upper-left viewport.
-- No clipped mini scrollbox.
-- Mounted Workspace Manager content should fill available width/height.
-
-Required tool behavior:
-- read explicit tool query.
-- resolve tool=palette-browser through existing registry/SSoT.
-- pager displays resolved display name, e.g. Palette Browser / Manager.
-- selected tool mounts/activates.
-- if no explicit tool query exists, select/mount first available tool.
-- if explicit tool is invalid, show visible diagnostic inside page/mount container.
+Required:
+- Bind Prev/Next handlers to the actual rendered pager buttons inside mounted content.
+- Ensure handlers are attached after pager render or through delegated handling from stable parent.
+- Do not bind to removed/stale top-shell pager nodes.
+- Avoid duplicate event listeners on repeated render.
+- NEXT updates selected tool, updates label, and remounts/activates selected tool.
+- PREV updates selected tool, updates label, and remounts/activates selected tool.
+- Game launch must work without tool query:
+  tools/Workspace Manager/index.html?gameId=Bouncing-ball&mount=game
+- tool= may initialize selection if present, but must not be required.
 
 Forbidden:
 - changing samples
-- changing labels
+- changing game launch labels
 - restoring gameId || game
-- legacy game query fallback
-- second SSoT
+- requiring tool=
+- duplicate pager
+- moving pager back to top host shell
 - new header/banner
 - broad Workspace Manager refactor
 - start_of_day changes
 
 Likely files:
 - tools/Workspace Manager/main.js
-- tools/Workspace Manager/toolHost.css
-- any existing Workspace Manager mounted-content CSS only if directly responsible for tiny viewport
+- maybe tools/shared/platformShell.js only if pager is rendered/bound there
 
 Validation:
-Create docs/dev/reports/workspace_host_size_and_tool_resolution_validation.md with:
+Create docs/dev/reports/workspace_pager_button_events_validation.md with:
 - changed files
-- proof host page fills browser viewport
-- proof mount container fills available browser area
-- proof no tiny upper-left constrained viewport remains
-- proof tool=palette-browser resolves to display name
-- proof pager no longer shows No tool available for valid game/tool
-- proof selected tool mounts/activates
-- proof missing tool selects first available tool
-- proof invalid tool renders visible diagnostic
+- root cause of non-functioning buttons
+- proof pager label still resolves
+- proof NEXT changes selected tool label
+- proof NEXT remounts/activates selected tool
+- proof PREV changes selected tool label
+- proof PREV remounts/activates selected tool
+- proof game launch works without tool=
+- proof tool= is not required
+- proof no duplicate event listeners on repeated render
 - proof gameId || game fallback not restored
 - proof samples remain untouched
 - anti-pattern self-check
 
 Return ZIP at:
-tmp/BUILD_PR_LEVEL_20_25_FIX_WORKSPACE_HOST_SIZE_AND_TOOL_RESOLUTION.zip
+tmp/BUILD_PR_LEVEL_20_26_REPAIR_WORKSPACE_PAGER_BUTTON_EVENTS.zip
 ```

docs/operations/dev/commit_comment.txt

@@ -1,9 +1,9 @@
-Fix Workspace Manager host size and tool resolution
+Repair Workspace Manager pager button events
 
 PR Details:
-- Expands Workspace Manager host and mount container to fill available browser page area.
-- Resolves explicit tool query values through the tool registry.
-- Shows resolved tool name in pager instead of No tool available.
-- Mounts/activates selected tool.
-- Keeps first-tool default only when no explicit tool is provided.
+- Fixes Prev/Next click handling for the mounted Workspace Manager pager.
+- Keeps resolved tool labels working.
+- Updates selected and mounted tool on pager navigation.
+- Ensures game launches work without requiring tool=.
+- Avoids stale DOM references and duplicate event listeners.
 - Does not restore legacy game query fallback.