Website-Aware Overlays

Context-aware overlays normally pick a shortcut layer from the app you’re in. But a browser is a special case: Gmail, Jira, Figma and every other web app all run inside the same browser process, and their window titles are inconsistent — so the app name “chrome” is not enough to identify them.

Website detection fixes that: PolyKybdHost can see the URL of your focused browser tab and match an overlay to the website, so switching from Jira to Outlook in the same browser re-labels your keycaps just like switching between two native apps.

How the URL reaches the host

PolyKybdHost gets the active tab’s URL from one of two sources:

Platform	Source	Install needed
Windows / Linux	The browser extension (below)	Yes — install the extension
macOS (Chrome, Edge, Brave, Vivaldi, Opera, Arc, Safari)	Built-in AppleScript query	No, works without setup
Firefox on macOS	The browser extension	Yes — AppleScript cannot read the URL from Firefox

The extension sends only the tab’s URL, its title, and whether the window is focused — to http://127.0.0.1 (your own machine) and nowhere else. No page content is ever read. See the extension privacy policy for the full details.

Installing the browser extension

The extension works on all Chromium browsers (Chrome, Edge, Brave, Vivaldi, Opera, Arc) and Firefox. Once it’s published you’ll install it from the Chrome Web Store or Firefox Add-ons in one click, with automatic updates. To load it manually in the meantime:

Chromium: chrome://extensions → enable Developer mode → Load unpacked → pick the dist/chromium/ folder from a build.sh run.
Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on → pick dist/firefox/manifest.json.

Then open the extension’s Options, confirm the Host port matches PolyKybdHost’s browser_report_port (default 50164), and click Test connection — it should read Connected to PolyKybdHost ✓.

Host settings

Website detection is controlled by a few settings in PolyKybdHost (Settings dialog, or polyctl settings):

Setting	Default	What it does
`browser_url_detection`	on	Master switch for the whole feature. Off → browser overlays match on title only.
`browser_report_local_enabled`	on	Runs the loopback receiver the extension posts to. Bound to `127.0.0.1` only.
`browser_report_port`	`50164`	Port the receiver listens on — must match the extension’s Host port.
`browser_report_token`	(empty)	Optional shared secret. When set, a report must present the same token (set it in the extension Options too) — extra defence against other local apps.

Mapping overlays to websites

In your overlay mapping, a browser entry can contain a urls-contains block: each key is a substring matched against the focused tab’s URL, and the first match is used. URL matches take priority over titles-contains, and both are kept so title matching still works whenever no URL is available.

chrome,google-chrome,chromium,brave,msedge,microsoft-edge,vivaldi,opera,arc:
  overlay: [chrome_template.mods.png, chrome_template.combo.mods.png]
  urls-contains:
    atlassian.net:   { overlay: jira_template.mods.png }
    outlook.office.com: { overlay: web_outlook_template.mods.png }
    miro.com:        { overlay: miro_template.mods.png }
  titles-contains:
    Jira:   { overlay: jira_template.mods.png }
    Outlook:{ overlay: web_outlook_template.mods.png }

The browser’s shortcuts stay underneath

A web app runs inside the browser, so the browser’s own shortcuts still work on every site: new tab, reload, find, zoom, switching tabs. Since host 1.16.0 a website’s overlay is drawn on top of the browser’s instead of replacing it:

A key the website’s overlay draws shows the website’s shortcut.
Every other key keeps the browser’s shortcut.

So with GitHub open, Ctrl still shows new tab on T and the address bar on L, next to GitHub’s own keys. Nothing changes in your mapping file: the browser entry’s overlay is the bottom layer, and the matched urls-contains or titles-contains entry goes on top.

Browser keys are drawn dimmed

With firmware 1.8.3 and host 1.16.2 or later, the keys that still show the browser’s shortcut under a website’s overlay are drawn dimmed: the keyboard lights a quarter of the icon’s pixels, every other row and every other column. The website’s own shortcuts stay at full strength, so they stand out, and the browser’s are still readable.

Only the icon is dimmed. The key’s letter and its Shift and AltGr previews stay at full brightness.
The program icon on Esc is never dimmed.
With no website match, the browser’s overlay is drawn at full strength as before.

With an older keyboard or host, everything is drawn at full strength.

Across two machines

Website detection also works for a computer you are forwarding from — see Multi-Machine Setup. Install the browser extension on the remote machine (it always reports to 127.0.0.1 on its own machine, so nothing about it changes) and run the forwarder with --report-rpc. The focused tab’s URL is then sent with the window report, and your urls-contains entries match forwarded browsers exactly as local ones.