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