Docs Demo Dashboard Get your key
On this page
  1. DOM footprint
  2. Single-page apps
  3. How pins anchor
    1. Pin check
  4. Small screens and print
  5. Loading and performance

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:

NodeWhereWhat it is
div#comments-widget-hostend 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-pinsend 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.

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:

  1. Its id, if it has one.
  2. Its first non-empty data- attribute, such as data-testid or data-section.
  3. A path of up to five levels of tag, class and nth-of-type, checked to be unique on the page.
  4. Failing all of that, body with the stored coordinates.

This has practical consequences for a page under review:

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