@agent-native/core 0.176.1 → 0.176.2-nightly-20260831184159

package/corpus/templates/clips/desktop/src-tauri/src/util.rs

@@ -3,6 +3,7 @@ use std::{
     path::{Path, PathBuf},
     process::{Command, Stdio},
     sync::atomic::{AtomicU64, Ordering},
+    time::Duration,
 };
 
 use tauri::{AppHandle, Emitter, Manager, WebviewUrl, WebviewWindow, WebviewWindowBuilder};
@@ -239,9 +240,83 @@ pub fn raise_to_status_level(window: &WebviewWindow) {
     }
 }
 
-#[cfg(not(target_os = "macos"))]
+// Windows has no window-level concept — `always_on_top` sets WS_EX_TOPMOST,
+// a z-order position rather than a level, so another app that calls
+// `SetWindowPos(HWND_TOPMOST)` after ours moves above ours even though both
+// windows are "always on top". Re-issuing `set_always_on_top(true)` re-sends
+// that call and pops the overlay back to the front of the topmost band —
+// the closest Windows equivalent to the NSStatusWindowLevel escape hatch
+// above. Combine with `start_topmost_reassert_loop` below: a single call at
+// show time only wins the race until the next app does the same.
+#[cfg(target_os = "windows")]
+pub fn raise_to_status_level(window: &WebviewWindow) {
+    if let Err(err) = window.set_always_on_top(true) {
+        eprintln!(
+            "[clips-tray] raise_to_status_level({}): set_always_on_top failed: {err}",
+            window.label()
+        );
+    }
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "windows")))]
 pub fn raise_to_status_level(_window: &WebviewWindow) {
-    // No-op on non-macOS platforms. Window levels are an AppKit concept.
+    // No-op on Linux. Window levels/topmost re-assertion aren't a portable
+    // concept across window managers.
+}
+
+#[cfg(any(target_os = "windows", test))]
+fn advance_topmost_generation(current_generation: &AtomicU64) -> u64 {
+    current_generation
+        .fetch_add(1, Ordering::SeqCst)
+        .wrapping_add(1)
+}
+
+#[cfg(any(target_os = "windows", test))]
+fn is_current_topmost_generation(current_generation: &AtomicU64, generation: u64) -> bool {
+    current_generation.load(Ordering::SeqCst) == generation
+}
+
+/// Poll a window every couple of seconds and reassert `raise_to_status_level`
+/// while it's visible. A single call at show time only wins the Windows
+/// z-order race described there until another app raises itself topmost
+/// afterward — e.g. a call app's floating controls appearing mid-recording —
+/// which is exactly how the recording pill/toolbar can end up silently
+/// buried with no taskbar entry to recover it (both windows are
+/// intentionally `skip_taskbar`). Each start advances a caller-owned
+/// generation; an older task exits when superseded, while the new task always
+/// starts. This avoids losing the loop if a window is recreated while the old
+/// task is exiting. No-op on macOS/Linux.
+#[cfg(target_os = "windows")]
+pub fn start_topmost_reassert_loop(
+    app: &AppHandle,
+    label: &'static str,
+    current_generation: &'static AtomicU64,
+) {
+    let generation = advance_topmost_generation(current_generation);
+    let app = app.clone();
+    tauri::async_runtime::spawn(async move {
+        loop {
+            if !is_current_topmost_generation(current_generation, generation) {
+                break;
+            }
+            let Some(window) = app.get_webview_window(label) else {
+                break;
+            };
+            if window.is_visible().unwrap_or(false) {
+                raise_to_status_level(&window);
+            }
+            tokio::time::sleep(Duration::from_secs(2)).await;
+        }
+    });
+}
+
+#[cfg(not(target_os = "windows"))]
+pub fn start_topmost_reassert_loop(
+    _app: &AppHandle,
+    _label: &'static str,
+    _current_generation: &'static AtomicU64,
+) {
+    // No-op on macOS/Linux — see the doc comment on the Windows impl.
 }
 
 #[cfg(not(target_os = "macos"))]
@@ -653,8 +728,11 @@ pub fn hide_voice_wake_popover(app: &AppHandle) {
 
 #[cfg(test)]
 mod tests {
-    use super::bundle_path_from_executable_path;
+    use super::{
+        advance_topmost_generation, bundle_path_from_executable_path, is_current_topmost_generation,
+    };
     use std::path::Path;
+    use std::sync::atomic::AtomicU64;
 
     #[test]
     fn derives_macos_bundle_path_from_app_executable() {
@@ -669,4 +747,20 @@ mod tests {
         let executable = Path::new("/Users/steve/dev/Clips");
         assert!(bundle_path_from_executable_path(executable).is_none());
     }
+
+    #[test]
+    fn replacement_topmost_loop_supersedes_the_exiting_generation() {
+        let current_generation = AtomicU64::new(0);
+        let exiting_generation = advance_topmost_generation(&current_generation);
+        let replacement_generation = advance_topmost_generation(&current_generation);
+
+        assert!(!is_current_topmost_generation(
+            &current_generation,
+            exiting_generation
+        ));
+        assert!(is_current_topmost_generation(
+            &current_generation,
+            replacement_generation
+        ));
+    }
 }

package/corpus/templates/clips/public/manifest.json

@@ -2,7 +2,7 @@
   "name": "Clips",
   "short_name": "Clips",
   "description": "Async video — record your screen, share a link, watch it back.",
-  "start_url": ".",
+  "start_url": "./home",
   "background_color": "#0F0F14",
   "theme_color": "#18181B",
   "icons": [

package/corpus/templates/clips/server/db/schema.ts

@@ -341,6 +341,7 @@ export const recordingComments = table("recording_comments", {
   authorEmail: text("author_email").notNull(),
   authorName: text("author_name"),
   content: text("content").notNull(),
+  mentionsJson: text("mentions_json"),
   videoTimestampMs: integer("video_timestamp_ms").notNull().default(0),
   // JSON map of emoji -> [emails]
   emojiReactionsJson: text("emoji_reactions_json").notNull().default("{}"),

package/corpus/templates/clips/server/lib/activity-notifications.ts

@@ -18,6 +18,7 @@ import { and, eq } from "drizzle-orm";
 
 import { CLIPS_USER_PREFS_KEY } from "../../shared/clips-ai-prefs.js";
 import { getDb, schema } from "../db/index.js";
+import { canReceiveRecordingActivity } from "./recording-page-access.js";
 import { sendClipsTransactionalEmail } from "./transactional-email-templates.js";
 
 /**
@@ -44,6 +45,8 @@ async function getRecording(recordingId: string) {
       title: schema.recordings.title,
       ownerEmail: schema.recordings.ownerEmail,
       orgId: schema.recordings.orgId,
+      password: schema.recordings.password,
+      expiresAt: schema.recordings.expiresAt,
     })
     .from(schema.recordings)
     .where(eq(schema.recordings.id, recordingId))
@@ -73,6 +76,7 @@ export interface RecordingCommentNotificationInput {
   authorEmail: string;
   authorName?: string | null;
   content: string;
+  mentions?: { email: string; name: string }[];
   videoTimestampMs?: number | null;
   isReply?: boolean;
 }
@@ -94,7 +98,11 @@ async function deliverRecordingCommentEmails(
     return RECORDING_MISSING;
   }
 
-  const candidates = [recording.ownerEmail];
+  const mentions = input.mentions ?? [];
+  const mentioned = new Set(
+    mentions.map((mention) => mention.email.trim().toLowerCase()),
+  );
+  const candidates = [recording.ownerEmail, ...mentioned];
   if (input.isReply) {
     candidates.push(
       ...(await threadParticipants(input.recordingId, input.threadId)),
@@ -103,10 +111,18 @@ async function deliverRecordingCommentEmails(
 
   // Thread rows are history, not an access grant: a viewer whose share was
   // revoked must stop receiving the recording's comment bodies.
+  const clipsAllowed = candidates.filter((email) =>
+    canReceiveRecordingActivity({
+      ownerEmail: recording.ownerEmail,
+      recipientEmail: email,
+      hasPassword: Boolean(recording.password),
+      expiresAt: recording.expiresAt,
+    }),
+  );
   const allowed = await filterRecipientsByResourceAccess({
     resourceType: "recording",
     resourceId: recording.id,
-    emails: candidates,
+    emails: clipsAllowed,
     orgId: recording.orgId,
   });
 
@@ -126,6 +142,7 @@ async function deliverRecordingCommentEmails(
         content: input.content,
         videoTimestampMs: input.videoTimestampMs ?? null,
         isReply: input.isReply ?? false,
+        ...(mentioned.has(to) ? { wasMentioned: true } : {}),
       }),
   });
 }
@@ -156,12 +173,20 @@ async function deliverRecordingReactionEmails(
     return RECORDING_MISSING;
   }
 
+  const clipsAllowed = [recording.ownerEmail, ...(input.extraRecipients ?? [])]
+    .filter((email): email is string => Boolean(email))
+    .filter((email) =>
+      canReceiveRecordingActivity({
+        ownerEmail: recording.ownerEmail,
+        recipientEmail: email,
+        hasPassword: Boolean(recording.password),
+        expiresAt: recording.expiresAt,
+      }),
+    );
   const allowed = await filterRecipientsByResourceAccess({
     resourceType: "recording",
     resourceId: recording.id,
-    emails: [recording.ownerEmail, ...(input.extraRecipients ?? [])].filter(
-      (email): email is string => Boolean(email),
-    ),
+    emails: clipsAllowed,
     orgId: recording.orgId,
   });
 

package/corpus/templates/clips/server/lib/comment-mentions.ts

@@ -0,0 +1,23 @@
+import { isOrgMember } from "@agent-native/core/org";
+
+import {
+  normalizeCommentMentions,
+  type CommentMention,
+} from "../../shared/comment-mentions.js";
+
+export async function resolveCommentMentions(
+  value: unknown,
+  organizationId: string,
+): Promise<CommentMention[]> {
+  const mentions = normalizeCommentMentions(value);
+  if (!organizationId || mentions.length === 0) return [];
+
+  const membership = await Promise.all(
+    mentions.map(async (mention) =>
+      (await isOrgMember(organizationId, mention.email)) ? mention : null,
+    ),
+  );
+  return membership.filter(
+    (mention): mention is CommentMention => mention !== null,
+  );
+}

package/corpus/templates/clips/server/lib/emails.ts

@@ -222,9 +222,9 @@ function registerClipsEmailDefinitions(): void {
     name: "Clip comment",
     trigger:
       "Someone comments or replies on a Clip. Subject and copy differ slightly for a reply; both send under this id.",
-    recipientLabel: "Owner and thread authors",
+    recipientLabel: "Owner, mentioned members, and thread authors",
     recipient:
-      "The recording owner, plus every prior author in the thread when the comment is a reply. The list is re-checked against the recording's live ACL and filtered by each user's `emailNotifications` preference; the comment's own author never receives it.",
+      "The recording owner, mentioned organization members, plus every prior author in the thread when the comment is a reply. The list is re-checked against the recording's live ACL and filtered by each user's `emailNotifications` preference; the comment's own author never receives it.",
     senderLabel: "Agent-Native Clips",
     sender: CLIPS_SENDER,
     preview: () =>

package/corpus/templates/clips/server/lib/recording-page-access.ts

@@ -38,3 +38,19 @@ export function canOpenDirectRecordingPage(input: {
   if (input.visibility === "public") return input.hasExplicitShare;
   return true;
 }
+
+/** Comment activity follows the same expiry and password boundary as the player. */
+export function canReceiveRecordingActivity(input: {
+  ownerEmail: string;
+  recipientEmail: string;
+  hasPassword: boolean;
+  expiresAt?: string | null;
+  now?: number;
+}): boolean {
+  if (isRecordingExpired(input.expiresAt, input.now)) return false;
+  if (!input.hasPassword) return true;
+  return (
+    input.ownerEmail.trim().toLowerCase() ===
+    input.recipientEmail.trim().toLowerCase()
+  );
+}

package/corpus/templates/clips/server/lib/transactional-email-templates.ts

@@ -75,6 +75,7 @@ export type ClipsTransactionalEmailInput =
       content: string;
       videoTimestampMs?: number | null;
       isReply?: boolean;
+      wasMentioned?: boolean;
     })
   | (TransactionalEmailBase & {
       kind: "activity-reaction";
@@ -547,17 +548,23 @@ export function renderClipsTransactionalEmail(
         typeof input.videoTimestampMs === "number" && input.videoTimestampMs > 0
           ? ` at ${formatTimestamp(input.videoTimestampMs)}`
           : "";
-      const subject = input.isReply
-        ? `${author} replied on “${title}”`
-        : `${author} commented on “${title}”`;
+      const subject = input.wasMentioned
+        ? `${author} mentioned you on “${title}”`
+        : input.isReply
+          ? `${author} replied on “${title}”`
+          : `${author} commented on “${title}”`;
       const rendered = renderEmail({
         brandName: CLIPS_BRAND_NAME,
         preheader: subject,
-        heading: input.isReply
-          ? `${author} replied on your Clip`
-          : `${author} commented on your Clip`,
+        heading: input.wasMentioned
+          ? `${author} mentioned you on your Clip`
+          : input.isReply
+            ? `${author} replied on your Clip`
+            : `${author} commented on your Clip`,
         paragraphs: [
-          `${emailStrong(author)} left a ${input.isReply ? "reply" : "comment"} on ${emailStrong(title!)}${at}.`,
+          input.wasMentioned
+            ? `${emailStrong(author)} mentioned you in a comment on ${emailStrong(title!)}${at}.`
+            : `${emailStrong(author)} left a ${input.isReply ? "reply" : "comment"} on ${emailStrong(title!)}${at}.`,
           `“${quotedExcerpt(input.content)}”`,
         ],
         cta: {

package/corpus/templates/clips/server/plugins/auth.ts

@@ -8,6 +8,7 @@ export default createAuthPlugin({
   // Keep the native tray token and the Better Auth cookie useful between
   // infrequent recording sessions without making them permanent.
   maxAge: 60 * 60 * 24 * 90,
+  workspaceAppPublicPaths: ["/"],
   // Clips owns `/_agent-native/google/*` so the same registered Google
   // callback can handle both normal sign-in and the Calendar connect flow.
   mountGoogleOAuthRoutes: false,

package/corpus/templates/clips/server/plugins/core-routes.ts

@@ -0,0 +1,5 @@
+import { createCoreRoutesPlugin } from "@agent-native/core/server";
+
+export default createCoreRoutesPlugin({
+  googleOAuthManagedConnection: "required",
+});

package/corpus/templates/clips/server/plugins/db.ts

@@ -1159,6 +1159,11 @@ export const migrations = runMigrations(
       name: "recording-media-updated-at",
       sql: `ALTER TABLE recordings ADD COLUMN IF NOT EXISTS media_updated_at TEXT NOT NULL DEFAULT (datetime('now'))`,
     },
+    {
+      version: 66,
+      name: "recording-comment-mentions",
+      sql: `ALTER TABLE recording_comments ADD COLUMN IF NOT EXISTS mentions_json TEXT`,
+    },
   ],
   { table: "clips_migrations" },
 );

package/corpus/templates/clips/server/routes/api/auth/google-calendar.get.ts

@@ -25,7 +25,6 @@ import {
 import {
   defineEventHandler,
   getQuery,
-  sendRedirect,
   setResponseStatus,
   type H3Event,
 } from "h3";
@@ -106,7 +105,10 @@ export default defineEventHandler(async (event: H3Event) => {
     // this route (popup, direct nav, etc.). Only return JSON when the
     // caller explicitly wants the URL string.
     if (q.json === "1") return { url };
-    return sendRedirect(event, url, 302);
+    return new Response(null, {
+      status: 302,
+      headers: { Location: url },
+    });
   } catch (err: any) {
     setResponseStatus(event, 500);
     return { error: err?.message ?? "Unknown error" };

package/corpus/templates/clips/server/routes/api/clips-latest.json.get.ts

@@ -32,12 +32,12 @@ import {
  *
  *   - A 5-minute process-wide memoization (`cached`) — every request
  *     for 5 min shares one upstream fetch.
- *   - A stale-while-error fallback — if GitHub ever errors out AND we
- *     have a previously-successful payload (even expired), we return
- *     it. Avoids a download outage during a transient GitHub hiccup or
- *     a rate-limit burst.
- *   - HTTP `cache-control: max-age=60` on the response so downstream
- *     CDNs + the browser cache this aggressively.
+ *   - A stale-while-revalidate refresh — once the cache expires, we return the
+ *     previous payload immediately and refresh it in the background.
+ *   - A stale-while-error fallback — if GitHub ever errors out AND we have a
+ *     previously-successful payload (even expired), we keep serving it.
+ *   - Durable HTTP cache headers with short freshness and a long stale window
+ *     for downstream CDNs + the browser.
  */
 
 const RELEASES_URL_BASE =
@@ -47,6 +47,16 @@ const PER_PAGE = 100;
 // by then, something else is wrong and the 404 is correct.
 const MAX_PAGES = 10;
 const CACHE_TTL_MS = 5 * 60_000;
+const CACHE_RETRY_BACKOFF_MS = 60_000;
+
+export const CLIPS_RELEASE_CACHE_HEADERS = {
+  "cache-control":
+    "public, max-age=300, stale-while-revalidate=86400, stale-if-error=86400",
+  "cdn-cache-control":
+    "public, max-age=300, stale-while-revalidate=86400, stale-if-error=86400",
+  "netlify-cdn-cache-control":
+    "public, durable, s-maxage=300, stale-while-revalidate=86400, stale-if-error=86400",
+} as const;
 
 export type ClipsReleaseChannel = "production" | "nightly";
 
@@ -201,6 +211,9 @@ const cache = new Map<
   { data: DownloadManifest; ts: number }
 >();
 const inFlight = new Map<ClipsReleaseChannel, Promise<DownloadManifest>>();
+const retryAfter = new Map<ClipsReleaseChannel, number>();
+
+type WaitUntil = (promise: Promise<unknown>) => void;
 
 class UpstreamError extends Error {
   statusCode: number;
@@ -347,32 +360,70 @@ async function buildManifest(
   };
 }
 
-async function getManifest(
-  channel: ClipsReleaseChannel = "production",
+function refreshManifest(
+  channel: ClipsReleaseChannel,
 ): Promise<DownloadManifest> {
-  const now = Date.now();
-  const cached = cache.get(channel);
-  if (cached && now - cached.ts < CACHE_TTL_MS) return cached.data;
   const pending = inFlight.get(channel);
   if (pending) return pending;
   const request = (async () => {
     try {
       const data = await buildManifest(channel);
       cache.set(channel, { data, ts: Date.now() });
+      retryAfter.delete(channel);
       return data;
-    } catch (err) {
-      // Stale-while-error: if we have an older payload, serve it. Only
-      // bubble the error if the cache is empty.
-      if (cached) return cached.data;
-      throw err;
-    } finally {
-      inFlight.delete(channel);
+    } catch (error) {
+      retryAfter.set(channel, Date.now() + CACHE_RETRY_BACKOFF_MS);
+      throw error;
     }
   })();
-  inFlight.set(channel, request);
-  return request;
+  inFlight.set(
+    channel,
+    request.finally(() => {
+      inFlight.delete(channel);
+    }),
+  );
+  return inFlight.get(channel)!;
+}
+
+function refreshInBackground(
+  channel: ClipsReleaseChannel,
+  waitUntil?: WaitUntil,
+): void {
+  const refresh = refreshManifest(channel).catch(() => undefined);
+  if (waitUntil) {
+    waitUntil(refresh);
+  } else {
+    void refresh;
+  }
 }
 
+async function getManifest(
+  channel: ClipsReleaseChannel = "production",
+  waitUntil?: WaitUntil,
+): Promise<DownloadManifest> {
+  const now = Date.now();
+  const cached = cache.get(channel);
+  if (cached) {
+    if (
+      now - cached.ts >= CACHE_TTL_MS &&
+      now >= (retryAfter.get(channel) ?? 0)
+    ) {
+      refreshInBackground(channel, waitUntil);
+    }
+    return cached.data;
+  }
+  return refreshManifest(channel);
+}
+
+export const __clipsLatestTest = {
+  getManifest,
+  reset() {
+    cache.clear();
+    inFlight.clear();
+    retryAfter.clear();
+  },
+};
+
 export function normalizeClipsReleaseChannel(
   value: unknown,
 ): ClipsReleaseChannel {
@@ -383,7 +434,11 @@ export default defineEventHandler(async (event) => {
   const channel = normalizeClipsReleaseChannel(getQuery(event).channel);
   let manifest: DownloadManifest;
   try {
-    manifest = await getManifest(channel);
+    const waitUntil =
+      typeof event.waitUntil === "function"
+        ? (promise: Promise<unknown>) => event.waitUntil(promise)
+        : undefined;
+    manifest = await getManifest(channel, waitUntil);
   } catch (err) {
     const e = err as {
       statusCode?: number;
@@ -397,7 +452,7 @@ export default defineEventHandler(async (event) => {
   }
   setResponseHeaders(event, {
     "content-type": "application/json; charset=utf-8",
-    "cache-control": "public, max-age=60",
+    ...CLIPS_RELEASE_CACHE_HEADERS,
   });
   return manifest;
 });

package/corpus/templates/clips/server/routes/api/public-recording.get.ts

@@ -36,6 +36,7 @@ import {
   buildAgentApiUrls,
   CLIP_AGENT_ACCESS_TOKEN_PREFIX,
 } from "../../../shared/agent-context.js";
+import { displayCommentMentions } from "../../../shared/comment-mentions.js";
 import {
   normalizeTranscriptSegments,
   parseTranscriptSegments,
@@ -331,6 +332,15 @@ export default defineEventHandler(async (event) => {
         )
     : [];
   const hydratedComments = await hydrateCommentAuthorNames(comments);
+  const commentMentions = new Map(
+    hydratedComments.map((comment) => [
+      comment.id,
+      displayCommentMentions(comment.mentionsJson),
+    ]),
+  );
+  for (const comment of hydratedComments) {
+    Reflect.deleteProperty(comment, "mentionsJson");
+  }
 
   const reactions = rec.enableReactions
     ? await db
@@ -519,6 +529,7 @@ export default defineEventHandler(async (event) => {
       authorEmail: c.authorEmail,
       authorName: c.authorName,
       content: c.content,
+      mentions: commentMentions.get(c.id) ?? [],
       videoTimestampMs: c.videoTimestampMs,
       emojiReactionsJson: c.emojiReactionsJson,
       resolved: Boolean(c.resolved),

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/interrupt.post.ts

@@ -24,15 +24,15 @@ import {
 } from "h3";
 
 import { UPLOAD_RETRY_RESUME_FLAG } from "../../../../../shared/feature-flags.js";
+import {
+  isRetryableUploadInterruption,
+  retryableUploadInterruptionReason,
+} from "../../../../../shared/upload-interruption.js";
 import { getDb, schema } from "../../../../db/index.js";
 import {
   getEventOwnerContext,
   ownerEmailMatches,
 } from "../../../../lib/recordings.js";
-import {
-  isRetryableUploadInterruption,
-  retryableUploadInterruptionReason,
-} from "../../../../lib/upload-interruption.js";
 import abortUpload from "./abort.post.js";
 
 export default defineEventHandler(async (event: H3Event) => {

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/resume.get.ts

@@ -32,6 +32,7 @@ import {
 } from "h3";
 
 import { UPLOAD_RETRY_RESUME_FLAG } from "../../../../../shared/feature-flags.js";
+import { isRetryableUploadInterruption } from "../../../../../shared/upload-interruption.js";
 import { getDb, schema } from "../../../../db/index.js";
 import {
   listRecordingChunkKeys,
@@ -47,7 +48,6 @@ import {
   getResumableSession,
 } from "../../../../lib/resumable-session.js";
 import { abortResumableUploadSession } from "../../../../lib/resumable-upload-cleanup.js";
-import { isRetryableUploadInterruption } from "../../../../lib/upload-interruption.js";
 import {
   UPLOAD_LEASE_MS,
   uploadLeaseExpiry,

package/corpus/templates/clips/shared/comment-mentions.ts

@@ -0,0 +1,71 @@
+export interface CommentMention {
+  email: string;
+  name: string;
+}
+
+export interface CommentMentionDisplay {
+  name: string;
+}
+
+export function normalizeCommentMentions(value: unknown): CommentMention[] {
+  let raw = value;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed) return [];
+    try {
+      raw = JSON.parse(trimmed);
+    } catch {
+      // coercion-ok: malformed optional mention metadata is treated as absent.
+      return [];
+    }
+  }
+  if (!Array.isArray(raw)) return [];
+
+  const seen = new Set<string>();
+  const mentions: CommentMention[] = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const candidate = entry as Record<string, unknown>;
+    const email =
+      typeof candidate.email === "string"
+        ? candidate.email.trim().toLowerCase()
+        : "";
+    if (!email || !email.includes("@") || seen.has(email)) continue;
+    const name =
+      typeof candidate.name === "string" ? candidate.name.trim() : "";
+    seen.add(email);
+    mentions.push({
+      email,
+      name: name || email.split("@")[0] || email,
+    });
+  }
+  return mentions;
+}
+
+export function parseCommentMentions(
+  value: string | null | undefined,
+): CommentMention[] {
+  return normalizeCommentMentions(value);
+}
+
+export function displayCommentMentions(
+  value: unknown,
+): CommentMentionDisplay[] {
+  return normalizeCommentMentions(value).map(({ name }) => ({ name }));
+}
+
+function hasMentionToken(text: string, name: string): boolean {
+  const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|\\s)@${escapedName}(?=$|[^\\p{L}\\p{N}_])`, "u").test(
+    text,
+  );
+}
+
+export function mentionsForCommentText(
+  text: string,
+  mentions: readonly CommentMention[],
+): CommentMention[] {
+  return normalizeCommentMentions(
+    mentions.filter((mention) => hasMentionToken(text, mention.name)),
+  );
+}