Force delegated Workspace Manager pager events

PR Details:
- Replaces stale/direct pager button binding with delegated click handling from a stable parent.
- Ensures PREV/NEXT handlers fire for rendered pager buttons.
- Updates selected tool, label, and mounted content.
- Adds diagnostics for pager click/state failures.
- Avoids duplicate listeners on repeated render.
- Does not restore legacy game query fallback.

Author: DavidQ

docs/dev/codex_rules.md

@@ -4,48 +4,51 @@ These rules OVERRIDE all other instructions.
 
 ## This PR
 
-Fix only Workspace Manager pager button event behavior.
+Fix only Workspace Manager pager button events using delegated click handling.
 
 Allowed:
-- targeted pager event binding repair
-- targeted state update/remount repair
+- targeted event handling changes
+- targeted diagnostics for pager clicks/state failures
 - validation report
 
 Forbidden:
-- broad cleanup
-- unrelated refactoring
-- samples changes
-- game route label changes
-- requiring `tool=` for game launch
-- restoring `gameId || game`
+- moving pager location
 - duplicate pager
-- top-shell pager restoration
 - new header/banner
+- dropdown + Select Tool + Mount flow
+- requiring `tool=`
+- restoring `gameId || game`
+- samples changes
+- broad refactor
 - start_of_day changes
 
-## Required Behavior
+## Required Event Pattern
+
+Use delegated click handling from a stable parent.
+
+Do not rely only on direct button listeners on nodes that are recreated.
+
+## Required Selectors
 
-Pager buttons must bind to rendered buttons inside mounted content.
+Use:
+- `[data-tool-host-prev]`
+- `[data-tool-host-next]`
 
-`?gameId=<id>&mount=game` must work without `tool=`.
+Do not use button text as logic.
 
-Prev/Next must:
-- update selected tool
-- update label
-- remount/activate selected tool
+## Required Diagnostics
 
-## Still Forbidden
+Silent no-op is forbidden.
 
-Do not restore:
-- `gameId || game`
-- legacy `game` query fallback
-- hidden fallback routing
-- stale memory reuse
+If click handler cannot proceed:
+- console diagnostic
+- visible diagnostic if state/tool list is missing
 
 ## Anti-Patterns Forbidden
 
 - stale DOM references
 - duplicate event listeners on repeated render
+- DOM text as state source
 - variable aliasing
 - pass-through variables
 - duplicate state

docs/dev/reports/workspace_pager_delegated_events_validation.md

@@ -0,0 +1,83 @@
+# BUILD_PR_LEVEL_20_27_FORCE_DELEGATED_WORKSPACE_PAGER_EVENTS Validation
+
+## Changed files
+- tools/shared/platformShell.js
+- tools/Workspace Manager/main.js
+- docs/dev/reports/workspace_pager_delegated_events_validation.md
+
+## Why previous binding failed
+- `tools/Workspace Manager/main.js:529` binds click handling on `document` in the Workspace Manager host page.
+- Pager controls are rendered by platform shell markup in `tools/shared/platformShell.js:882` and can be recreated during shell re-render (`tools/shared/platformShell.js:1220`).
+- Result: previous direct/host-side binding did not reliably receive live pager clicks from the rendered pager path, so PREV/NEXT appeared non-functional.
+
+## Stable parent delegated listener
+- Stable parent used: `[data-tools-platform-header]` via `queryFirst("[data-tools-platform-header]")` in `tools/shared/platformShell.js:1182`.
+- Delegated click routing is done with:
+- `target.closest("[data-tool-host-prev]")` at `tools/shared/platformShell.js:1194`
+- `target.closest("[data-tool-host-next]")` at `tools/shared/platformShell.js:1195`
+- Action is bridged to Workspace Manager with `window.top.postMessage({ type: "workspace-pager-action", action }, window.location.origin)` at `tools/shared/platformShell.js:1210`.
+
+## Selector and binding proof
+- `[data-tool-host-prev]` and `[data-tool-host-next]` exist in live pager markup at `tools/shared/platformShell.js:882`.
+- Delegated listener one-time guard exists:
+- `let workspacePagerDelegatedBound = false;` at `tools/shared/platformShell.js:23`
+- `if (workspacePagerDelegatedBound) return;` at `tools/shared/platformShell.js:1179`
+- `workspacePagerDelegatedBound = true;` at `tools/shared/platformShell.js:1187`
+- Render re-entry is safe:
+- `renderShell(currentTool)` calls `bindWorkspacePagerDelegatedEvents()` at `tools/shared/platformShell.js:1235`
+- Guard prevents duplicate listeners on repeated render.
+
+## PREV/NEXT fired and remount flow proof
+- Shell-side click diagnostic:
+- `console.info("[WorkspacePager] ... handler fired.")` at `tools/shared/platformShell.js:1202`.
+- Workspace Manager receives delegated action:
+- `window.addEventListener("message", ...)` at `tools/Workspace Manager/main.js:578`
+- `payload.type === "workspace-pager-action"` check at `tools/Workspace Manager/main.js:583`
+- Workspace diagnostic:
+- `console.info("[WorkspaceManager] ... delegated handler fired.")` at `tools/Workspace Manager/main.js:594`
+- NEXT/PREV state update path:
+- `selectToolByOffset(offset)` at `tools/Workspace Manager/main.js:607`
+- `writeSelectedToolId(...)` inside selector at `tools/Workspace Manager/main.js:275`
+- Remount/activate path:
+- `mountSelectedTool(action)` at `tools/Workspace Manager/main.js:617`
+- `runtime.mountTool(toolId, ...)` at `tools/Workspace Manager/main.js:669`
+- Label update after mount:
+- `onMounted(tool) { setCurrentLabel(tool.displayName); }` at `tools/Workspace Manager/main.js:627`
+
+## Missing state/tool list diagnostic proof
+- Missing tool list check: `if (toolIds.length === 0)` at `tools/Workspace Manager/main.js:596`
+- Visible diagnostic on failure: `renderMountDiagnostic(...)` at `tools/Workspace Manager/main.js:598`
+- Selection failure diagnostic: `renderMountDiagnostic(...)` at `tools/Workspace Manager/main.js:609`
+- Silent no-op is not used in these failure paths.
+
+## No button-text dependency proof
+- Click path uses data attributes only (`closest("[data-tool-host-prev]")` / `closest("[data-tool-host-next]")`).
+- No logic reads `[PREV]`/`[NEXT]` text as state.
+
+## Game launch without `tool=` proof
+- `readRequestedToolIdFromQuery()` exists at `tools/Workspace Manager/main.js:313`.
+- Missing/invalid `tool` resolves to empty at `tools/Workspace Manager/main.js:315`.
+- Initialization does not require `tool=`:
+- `const initialToolId = requestedToolId || (toolIds[0] || "");` at `tools/Workspace Manager/main.js:857`.
+
+## `gameId || game` fallback not restored
+- Explicit game query remains `gameId`:
+- `const gameId = (url.searchParams.get("gameId") || "").trim();` at `tools/Workspace Manager/main.js:329`.
+- Static search confirmation:
+- `NOT_FOUND url.searchParams.get("game")`
+- `NOT_FOUND gameId || game`
+
+## Samples remain untouched
+- `git diff --name-only -- samples games` returned no changed files.
+- Existing labels remain:
+- `Open <tool>` in `samples/index.render.js:104`
+- `Open with Workspace Manager` in `games/index.render.js:263`
+
+## Anti-pattern self-check
+- No stale DOM text parsing for pager actions.
+- No button-text-driven click logic.
+- No duplicate delegated listener on repeated render (guarded one-time bind).
+- No new duplicate pager introduced.
+- No `gameId || game` fallback restored.
+- No samples changes.
+- No broad refactor or scope expansion outside pager event routing and diagnostics.

docs/operations/dev/codex_commands.md

@@ -1,4 +1,4 @@
-# Codex Commands — BUILD_PR_LEVEL_20_26_REPAIR_WORKSPACE_PAGER_BUTTON_EVENTS
+# Codex Commands — BUILD_PR_LEVEL_20_27_FORCE_DELEGATED_WORKSPACE_PAGER_EVENTS
 
 ## Model
 GPT-5.4 or GPT-5.3-codex
@@ -11,58 +11,59 @@ High
 ```text
 Read docs/dev/codex_rules.md first.
 
-Execute BUILD_PR_LEVEL_20_26_REPAIR_WORKSPACE_PAGER_BUTTON_EVENTS.
+Execute BUILD_PR_LEVEL_20_27_FORCE_DELEGATED_WORKSPACE_PAGER_EVENTS.
 
 Current UAT:
-- Pager now shows: [PREV]Palette Browser / Manager[NEXT]
-- This means tool label resolution works.
-- Buttons do not function.
+- Pager renders.
+- Label resolves.
+- Buttons still do not work.
 
 Goal:
-Fix only the Workspace Manager pager button events.
+Force pager buttons to work using delegated click handling from a stable parent.
 
 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.
+1. Find the live pager render path.
+2. Ensure buttons have:
+   - data-tool-host-prev
+   - data-tool-host-next
+3. Bind one delegated click handler from a stable parent that survives re-render:
+   - preferably data-tool-host-mount-container or tool-host-workspace.
+4. Handler must detect clicks via closest("[data-tool-host-prev]") and closest("[data-tool-host-next]") or equivalent.
+5. Handler must update selected tool from the authoritative available tool list/current index.
+6. Handler must update the pager label.
+7. Handler must remount/activate selected tool content.
+8. Add console diagnostics showing PREV/NEXT handler fired.
+9. If state/tool list is missing, render visible diagnostic instead of silent no-op.
+10. Avoid duplicate listeners on repeated render.
 
 Forbidden:
-- changing samples
-- changing game launch labels
-- restoring gameId || game
-- requiring tool=
+- moving pager
 - duplicate pager
-- moving pager back to top host shell
-- new header/banner
+- relying on button text
+- requiring tool=
+- restoring gameId || game
+- changing samples
 - broad Workspace Manager refactor
 - start_of_day changes
 
-Likely files:
-- tools/Workspace Manager/main.js
-- maybe tools/shared/platformShell.js only if pager is rendered/bound there
-
 Validation:
-Create docs/dev/reports/workspace_pager_button_events_validation.md with:
+Create docs/dev/reports/workspace_pager_delegated_events_validation.md with:
 - changed files
-- 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
+- explanation why previous binding failed
+- stable parent used for delegated listener
+- proof data-tool-host-prev and data-tool-host-next exist
+- proof delegated handler is bound once
+- proof repeated render does not duplicate listener
+- proof NEXT handler fires
+- proof NEXT changes label and mounted tool
+- proof PREV handler fires
+- proof PREV changes label and mounted tool
+- proof no click path depends on button text
 - 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_26_REPAIR_WORKSPACE_PAGER_BUTTON_EVENTS.zip
+tmp/BUILD_PR_LEVEL_20_27_FORCE_DELEGATED_WORKSPACE_PAGER_EVENTS.zip
 ```

docs/operations/dev/commit_comment.txt

@@ -1,9 +1,9 @@
-Repair Workspace Manager pager button events
+Force delegated Workspace Manager pager 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.
+- Replaces stale/direct pager button binding with delegated click handling from a stable parent.
+- Ensures PREV/NEXT handlers fire for rendered pager buttons.
+- Updates selected tool, label, and mounted content.
+- Adds diagnostics for pager click/state failures.
+- Avoids duplicate listeners on repeated render.
 - Does not restore legacy game query fallback.