---

name: jsgui3-activation-debug description: 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.

jsgui3 Activation Debug

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 ....

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/JSGUI3_UI_ARCHITECTURE_GUIDE.md
• AGENTS.md quick anchor (“Client-side activation flow critical”)
• Fast browser verification (single browser, many scenarios): docs/guides/PUPPETEER_SCENARIO_SUITES.md