---
title: "Threads and pins"
description: "A comment is attached to an element rather than to a spot on the screen, and its pin says how sure it is that it found that element again."
---

> Documentation Index
> Fetch the complete documentation index at: https://commentware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads and pins

import PinDriftStates from "../../../components/PinDriftStates.astro";

A web page moves. A comment about a broken button has to stay with that button
when the page reflows or is redesigned, or it ends up pointing at a paragraph
three sections down. So a comment in Commentware is attached to the element you
clicked, and the dot marking it on the page is its pin.

## Comments, threads and pins

A **comment** is one thing somebody wrote. A **thread** is everything written at
one spot on a page, and a **pin** is the dot marking that spot. Leaving a
comment makes a thread with one comment in it.

## Mentions

A mention is stored as a reference to the person, not parsed back out of the
text, which is what lets somebody be renamed without breaking every comment that
names them. The consequence is that a name typed as plain text looks addressed
to somebody and notifies nobody, with no error to tell you.

## What a pin records

A pin is not a pair of coordinates on a page. When you leave a comment,
Commentware records several independent observations of the **element** you
clicked — where it sits in the document, what it is called, what it says, what
landmark it is under — and a screenshot of the page as it was.

## How a pin finds its element again

Every time you open the overlay on a page, Commentware looks for each comment's
element again and scores how far the element has changed. That change is
called _drift_, and the pin says what it found:

| What the pin says                                       | What happened                                                            |
| ------------------------------------------------------- | ------------------------------------------------------------------------ |
| Still on the exact element it was left on               | Nothing relevant changed.                                                |
| The page changed slightly around this                   | The element is there, with some of its evidence gone.                    |
| The page changed around this                            | Found, but on weaker evidence. Worth a look.                             |
| Barely recognizable — this may be the wrong place       | Something matched, and it may not be the right something.                |
| Lost — that element is gone, so the pin sits where it was left | Nothing matched. The pin falls back to its original position.     |
| Not checked on this page yet                            | Nobody has opened the overlay on this page since the comment was written.  |

Past the second of those, the pin is drawn as drifted rather than as itself, so
you can see at a glance which comments have come unstuck. There are six things a
pin can say and two ways it is drawn:

Six things a pin can say, and two ways it is drawn:

- **Still on the exact element it was left on** — score 0, drawn as an ordinary pin.
- **The page changed slightly around this** — under 0.34, drawn as an ordinary pin.
- **The page changed around this** — 0.34 and over, drawn with a dashed border.
- **Barely recognizable — this may be the wrong place** — 0.67 and over, drawn with a dashed border.
- **Lost — that element is gone, so the pin sits where it was left** — score 1, drawn with a dashed border.
- **Not checked on this page yet** — no score, drawn as an ordinary pin.

**A score is about the element, not about the pin's pixels.** A pin can sit
exactly where you remember and still say the page changed around it, because the
thing it is attached to has been rewritten.

## What is kept about the page

Two things are kept beyond the screenshot:

- **Up to 128 characters of the element's opening text**, which is what tells
  "this paragraph was edited" from "this is a different paragraph". Without it a
  drifted anchor cannot tell an edit from a replacement.
- **The page's title**, which is how every list of pages names a page.

Turning screenshots off for a site stops the text being kept too — the two are
one question, and the screenshot is the large half of it rather than the whole.
The title is kept either way, because a site with no titles would leave you
with an unnavigable list rather than a smaller one. Learn more about [what
Commentware stores](/docs/what-commentware-stores/).

## An agent's pins

An agent has no browser, so a pin it places is coarser than one you placed by
clicking: it places the comment against a URL rather than against an element.
Learn more about [what an agent cannot
do](/docs/concepts/agents/#what-an-agent-cannot-do).

## Next steps

- [Move a pin and edit its screenshot](/docs/using/pins/): move a pin that has
  come unstuck, and work with its screenshot.
- [Comment on a page](/docs/using/comments/): leave, answer and resolve comments.