@spec claim_for_delivery([PhoenixKit.Mentions.Mention.t()]) :: [
  PhoenixKit.Mentions.Mention.t()
]

CLAIMS delivery for these mentions, returning the ones this caller won.

WHERE notified_at IS NULL is what makes it a claim rather than a stamp: two saves of the same field racing (a double submit, two tabs) both see an unnotified row and would both send. Only the update that actually changes a row may deliver.

@spec context(
  String.t() | nil,
  keyword()
) :: map()

Everything a renderer needs for the mentions in text, in one pass.

Returns %{{type, uuid} => %{state, title, path, prefixed}} where state is :ok, :missing, or :forbidden. Batched per type: a page with thirty mentions across three types costs three resolve calls and three visibility calls.

@spec enabled?() :: boolean()

Master switch. Defaults ON — the feature is additive and inert until someone actually types a trigger.

@spec list_backlinks(String.t(), String.t(), keyword()) :: [
  PhoenixKit.Mentions.Mention.t()
]

What links here: every record mentioning this one, newest first.

The backlink panel on a record's own page. Not permission-filtered — the caller knows who is asking and what their own module's rules are.

@spec list_for_source(String.t(), String.t(), String.t()) :: [
  PhoenixKit.Mentions.Mention.t()
]

Every mention recorded for one field of one record.

@spec notify(
  list(),
  keyword()
) :: :ok

Delivers the @ pings among mentions and marks them sent.

Call it with what sync/4 returned — those are the ones that are new. Everything else is filtered here rather than by the caller:

• # links never notify. Telling a record's watchers it was referenced is a different product (and a noisy one); the reverse index is enough to build a "mentioned in" panel when that is actually wanted.
• mentioning yourself does nothing.
• someone who cannot open the containing record is not told about it. An email about a comment that 403s on click is worse than silence.

Delivery itself is core's activity → notification bridge, so a ping lands wherever that person already reads things and obeys their existing preferences and channels.

@spec redact_titles?() :: boolean()

Extra-security mode: withhold the TITLE of a mention the viewer cannot open, showing the label the author stored instead of a live one.

Off by default. On, a record renamed after being mentioned never shows its new name to someone who can't open it — worth having where the name itself is the sensitive part, and unnecessary noise where it isn't.

@spec search(:user | :resource, String.t(), keyword()) :: [map()]

Candidates for the typeahead.

kind is :user for @ (core's users only — a ping is always a person) or :resource for # (every module that opted in).

Options:

• :user_uuid — who is searching. Handlers MUST scope to this; a typeahead that offers records the searcher cannot open is itself the leak.
• :limit — max results overall (default 8).

Never raises: a handler that blows up contributes nothing and is logged.

@spec searchable_handlers() :: %{required(String.t()) => module()}

Handler modules that can be searched, as %{resource_type => module}.

Derived from the same resource_links/0 registry that powers deep-linking — a type is offerable only if it is already resolvable, so a mention can never be created that cannot later be rendered.

@spec sync(String.t(), String.t(), String.t() | nil, keyword()) ::
  {:ok, [PhoenixKit.Mentions.Mention.t()]} | {:error, term()}

Rebuilds the index for one field of one record from its text, and returns the mentions that are NEW since last time.

Call this from the durable save — creating or updating the comment, the task, the note. Never from a keystroke or an autosave draft: the return value is what gets notified, and a debounce would ping on every pause.

The delete-then-insert is scoped to this source_field, so a record with two mentionable fields keeps them independent.

@spec to_markdown(
  String.t() | nil,
  keyword()
) :: String.t()

Rewrites the mentions in text as MARKDOWN, resolved for this viewer.

For surfaces that render markdown rather than HEEx — comments, notes, anything going through MDEx. Same three states as the component, with one honest limitation: markdown output is sanitised afterwards, so a redacted mention here is plain text rather than a button. The reader still learns that something exists and that it isn't theirs; they just can't ask for access from inside a rendered comment.

Mentions.to_markdown(comment.content, scope: scope)

Text with no mentions is returned unchanged, so this is safe to put in front of every markdown render.

@spec visible(String.t(), [String.t()], keyword()) :: [String.t()]

Of uuids for type, the ones this viewer may see.

A handler with no visible_resource_uuids/2 is treated as public — see the moduledoc. Anything that raises fails CLOSED (nothing visible): a broken permission check must not become an open door.