What it does to your page
The script is a guest. It is built to leave the page it lands on alone, and this is the precise account of what it does touch.
DOM footprint
After a successful key check the script adds three things and nothing else:
| Node | Where | What it is |
|---|---|---|
div#comments-widget-host | end of <body> | A zero-size position: fixed element holding an open shadow root. The toolbar, side panel, login panel and menus render inside it. z-index: 2147483646. |
div#comments-widget-pins | end of <body> | A zero-size position: absolute element at the page origin. Pins and comment bubbles are drawn here in page coordinates so they scroll with the content. z-index: 2147483644. Not in a shadow root, so that pins can sit over the real page. |
<style> | <head> | Styles for the pin container, scoped to #comments-widget-pins, plus the print rule below. |
Everything in the shadow root is isolated from your CSS in both directions: your stylesheet cannot restyle the toolbar, and the widget's styles cannot leak into your page. The widget does not load a stylesheet, fonts or images from a third party; its styles are in the script. The bar layout additionally sets a custom property and padding, described under layout.
Both containers have pointer-events: none; only the controls inside them accept clicks. While a visitor is in commenting mode the page receives a click to place a pin and nothing else. The widget does not intercept your forms, links or keyboard input, apart from the Alt shortcuts.
Light or dark theme is chosen per visitor from the account menu and stored in the browser. It is applied as a data attribute on the widget's own containers, never on your document.
Single-page apps
The script follows client-side navigation. When the URL changes, the open comment closes, commenting mode ends, and the pins for the new page are shown. Navigation is detected from popstate, hashchange and a check of the URL every 400 ms. The script deliberately does not patch history.pushState: reaching into the host page's History object is not something a guest should do, and the poll costs nothing measurable.
If your router re-renders large parts of the page, pins re-anchor to the new elements by selector. See the next section for what makes that reliable.
How pins anchor
A pin is not a pair of coordinates. When a comment is placed, the script records the element under the cursor and where within that element the click landed, as fractions of its box. Absolute page coordinates are kept only as a fallback. When the page is shown again, the element is found and the pin is drawn at the same fraction of wherever the element now is, so pins survive responsive layouts, content that grows above them and most redesigns.
The element is identified by a selector, chosen in this order:
- Its
id, if it has one. - Its first non-empty
data-attribute, such asdata-testidordata-section. - A path of up to five levels of tag, class and
nth-of-type, checked to be unique on the page. - Failing all of that,
bodywith the stored coordinates.
This has practical consequences for a page under review:
- Stable ids and data attributes give the most durable pins. A hashed class name from a CSS-in-JS library changes on every build and will not be found again. If you already use
data-testidfor tests, pins get that for free. - A pin in a sheet, dialog, drawer or side panel is kept by that overlay's role and name, then by its path inside it, so it comes back in the right one whichever was opened first. An overlay that says it is a dialog (
role="dialog"; in React Native,accessibilityRole) and has a name of its own (aria-labeloraccessibilityLabel) holds its pins best. - Same-origin iframes and open shadow roots are supported. A pin can land on an element inside either, and the selector records the boundary it crossed. Cross-origin iframes are opaque: a pin over one anchors to the iframe element itself.
- An element that is on the page but cannot be seen, such as an item in a closed menu, a hidden tab or a side panel that slid away, hides its pins until it shows again. The side panel lists the comment as Not visible now.
- An element that disappears takes its pins with it until it returns. The comment is still in the side panel, marked Element not found, and the panel's Only detached filter lists every one of them.
Pin positions are recomputed at most once per animation frame, on resize, on scroll inside any scrollable box on the page, on scroll and resize inside same-origin iframes, and on navigation. There is no scroll listener on your window as a rule: pins live in page coordinates and scroll natively.
Elements that do not scroll with the page are followed too. A pin on anything inside a position: fixed ancestor is drawn fixed, in viewport coordinates, so it stays on its element while the page moves underneath, and so do its comment thread and the form while a comment is being written. A pin on anything inside a position: sticky ancestor is recomputed on the window's scroll for as long as such a pin is on the page, which is the one case where the window's scroll is listened to. A fixed element under a transformed ancestor is not fixed to the viewport, and is treated as the ordinary page content it behaves as.
A pin can be pointed at a different element after the fact: its author drags it, and where it is dropped is re-anchored exactly as the first placement was, element and all — the same outline and selector label appear while it travels, and a same-origin iframe or open shadow root is as valid a destination as the top document. Only the author's drag does anything; for everybody else the pin only opens its thread, which is what a press that never moves does in either case. Escape during the drag puts it back, and so does the Undo on the confirmation.
Pin check
On a local address, and for the owner of the site's key, the script also says what on the page will keep pins from staying put. As sheets and dialogs come into view, and as a pin is placed, it looks for an overlay that does not say it is a dialog, has no name, has a name every overlay could have (Modal, or a library's default such as Bottom Sheet) or changes its name while open, and for an element known only by class names a build makes up. Each is said once per page load as a [SharedLayers] Pin check warning in the console, with the element and the fix: a role, a fixed name, a test id. On a local app the same findings go into .sharedlayers/pin-check.json once a project folder is chosen, for a coding AI to propose the fixes; see With an AI agent. Visitors' consoles stay quiet.
Small screens and print
Below 640 px wide the widget renders nothing and fetches nothing. Reviewing a phone layout is best done in a desktop browser's device mode, where the window stays wide. The check follows the window, so a desktop window dragged narrow hides the widget and dragged wide brings it back.
Both containers carry display: none under @media print. Nothing of SharedLayers appears on a printed page or in a print-to-PDF.
Loading and performance
- One file. The script is about 255 KB compressed. It carries its own rendering library, styles and database client; nothing else is fetched to draw the toolbar.
- Cached at the edge. The file is served with a 5 minute freshness window and a day of stale-while-revalidate, so repeat views cost nothing and a fix reaches every installation within minutes. Details under Versioning.
- One request to boot. The key check, the layer list and the comments of the current layer come back in a single call, sent the moment the script runs, before the page has finished parsing.
asyncon the tag brings that moment forward. - The first visit waits for that answer before anything is drawn; half-mounting and retracting would be worse than appearing a beat late. Visits within the next hour mount at once on the remembered answer and ask again in the background. If the key has been revoked, the plan has lapsed or the domain limit has been reached since, the widget removes itself again. A loading indicator in the toolbar gives up after 6 seconds and shows the controls regardless.
- Sign-in is read alongside, not first. The visitor's session is read from storage while the boot request is in flight, and comments appear as soon as both are back. The script then subscribes to live updates over one websocket per site. New comments from other people appear without reloading.
- Snapshots are rendered after the comment is saved, off the critical path, with a hard 8 second budget. Turn them off on very heavy pages if the render is noticeable.