Debug jsgui3 client-side activation issues. Use when SSR renders but clicks don’t work, this.dom.el is null, or you see Missing context.map_Controls / activation 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
Confirm this is an activation issue, not just CSS/DOM.
Follow the documented activation flow and look for the canonical signatures.
If E2E is involved, rebuild the client bundle before debugging behavior.
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
