Add @handle.tld mention support: profile links and Bluesky notifications

[jeherve]

Fixes #142

Proposed changes:

Adds Bluesky @handle.tld mention support so authors can notify accounts and link to their profiles. This works in two places: a display-side linkifier (includes/class-mention.php) wraps bare handles in the_content as profile links routed through the appview_url() helper (so they honor the atmosphere_appview_host filter), and a publishing-side carry-over pulls resolvable body mentions into long-form and teaser-thread Bluesky post text so mentioned accounts are notified even when the mention is buried deep in the body. It also replaces the unreliable did:web:<handle> resolution fallback in Facet::resolve_mention() with the real handle-resolution chain (Resolver::handle_to_did()), memoized per request to bound lookups.

Other information:

• Have you written new tests for your changes, if applicable?

Testing instructions:

• Publish a post whose body mentions a real Bluesky account using @handle.tld (e.g. @bsky.app).
• On the front end, confirm the handle renders as a link to the account's profile on your site's appview host.
• On Bluesky, confirm the published post (including long-form and teaser-thread variants) carries the mention so the account is notified, and that the mention resolves to the correct DID rather than a dead did:web profile.
• Run composer lint and npm run env-test — both pass (786 tests).

Changelog entry

A changelog entry is already committed at .github/changelog/add-content-mentions (Significance: minor, Type: added).

[Copilot]

Pull request overview

Adds end-to-end Bluesky @handle.tld mention support across both display rendering (auto-linking handles to appview profiles) and publishing (ensuring mentions buried in long-form bodies are carried into Bluesky post text so they generate proper #mention facets and notifications). It also switches mention DID resolution to the full AT Protocol handle-resolution chain and memoizes resolutions per request to bound repeated lookups.

Changes:

• Introduces a display-side mention linkifier (Atmosphere\Mention) hooked into the_content, with a suppression guard for transformer/plain-text rendering paths.
• Extends Bluesky post composition to carry resolvable body mentions into long-form/link-card and teaser-thread outputs while staying within the 300-grapheme limit.
• Updates facet mention resolution to use Resolver::handle_to_did() with request-scoped memoization, and adds PHPUnit coverage for mention resolution and carry-over behavior.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/phpunit/tests/transformer/class-test-post.php	Adds long-form/teaser-thread tests verifying mention carry-over and facet shape; includes HTTP stubbing helper.
tests/phpunit/tests/transformer/class-test-facet.php	Adds tests for resolved DID mentions, unresolvable mention behavior, and resolve_handles() output; includes HTTP stubbing helper.
tests/phpunit/tests/transformer/class-test-document.php	Verifies document HTML content keeps mention links (linkifier active on document render path).
tests/phpunit/tests/class-test-mention.php	New unit tests for the display-side mention linkifier, host filter behavior, and suppression guard scoping.
readme.txt	Updates end-user documentation to describe @handle.tld mention linking + notification behavior.
includes/transformer/class-post.php	Implements body-mention carry-over into composed Bluesky post text and teaser-thread CTA; guards Bluesky text generation against linkified HTML.
includes/transformer/class-facet.php	Adds shared mention regex constant, request-scoped resolution cache, resolve_handles(), and switches mention DID resolution to Resolver chain.
includes/transformer/class-base.php	Suppresses mention auto-linking in the shared plain-text render path used for Bluesky text composition.
includes/class-mention.php	New mention linkifier that wraps bare handles in profile links via appview_url(), with protected-tag skipping and a suppression guard.
includes/class-atmosphere.php	Registers the mention linkifier on init so it applies to front-end and document-parser rendering.
.github/changelog/add-content-mentions	Adds a minor “added” changelog entry describing mention support.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pfefferle]

Some things that I checked:

• The @-mention detection misinterprets domain like WebFinger handles as profile handles: @notiz.blog@notiz.blog
• There is no lookup if accounts really exist, so even an example mention like @example.com will be linked.

Not (yet) checked: Does the implementation also takes care of the recent implemented "Custom Bluesky text"!?

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[jeherve]

Thanks @pfefferle — addressed all three. Two new commits: 4aab0d2 (tests for the custom-text interaction) and a3a2dd1 (the WebFinger fix + shared pattern + filter).

1. @notiz.blog@notiz.blog misread as a profile handle — fixed

The detection only had a leading boundary, so it caught the domain half of @user@domain.tld but not a WebFinger handle whose user half is itself domain-shaped (@notiz.blog@notiz.blog) — the leading @notiz.blog was linked and faceted.

Added a trailing (?![\w@]) boundary so a handle immediately followed by @ (or another word char) is rejected. . is deliberately kept out of the trailing class so a handle ending a sentence (@bsky.app.) still matches. While here, I made Facet::MENTION_PATTERN the single source of truth and pointed the display linkifier at it too, so the publish path and the front-end can't drift apart again (the bug existed precisely because they were two separate regexes). Regression tests added on both sides.

2. No existence check — @example.com still gets linked

Worth splitting this into the two paths, because they already behave differently:

• Publishing / notifications: existence is checked. Facet::resolve_mention() runs the real handle-resolution chain and only mints a #mention facet when the handle resolves to a DID. So @example.com never produces a Bluesky mention or notification — it ships as plain text. (Pinned by test_unresolvable_mention_produces_no_facet.)
• Display linkifier: intentionally does no network lookup. A per-render resolution would turn every front-end page view into an outbound DNS/HTTP request to each mentioned domain — a real perf and availability/SSRF-amplification concern (a post mentioning @attacker.example would make every visitor hit that host). So by default we link by syntax and let the appview render an unknown handle gracefully, same as the ActivityPub plugin's display-side linkifier.

To still give a seam for stricter sites, I added an atmosphere_link_mention filter — return false for a handle to leave it as plain text (e.g. gate on a cached existence check or an allowlist) without imposing the lookup cost on everyone by default.

If you'd prefer the plugin itself to gate display links on existence, the non-network way to do it would be to persist the publish-time resolved handle→DID set to post meta and only link handles present there — happy to do that as a follow-up if you think it's worth the coupling.

3. Does it handle the Custom Bluesky text?

Yes — custom text takes precedence, and the interaction is now pinned by tests (commit 4aab0d2):

• When custom text is set, the record text is exactly what the author wrote. The body-mention carry-over is intentionally not applied — injecting a handle the author chose to omit would break the "post exactly what I typed" contract. A body-buried mention isn't even resolved on that path (test_custom_text_does_not_carry_body_only_mention, with an HTTP tripwire).
• A handle the author types into the custom text still works: facet extraction runs on the final record text regardless of which branch composed it, so it produces a #mention facet and notifies (test_custom_text_mention_still_produces_facet).

composer lint and the full PHPUnit suite pass.

[pfefferle]

Review — @handle.tld mention support

Synthesized from three parallel lensed passes (security · correctness · WP-standards/i18n/BC) plus a manual read. Net: solid, well-defended feature; one blocking correctness bug and a consistency fix, then easy to merge.

Correctness — blocking — includes/transformer/class-post.php (~L751)

The } elseif ( '' !== $permalink && $text === $permalink ) branch sets $suffix = $permalink instead of $sep . $permalink. When a handle is carried in, the mention glues to the URL (@handle.tldhttps://…); MENTION_PATTERN's trailing (?![\w@]) then over-extends into a bogus handle, so no #mention facet is emitted — a silent notification loss. Reachable via an empty-title + empty-excerpt post (array_filter at L667 collapses $parts to [$permalink]). Fix: mirror the sibling branch ($suffix = $sep . $permalink) and add a test for that post shape.

Consistency — should fix — class-post.php (~L851)

carry_mentions_into_teaser() uses break on the first overflowing handle (dropping all shorter ones after it); carry_body_mentions() correctly uses continue. The teaser path also lacks the debug_log drop-accounting the link-card path has. Make it continue + log to match.

Robustness (not XSS) — includes/class-mention.php (L29)

PROTECTED_TAGS omits script, noscript, svg, iframe, title, so a @handle inside a <script>/<svg> body gets linkified into <a> and corrupts the element. Not an XSS (output is esc_url/esc_html'd; KSES blocks these tags from non-unfiltered_html users), but worth the one-line array extension.

Minor / hygiene

• mb_strlen vs grapheme_length in both carry methods (class-post.php ~L769/775/799/803/846/851) — safe (never exceeds the 300 cap) but over-truncates prose with emoji and is inconsistent with the rest of the file.
• Missing @since unreleased on Facet::MENTION_PATTERN, Facet::resolve_handles(), and class-mention.php's header/class + the atmosphere_link_mention filter (the release script needs it).
• Facet::is_valid_handle() duplicates Resolver::is_valid_handle() and has drifted (no reserved-TLD check); Resolver re-validates so SSRF stays closed, but prefer calling the canonical copy.
• $resolution_cache caches transient-failure misses, so one network blip can deflate #mention facets across a WP-CLI/cron bulk run — consider caching only successes.
• Tag regex skips hyphenated custom elements; mock_handle_resolution() duplicated across 3 test files; silent 1 MiB the_content guard; no test for the truncate-link carry path.

Verified solid

Output escaping; SSRF gate (wp_safe_remote_get + reserved-TLD rejection + is_valid_handle); no ReDoS (bounded quantifiers + 1 MiB cap); single-source MENTION_PATTERN with correct email/WebFinger boundaries; without_links() try/finally guard; projection + redacted guards keep DNS off the display and editor-preview paths; correct PREG_OFFSET_CAPTURE byte offsets; hit+miss memoization; reflection-based cache reset in tests; the did:web→real-resolution regression test pinned to a real handle.

Risk: MEDIUM (display linkifier runs on the_content site-wide, but read-only and well-guarded). Blocking item is just the separator bug — fix that + the teaser break/continue and this is good to go.

[jeherve]

Thanks for the thorough review. Addressed in 8382ebb:

Blocking — separator bug: The bare-permalink branch in carry_body_mentions() now keeps the \n\n separator ($suffix = $sep . $permalink). Added test_bare_permalink_carries_body_mention_with_separator and confirmed it reproduces the bug — reintroducing the old code fails with the exact @alice.bsky.socialhttp://… symptom, the fix makes it pass. (Hitting that branch needs an empty title and an excerpt that sanitises to empty, so the test uses an HTML-comment body plus a the_content filter that pushes the rendered body onto the link-card path.)

Should fix — teaser consistency: carry_mentions_into_teaser() now uses continue instead of break and emits the same debug_log drop-accounting as the body-mention path.

Robustness: PROTECTED_TAGS extended with script, noscript, svg, iframe, title (with a parametrized test), and the tag regex now matches hyphenated custom elements ([a-z][a-z0-9-]*) so they track correctly on the stack.

Minor / hygiene:

• Both carry methods now count graphemes instead of mb_strlen code points.
• @since unreleased added to Facet::MENTION_PATTERN, Facet::resolve_handles(), the Mention class, and the atmosphere_link_mention filter.
• Facet now calls the canonical Resolver::is_valid_handle(); the drifted local copy (missing the reserved-TLD check) is removed.
• The resolution cache stores successes only, so a transient lookup failure can't deflate #mention facets across a WP-CLI/cron bulk run.

Deliberately left (happy to follow up if you'd like):

• mock_handle_resolution() duplicated across 3 test files — pure test hygiene; left out to keep this diff focused on passing files.
• The silent 1 MiB the_content guard — it runs on every front-end render and mirrors ActivityPub's own silent guard, so logging there risks noise.
• A dedicated test for the short-form truncate-link carry path.

composer lint and the full PHPUnit suite (806 tests) are green.

[pfefferle]

Code review — typed multi-lens pass

Reviewed with three parallel lenses (correctness/fatals, security/escaping, perf-patterns-i18n-compat), each reading whole files. Blocking findings were confirmed against the code and origin/trunk. phpcs passes clean.

🔴 Blocking

1. Uncapped full-body handle resolution — includes/transformer/class-facet.php:395-419 + includes/transformer/class-post.php:721-727
body_mentions() runs Facet::resolve_handles() over the entire untruncated post body (render_post_content_plain()), with no cap on distinct handles. Every unresolvable handle now costs a DNS TXT lookup plus a wp_safe_remote_get( 'https://<handle>/.well-known/atproto-did', timeout 10 ) (class-resolver.php:45-49). An Author-role user can publish a body with thousands of @fake-N.example.com tokens → tens of thousands of seconds of blocking outbound I/O in one atmosphere_publish_post cron run, aimed at attacker-chosen public hosts. Backfill (500 posts/chunk) multiplies it. Every other Facet::extract() caller has an implicit ~300-grapheme bound; this one doesn't. Suggest a hard cap on distinct handles resolved per call (precedent: META_ORPHAN_RECORDS caps at 10).

2. Egress widening onto the lower-trust comment path — includes/transformer/class-facet.php:487-516
On trunk, resolve_mention() did DNS-only then fabricated did:web:<handle> (no HTTP). It now calls Resolver::handle_to_did(), which makes a real HTTPS request. Comment::transform() calls Facet::extract() on commenter-supplied content (class-comment.php:100), so an approved comment containing @target.example.com makes the server issue outbound HTTPS to an arbitrary public host. Bounded by the 300-grapheme comment cap and wp_safe_remote_get (blocks internal hosts) — so public-host egress amplification, not internal SSRF. The docblock at class-facet.php:475-481 names "skip mention resolution on the commenter path" as the fix but doesn't implement it. Gate the HTTP fallback off the comment path, or document as accepted risk.

3. Preview/publish grapheme-count divergence — includes/transformer/class-post.php:721-727, 225-247
body_mentions() returns array() in projection mode (good — no DNS in preview), but the carry-over mutates the composed text (inserts a whole @handle line), unlike facet extraction which only annotates. So project() measures text without the carried line and reports e.g. "120/300" to the pre-publish panel while the real record is longer — and near the cap the real prose can be silently truncated shorter than previewed. This violates the documented invariant ("the grapheme count the preview reports is identical either way", class-post.php:225-229).

4. Self-closed protected tag suppresses linkification — includes/class-mention.php:93-113
The tokenizer detects closing tags only by a leading / after <, not a trailing />. A self-closed protected tag (<iframe … />, <svg/>) is pushed onto $tag_stack and never popped, so every mention after it in the render is silently left as plain text — no error, no log. Verified against real wp_html_split() output.

🟡 Non-blocking

• No cross-request cache (class-facet.php:67). $resolution_cache is per-request static only; publishing is a fresh process per post, so backfill/republish re-resolves the same handle every time. docs/php-coding-standards.md prescribes a transient layer here; Reaction_Sync::resolve_author() is the precedent (HOUR_IN_SECONDS).
• Undocumented behavior change. Dropping the did:web fallback means unresolvable handles now produce no #mention facet (was a dead-link facet). Legitimate fix, but the changelog only mentions the new feature — worth a line so "notifications stopped" reports trace back here.
• resolve_mention() swallows WP_Error silently (class-facet.php:502-505) — route through debug_log() to distinguish "doesn't exist" from "transiently unreachable".
• Display links skip Resolver::is_valid_handle() — the linkifier links reserved TLDs (server.local) the publish path would reject; cosmetic dead-link drift from the "single source of truth" claim.
• Minor: consecutive // comment paragraphs at class-base.php:200-203 and class-facet.php:507-510 (repo convention is /* */ blocks); missing @since on new Mention members and $resolution_cache; carry_body_mentions()/carry_mentions_into_teaser() duplicate a greedy-fit loop; build_text() $available <= 0 path bypasses carry-over without a drop log.

✅ Positives

Escaping is solid (esc_url/esc_html at every call site); the display linkifier does zero network I/O by design; projection correctly skips DNS; MENTION_PATTERN correctly rejects webfinger/email collisions; without_links() uses try/finally restoring prior state; the did:web→real-resolution swap is a real bug fix; success-only caching is well-reasoned. phpcs clean.

---

Risk: HIGH — changes the core publish path for every post (full-body scan + live handle resolution) and adds network egress to both the publish and comment-sync paths.

Findings #1–#4 are concrete; #1 and #2 (egress) are the most important. Happy to draft fixes.

[kraftbj]

Two additional items from a review pass, both inline below. Neither is covered by the existing threads (verified against the prior passes).

[jeherve]

Thanks @pfefferle — all four blocking findings from the HIGH-risk pass are addressed across three commits, each with regression coverage. composer lint and the full PHPUnit suite (833 tests) pass.

1. Uncapped full-body handle resolution → a5530fd
   Facet::resolve_handles() now stops after MAX_RESOLVED_HANDLES (20) distinct handles and logs once when it truncates, so an author can't fan a body of @fake-N.example.com tokens into tens of thousands of DNS/HTTPS lookups. 20 is generous headroom over any post that can fit in 300 graphemes while keeping egress bounded. Test: test_resolve_handles_caps_distinct_lookups (30 handles → 20 lookups).

2. Egress widening onto the comment path → a5530fd
   Facet::extract() gained a $with_mentions flag; Comment::transform() passes false, so commenter-supplied @handle content no longer triggers any DNS/HTTPS resolution (link/hashtag facets still emit — they never touch the network). The resolve_mention() docblock that named this fix now points at the implemented gate. Tests: test_comment_mention_is_not_resolved (tripwire on pre_http_request) and test_extract_without_mentions_skips_resolution.

3. Preview/publish grapheme divergence → 71e4983
   Projection now sizes the carry-over instead of skipping it: in projecting mode body_mentions() returns the syntactic body handles (via Facet::handles_in(), no DNS) as an upper bound, so the reported grapheme count is never shorter than the record the publisher writes. Test: test_projection_accounts_for_carried_body_mention asserts the projected count equals the published record length.

4. Self-closed protected tag suppresses linkification → 2106156
   The tokenizer no longer pushes self-closed tags (<svg/>, <iframe … />) onto the tag stack, so they can't leave a phantom protected tag open for the rest of the render. Test: test_self_closed_protected_tag_does_not_swallow_later_mentions.

On the non-blocking items: the resolve_mention() docblock is updated to reflect the new comment-path gate and the resolve cap; success-only caching stays as-is (deliberate, and now documented alongside the cap). The cross-request transient cache and the "unresolvable handle now yields no facet" changelog note I'd prefer to keep as separate follow-ups rather than fold into these correctness commits — happy to open an issue for them if you'd like.

[pfefferle]

Ran a deep review pass over the mention handling; 10 inline notes below, roughly ordered by severity.

The common thread in several of them (the protected-tag gap, per-chunk linkification, tag-strip gluing, the unquoted-attribute self-close check, and the 1 MB guard) is publish/display parity: the publish path and the front-end linkifier tokenize the content differently, so they disagree about what is a mention. A structural fix — both sides consuming one shared tokenization — would close that class at once, rather than patching case by case.

Three others are deliberate-looking behavior changes vs trunk (dot-mentions no longer matching, comment mention facets removed, the dropped did:web: fallback) that probably each deserve an explicit decision rather than a silent change.

[jeherve]

Addressed all 10 notes across 29654c0 (parity + hardening) and 2b41fb8 (comment-mention filter); replies inline under each.

Took the structural route you suggested: the protected-tag gap, per-chunk linkification, tag-strip gluing, the unquoted-attribute self-close, and the 1 MB guard are all now driven by a single Mention tokenizer — Mention::classify_handles() produces the linkable/protected split that both the display linkifier and Facet::extract() consume, so publish and display can no longer disagree about what is a mention.

The three behaviour-vs-trunk notes each got an explicit decision: dot-mentions restored (regex boundary), comment mentions kept off but now opt-in via atmosphere_resolve_comment_mentions, and the did:web fallback kept off (a guess links to a dead profile for the *.bsky.social majority) but restorable via atmosphere_mention_didweb_fallback.

composer lint clean; full suite green (888 tests).