jsgui3 Activation Debug

Triggers

• "jsgui3", "clicks don’t work", "activation", "Missing context.map_Controls"

Scope

• Diagnose “renders but no interactivity” failures
• Ensure client bundle is current when tests run in a browser
• Add a minimal check script when behavior is unclear

Inputs

• Which UI server/route/control is affected
• Whether the issue reproduces in E2E (Puppeteer/Playwright)
• Whether client bundling is involved

Procedure

1. Confirm this is an activation issue, not just CSS/DOM.
2. Follow the documented activation flow and look for the canonical signatures.
3. If E2E is involved, rebuild the client bundle before debugging behavior.
4. If unclear, create a minimal reproduction check under a local checks/ folder.

Validation

• Prefer a node src/ui/**/checks/<name>.check.js script that exits cleanly.
• Then run the smallest relevant Jest suite via npm run test:by-path ....

Anti-Patterns to Avoid

• Blindly Editing CSS: Assuming a control isn't working because of z-index or pointer-events, when the real issue is that the JS activate() method never fired on the client.
• Skipping Build: Making changes to the jsgui3 control logic and running E2E tests without running npm run ui:client-build first, leading to false negatives.

Escalation / Research request

Ask for dedicated research if:

• activation semantics differ between SSR and bundled client unexpectedly
• the issue appears to involve context.map_Controls lifecycle gaps across multiple controls

References

• jsgui3 activation flow: docs/guides/JSGUI3UIARCHITECTURE_GUIDE.md
• AGENTS.md quick anchor (“Client-side activation flow critical”)
• Fast browser verification (single browser, many scenarios): docs/guides/PUPPETEERSCENARIOSUITES.md