Bookmarklet Troubleshooting

The bookmarklet is intentionally a thin loader: it injects a single script tag, which then renders the FoxChat UI inside a Shadow DOM. When something goes wrong, it is almost always one of five failures. Here they are with their fixes.

Failure 1: Content-Security-Policy blocks the script

Symptom: you click the bookmarklet, nothing happens, and your browser console shows a CSP violation like Refused to load the script 'https://app.getfoxchat.com/bookmarklet-recorder.js' because it violates the following Content Security Policy directive: "script-src 'self'".

The fix: the host site's CSP forbids third-party script tags, and bookmarklets are subject to the host page's CSP just like any other inline script. Workarounds:

• Record the same flow on a less restrictive page. Most apps have a public marketing site or a pre-login page where CSP is looser; record there.
• Use the Chrome extension instead. Extension content scripts run in an isolated world and ignore page CSP. See recording from the extension.
• Add the FoxChat domain to your CSP allowlist. If you control the site, add https://app.getfoxchat.com to your script-src directive. This unblocks the bookmarklet permanently for that site.

Failure 2: Shadow DOM CSS conflicts

Symptom: the FoxChat panel appears, but it looks broken — text is huge, colors are wrong, or the layout has collapsed.

The FoxChat panel renders inside a Shadow DOM root precisely to isolate its styles from the host page. In modern browsers this works automatically. In rare cases the issue is one of:

• The host page injects a global * { all: initial } reset that crosses Shadow DOM boundaries. Some legacy reset libraries do this. The fix is to refresh the page; FoxChat retries with a fallback style sheet on the second injection.
• The host page's !important rules target attributes the panel uses. If the host has div { font-size: 30px !important } with no scoping, that can leak into the Shadow DOM in older browsers. Workaround: open the bookmarklet on a different page on the same site (like the homepage or a logged-out marketing page) where the rule isn't applied.
• Browser zoom is non-100%. The panel uses vw/vh sizing; if you're at 67% zoom or 200% zoom on a small screen, the panel can clip. Reset zoom to 100% with Ctrl+0.

Failure 3: Esc-to-close doesn't work

Symptom: the panel is open, you press Esc, nothing happens.

The most common cause is that the host page captures the keydown event in a global handler that calls preventDefault. Some custom video players and presentation tools do this for their own keyboard shortcuts. Workarounds:

• Click the explicit Close button in the panel chrome.
• Click anywhere outside the panel that's not a button on the host page.
• Open the browser dev tools (F12) and run document.querySelector('foxchat-shadow-host')?.remove() in the console.

If Esc consistently fails on a specific site, please report it — we maintain a per-site quirks list.

Failure 4: Replay does nothing for a step

Symptom: the playback bookmarklet shows a step, you click Replay, the highlight does not re-animate.

This happens when the underlying element has been removed or recycled by the host page's framework between the time the step rendered and the time you clicked replay. Single-page apps that use virtual DOM diffing (React, Vue, Svelte) can swap out a button while leaving its visual position the same. Workaround:

• Click Next then Prev — this forces the runtime to re-locate the element using the seven-identifier fallback chain.
• Click Restart to start the walkthrough over from step 1; this re-runs the locator for every step.
• If the element is genuinely gone (the host page redesigned), the step needs to be re-recorded. Open the walkthrough in your dashboard and use the per-step re-record affordance.

Failure 5: Bookmarklet doesn't drag to the bookmarks bar

Symptom: you try to drag the orange Record button from the bookmarklet page to your bookmarks bar, the cursor refuses to drop, or the drop creates a regular bookmark to the page itself instead of a javascript: URL.

Browser-specific causes:

• Chrome on Linux: some window managers intercept drag events from Chrome to a different application strip. The fix is to drag straight up to the bookmarks bar inside Chrome itself, not across windows.
• Safari: Safari sometimes refuses javascript: URLs as drag targets if the bookmarks bar is in compact mode. Switch the bookmarks bar to expanded mode (View → Show Favorites Bar in expanded view).
• Firefox with a strict containers extension: some container-based extensions block drag-drop into bookmarks. Try in a clean profile or temporarily disable the extension.
• Bookmarks bar hidden: if the bar isn't visible, the drop has nowhere to go. Press Ctrl+Shift+B first.