Browser Widget Implementation

Use this checklist when adding or changing a browser widget.

Wiring Path

1. Authoring source:
   • shortcode, fenced codeblock, front matter, or data file.
2. Hugo render path:
   • partial or render hook emits semantic, stable DOM;
   • include data attributes needed by the runtime;
   • avoid inline styles/scripts unless there is a narrow reason.
3. Runtime:
   • add or update cdn/custom/<widget>.js;
   • register initialization through window.QL.runtime or the existing widget runtime compatibility path;
   • handle SPA route swaps and repeated initialization safely.
4. Styles:
   • alias site tokens into widget-local variables;
   • reset global component leakage inside the widget root;
   • keep controls explicit and accessible.
5. Asset loading:
   • add shared runtime assets through the generator head/CDN pipeline;
   • avoid site-local head forks.
6. Docs and tests:
   • update authoring docs and module map;
   • run a Hugo render check and a browser smoke when behavior is interactive.

Runtime Rules

• Initialization must be idempotent.
• Widgets should tolerate SPA replacement of the page body.
• Widgets should not assume a static header or global singleton page.
• Network/auth probes should use the shared guarded patterns when touching protected routes.

Files To Read

• docs/widget-integration-plan.md
• docs/javascript-module-map.md
• cdn/custom/widgetRuntime.js
• existing widget runtimes under cdn/custom/*Widget.js
• relevant Hugo shortcode/render-hook partials