texlite 0.8.3 → 0.9.0

package/dist/server/app.js

@@ -16,6 +16,9 @@ import { ProjectMutationCoordinator } from "./projectMutations.js";
 import { ProjectGitService } from "./git.js";
 import { LatexCompletionService } from "./latexCompletion.js";
 import { ProjectHistoryService } from "./history.js";
+import { ProjectEditHistoryService } from "./editHistory.js";
+import { HistoryRetentionScheduler } from "./historyRetention.js";
+import { EditHistoryRetry } from "./editHistoryRetry.js";
 import { ProjectOutlineService } from "./projectOutline.js";
 import { MetricRegistry } from "./metrics.js";
 import { apiError, HttpError } from "./http.js";
@@ -49,6 +52,10 @@ export async function buildApp(config, db, options = {}) {
     const eventLoopDelay = monitorEventLoopDelay({ resolution: 20 });
     eventLoopDelay.enable();
     const history = new ProjectHistoryService(config, db);
+    const editHistory = new ProjectEditHistoryService(db, config.editHistoryMaxStorageBytes);
+    const historyRetention = new HistoryRetentionScheduler(history, {
+        onError: (error, projectId) => app.log.error({ err: error, projectId }, "Failed to enforce project history retention")
+    });
     const latexCompletions = new LatexCompletionService(config);
     const projectOutlines = new ProjectOutlineService(config);
     const harper = new HarperService();
@@ -56,18 +63,47 @@ export async function buildApp(config, db, options = {}) {
     // Probe the optional host Harper CLI without delaying startup. Its absence is
     // supported: the browser spellchecker remains the writing-check fallback.
     void harper.preload().catch((error) => app.log.info({ err: error }, "Optional Harper CLI is unavailable"));
+    const failedSnapshots = new Set();
+    const failedEdits = new Map();
+    const signalHistory = (id) => collaboration.setHistoryWarning(id, failedSnapshots.has(id) || failedEdits.has(id));
+    const editRetry = new EditHistoryRetry((id, edits) => editHistory.record(id, edits), (id) => Boolean(db.prepare("SELECT 1 FROM projects WHERE id = ?").get(id)), (id, state, error) => {
+        if (state === "discarded") {
+            failedEdits.delete(id);
+            failedSnapshots.delete(id);
+            signalHistory(id);
+            return;
+        }
+        if (failedEdits.get(id) !== "incomplete") {
+            if (state === "ok")
+                failedEdits.delete(id);
+            else
+                failedEdits.set(id, state);
+        }
+        if (error)
+            app.log.error({ err: error, projectId: id }, "Failed to record project edit history");
+        signalHistory(id);
+    });
     const recordHistory = (projectId, userId, reason, paths) => {
         try {
-            return history.record(projectId, userId, reason, paths);
+            const version = history.record(projectId, userId, reason, failedSnapshots.has(projectId) ? undefined : paths, { deferRetention: reason === "autosave" });
+            if (failedSnapshots.delete(projectId))
+                signalHistory(projectId);
+            if (version && reason === "autosave")
+                historyRetention.schedule(projectId);
+            return version;
         }
         catch (error) {
+            failedSnapshots.add(projectId);
+            signalHistory(projectId);
             app.log.error({ err: error, projectId }, "Failed to record project history");
             return null;
         }
     };
-    const collaboration = new CollaborationService(config, db, ({ projectId, userId, paths, durationMs }) => {
-        metrics.record("collaboration.persist", durationMs);
+    const collaboration = new CollaborationService(config, db, ({ projectId, userId, paths, edits, durationMs }) => {
+        const started = performance.now();
+        editRetry.save(projectId, edits);
         recordHistory(projectId, userId, "autosave", paths);
+        metrics.record("collaboration.persist", durationMs + performance.now() - started);
     });
     const projectMutations = new ProjectMutationCoordinator(collaboration);
     const projectGit = new ProjectGitService(config, db, options.githubFetch);
@@ -103,11 +139,14 @@ export async function buildApp(config, db, options = {}) {
     await pruneTrashDirectory(config);
     for (const row of db.prepare("SELECT id FROM projects").all()) {
         history.enforceRetention(row.id);
+        editHistory.enforceRetention(row.id);
         pruneCompileRuns(row.id);
         pruneOrphanedCompileRuns(config, row.id);
     }
     app.addHook("onClose", async () => {
         eventLoopDelay.disable();
+        historyRetention.dispose();
+        editRetry.dispose();
         await harper.dispose();
         await texcount.dispose();
     });
@@ -187,7 +226,9 @@ export async function buildApp(config, db, options = {}) {
         metrics,
         recordHistory
     });
-    registerProjectHistoryRoutes(app, { config, db, history, projectMutations, recordHistory });
+    registerProjectHistoryRoutes(app, { config, db, history, editHistory, projectMutations, recordHistory,
+        clearPendingEdits: (id) => { editRetry.clear(id); failedEdits.delete(id); signalHistory(id); },
+        scheduleHistoryRetention: (id) => historyRetention.schedule(id) });
     registerProjectGitRoutes(app, { config, db, collaboration, projectMutations, projectGit, recordHistory });
     registerProjectCatalogRoutes(app, {
         config,

package/dist/server/cli.js

@@ -117,6 +117,9 @@ function writeInitialConfig(configPath, siteName, adminEmail) {
             maxVersions: CONFIG_DEFAULTS.historyMaxVersions,
             maxStorageMB: CONFIG_DEFAULTS.historyMaxStorageMB
         },
+        editHistory: {
+            maxStorageMB: CONFIG_DEFAULTS.editHistoryMaxStorageMB
+        },
         git: {
             binary: CONFIG_DEFAULTS.git,
             operationTimeoutSeconds: CONFIG_DEFAULTS.gitOperationTimeoutSeconds,
@@ -289,6 +292,7 @@ async function printConfig(options) {
         pdfRangeThresholdMB: config.pdfRangeThresholdBytes / (1024 * 1024),
         historyMaxVersions: config.historyMaxVersions,
         historyMaxStorageBytes: config.historyMaxStorageBytes,
+        editHistoryMaxStorageBytes: config.editHistoryMaxStorageBytes,
         git: config.git
     }, null, 2));
 }

package/dist/server/collaboration.js

@@ -9,8 +9,9 @@ import * as decoding from "lib0/decoding";
 import * as syncProtocol from "y-protocols/sync";
 import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, modifyAwarenessUpdate, removeAwarenessStates } from "y-protocols/awareness";
 import { listProjectFilesAsync, outputRoot, resolveSourcePath, safeRelativePath, sourceRoot } from "./files.js";
-import { accessibleProject, canEdit } from "./projects.js";
+import { collaborationProjectAccessFromStatement, canEdit, prepareCollaborationProjectAccessStatement } from "./projects.js";
 import { reanchorFileComments } from "./anchors.js";
+import { hashText } from "./editHistory.js";
 const MESSAGE_SYNC = 0;
 const MESSAGE_AWARENESS = 1;
 const MESSAGE_QUERY_AWARENESS = 3;
@@ -43,11 +44,17 @@ const STATE_SAVE_DELAY_MS = 750;
 const ROOM_IDLE_MS = 30_000;
 const FORMAT_LEASE_TTL_MS = 45_000;
 const MAX_FORMAT_LEASE_WAITERS = MAX_PROJECT_SESSIONS * 2;
+// A normal typing burst produces a few small Yjs updates. Keep adjacent
+// updates from the same user together without ever merging across another
+// collaborator's edit, so the resulting record remains attributable.
+const EDIT_SEGMENT_IDLE_MS = 30_000;
+const MAX_EDIT_SPANS_PER_STEP = 96;
+const MAX_EDIT_PREVIEW_CHARS = 1_200;
 // Completion notifications are useful only to browsers that were already
 // present when the operation finished. The database and retained manifests
 // are the authority for a later workspace open.
 const COMPLETED_COMPILE_STATE_TTL_MS = 60_000;
-const EPHEMERAL_META_KEYS = ["compileStates", "filesEvent", "commentsRevision", "dictionaryRevision"];
+const EPHEMERAL_META_KEYS = ["compileStates", "filesEvent", "commentsRevision", "dictionaryRevision", "historyWarning"];
 const COLORS = [
     ["#1677c8", "#1677c833"], ["#d65745", "#d6574533"], ["#16866a", "#16866a33"],
     ["#9a58b5", "#9a58b533"], ["#d27b18", "#d27b1833"], ["#3f7d20", "#3f7d2033"],
@@ -64,18 +71,27 @@ export class CollaborationService {
     projectGenerations = new Map();
     snapshotBarriers = new Map();
     pendingConnections = new Map();
+    /** Transient server-side status, restored into each newly opened room. */
+    historyWarnings = new Set();
     closed = false;
+    userByIdStatement;
+    collaborationProjectAccessStatement;
     constructor(config, db, onPersist) {
         this.config = config;
         this.db = db;
         this.onPersist = onPersist;
+        this.userByIdStatement = db.prepare("SELECT * FROM users WHERE id = ?");
+        this.collaborationProjectAccessStatement = prepareCollaborationProjectAccessStatement(db);
+    }
+    lookupProjectAccess(projectId, user) {
+        return collaborationProjectAccessFromStatement(this.collaborationProjectAccessStatement, projectId, user);
     }
     async connect(socket, projectId, user) {
         if (this.closed) {
             socket.close(1012, "Collaboration service is shutting down");
             return;
         }
-        const project = accessibleProject(this.db, projectId, user);
+        const project = this.lookupProjectAccess(projectId, user);
         if (!project) {
             socket.close(1008, "Project access denied");
             return;
@@ -390,6 +406,16 @@ export class CollaborationService {
         const filePath = filePathInput ? safeRelativePath(filePathInput) : "";
         this.bumpFiles(room, { kind: "update", path: filePath });
     }
+    setHistoryWarning(projectId, warning) {
+        if (warning)
+            this.historyWarnings.add(projectId);
+        else
+            this.historyWarnings.delete(projectId);
+        const room = this.rooms.get(projectId);
+        if (!room || room.meta.get("historyWarning") === warning)
+            return;
+        room.doc.transact(() => room.meta.set("historyWarning", warning), META_ORIGIN);
+    }
     signalComments(projectId) {
         const room = this.rooms.get(projectId);
         if (!room)
@@ -558,6 +584,7 @@ export class CollaborationService {
         this.roomInitializations.clear();
         this.snapshotBarriers.clear();
         this.pendingConnections.clear();
+        this.historyWarnings.clear();
     }
     initializeRoom(projectId, generation) {
         const existing = this.rooms.get(projectId);
@@ -677,7 +704,9 @@ export class CollaborationService {
             awarenessOwners: new Map(),
             allowedPaths: new Set(),
             persistedContent: new Map(),
+            observedContent: new Map(),
             dirtyPaths: new Set(),
+            pendingEditSegments: [],
             textObservers: new Map(),
             saveTimer: null,
             stateSaveTimer: null,
@@ -700,6 +729,12 @@ export class CollaborationService {
         // longer exists. The database/source tree are authoritative after a
         // restart; clear the markers before any browser can sync them back.
         const recoveredMetadataChanged = bootstrap.recoveredState && this.clearRecoveredMetadata(room);
+        // History bookkeeping is not stored in a project Yjs document, but a
+        // temporary failure must remain visible if its room was idled out before
+        // the editor reconnects.
+        if (this.historyWarnings.has(projectId)) {
+            room.doc.transact(() => room.meta.set("historyWarning", true), META_ORIGIN);
+        }
         this.sanitizeCompileStates(room);
         let recoveredDirty = false;
         const diskPaths = new Set();
@@ -720,13 +755,17 @@ export class CollaborationService {
                 else {
                     replaceText(text, file.content);
                 }
+                room.observedContent.set(file.path, text.toString());
             }
             for (const name of room.doc.share.keys()) {
                 if (!name.startsWith(SOURCE_PREFIX))
                     continue;
                 const filePath = name.slice(SOURCE_PREFIX.length);
-                if (!diskPaths.has(filePath))
-                    replaceText(room.doc.getText(name), "");
+                if (!diskPaths.has(filePath)) {
+                    const text = room.doc.getText(name);
+                    replaceText(text, "");
+                    room.observedContent.set(filePath, text.toString());
+                }
             }
         }, DISK_ORIGIN);
         const rejectedRecoveredPaths = this.rejectOversizedTexts(room);
@@ -790,7 +829,7 @@ export class CollaborationService {
     attachConnection(room, socket, user) {
         if (socket.readyState !== WebSocket.OPEN)
             return;
-        if (!accessibleProject(this.db, room.projectId, user)) {
+        if (!this.lookupProjectAccess(room.projectId, user)) {
             socket.close(1008, "Project access denied");
             return;
         }
@@ -832,9 +871,17 @@ export class CollaborationService {
         const text = room.doc.getText(typeName(filePath));
         if (room.textObservers.has(filePath))
             return text;
-        const observer = (_event, transaction) => {
-            if (transaction.origin === DISK_ORIGIN || transaction.origin === HTTP_ORIGIN || transaction.origin === META_ORIGIN)
+        const observer = (event, transaction) => {
+            const before = room.observedContent.get(filePath) ?? text.toString();
+            const after = text.toString();
+            if (transaction.origin === DISK_ORIGIN || transaction.origin === HTTP_ORIGIN || transaction.origin === META_ORIGIN) {
+                // Non-collaborative mutations deliberately reset the source chain.
+                // They are represented by recovery snapshots, not by a guessed user
+                // edit record; keeping this mirror current prevents later edits from
+                // being mapped across such a replacement.
+                room.observedContent.set(filePath, after);
                 return;
+            }
             if (!room.allowedPaths.has(filePath)) {
                 // A client can still have the old Y.Text bound briefly after another
                 // session deletes or moves a file. Correct any late update immediately;
@@ -843,21 +890,69 @@ export class CollaborationService {
                 room.doc.transact(() => replaceText(text, ""), DISK_ORIGIN);
                 return;
             }
+            if (isConnectionOrigin(transaction.origin) && before !== after) {
+                const connection = transaction.origin;
+                this.recordEditStep(room, filePath, connection, event, before, after);
+            }
+            room.observedContent.set(filePath, after);
             room.dirtyPaths.add(filePath);
         };
         text.observe(observer);
         room.textObservers.set(filePath, observer);
         return text;
     }
+    /**
+     * Keep live collaborative changes in short, author-isolated segments. The
+     * segment is only handed to the history service after `flushRoom()` has
+     * made the matching source content durable.
+     */
+    recordEditStep(room, filePath, connection, event, before, after) {
+        const spans = editSpansFromYDelta(event.delta, before, after);
+        if (!spans.length)
+            return;
+        const createdAt = new Date().toISOString();
+        const activeLease = this.activeFormatLease(room, filePath);
+        const kind = activeLease?.connection === connection ? "format" : "edit";
+        const step = {
+            beforeHash: hashText(before),
+            afterHash: hashText(after),
+            createdAt,
+            spans
+        };
+        const previous = room.pendingEditSegments.at(-1);
+        const previousTime = previous ? Date.parse(previous.updatedAt) : Number.NaN;
+        if (previous
+            && previous.filePath === filePath
+            && previous.authorId === connection.user.id
+            && previous.kind === kind
+            && previous.afterHash === step.beforeHash
+            && Number.isFinite(previousTime)
+            && Date.parse(createdAt) - previousTime <= EDIT_SEGMENT_IDLE_MS) {
+            previous.steps.push(step);
+            previous.afterHash = step.afterHash;
+            previous.updatedAt = createdAt;
+            return;
+        }
+        room.pendingEditSegments.push({
+            filePath,
+            authorId: connection.user.id,
+            kind,
+            beforeHash: step.beforeHash,
+            afterHash: step.afterHash,
+            createdAt,
+            updatedAt: createdAt,
+            steps: [step]
+        });
+    }
     handleMessage(room, connection, bytes) {
-        const refreshedUser = this.db.prepare("SELECT * FROM users WHERE id = ?").get(connection.user.id);
+        const refreshedUser = this.userByIdStatement.get(connection.user.id);
         if (!refreshedUser || refreshedUser.disabled) {
             connection.socket.close(1008, "Project access revoked");
             this.disconnect(room, connection);
             return;
         }
         connection.user = refreshedUser;
-        const current = accessibleProject(this.db, room.projectId, refreshedUser);
+        const current = this.lookupProjectAccess(room.projectId, refreshedUser);
         if (!current) {
             connection.socket.close(1008, "Project access revoked");
             return;
@@ -1280,21 +1375,24 @@ export class CollaborationService {
         if (room.saveTimer)
             clearTimeout(room.saveTimer);
         room.saveTimer = null;
-        this.rejectOversizedTexts(room);
+        const rejectedDuringFlush = this.rejectOversizedTexts(room);
         this.persistRoomState(room);
         let changed = false;
         const changedPaths = [];
         const failedPaths = [...room.rejectedPaths];
+        const finalizedPaths = new Set(rejectedDuringFlush);
         const dirtyPaths = [...room.dirtyPaths];
         for (const filePath of dirtyPaths) {
             if (!room.allowedPaths.has(filePath)) {
                 room.dirtyPaths.delete(filePath);
+                finalizedPaths.add(filePath);
                 continue;
             }
             const next = this.trackedText(room, filePath).toString();
             const previous = room.persistedContent.get(filePath) ?? "";
             if (next === previous) {
                 room.dirtyPaths.delete(filePath);
+                finalizedPaths.add(filePath);
                 continue;
             }
             if (Buffer.byteLength(next, "utf8") > maxCollaborativeFileBytes(this.config)) {
@@ -1321,6 +1419,7 @@ export class CollaborationService {
             }
             room.persistedContent.set(filePath, next);
             room.dirtyPaths.delete(filePath);
+            finalizedPaths.add(filePath);
             try {
                 reanchorFileComments(this.db, room.projectId, filePath, previous, next);
             }
@@ -1328,6 +1427,13 @@ export class CollaborationService {
             changed = true;
             changedPaths.push(filePath);
         }
+        const persistedPaths = new Set(changedPaths);
+        const edits = room.pendingEditSegments.filter((segment) => persistedPaths.has(segment.filePath));
+        // A reverted edit or rejected oversized file did not produce a durable
+        // source revision, so it must not become a misleading edit-history row.
+        if (finalizedPaths.size > 0) {
+            room.pendingEditSegments = room.pendingEditSegments.filter((segment) => !finalizedPaths.has(segment.filePath));
+        }
         if (changed && room.lastModifiedUserId) {
             this.db.prepare("UPDATE projects SET updated_at = ?, last_modified_by = ? WHERE id = ?")
                 .run(new Date().toISOString(), room.lastModifiedUserId, room.projectId);
@@ -1336,7 +1442,7 @@ export class CollaborationService {
             this.signalComments(room.projectId);
         if (changed && this.onPersist) {
             try {
-                this.onPersist({ projectId: room.projectId, userId: room.lastModifiedUserId, paths: changedPaths, durationMs: performance.now() - startedAt });
+                this.onPersist({ projectId: room.projectId, userId: room.lastModifiedUserId, paths: changedPaths, edits, durationMs: performance.now() - startedAt });
             }
             catch { /* Source durability must not depend on optional history bookkeeping. */ }
         }
@@ -1513,6 +1619,119 @@ function replaceText(text, content) {
     if (content)
         text.insert(0, content);
 }
+/**
+ * Turn Y.Text's transaction delta into compact positional spans. We retain
+ * lengths for exact range mapping, while previews keep a pasted/formatter
+ * change from turning the edit-history database into a second source store.
+ */
+function editSpansFromYDelta(delta, before, after) {
+    if (before === after)
+        return [];
+    let beforeOffset = 0;
+    let afterOffset = 0;
+    let invalid = false;
+    const spans = [];
+    let pending = null;
+    const flushPending = () => {
+        if (!pending)
+            return;
+        const deletedLength = pending.deleted.length;
+        const insertedLength = pending.inserted.length;
+        if (deletedLength || insertedLength) {
+            spans.push(editSpan(pending.beforeStart, pending.beforeStart + deletedLength, pending.afterStart, pending.afterStart + insertedLength, pending.deleted, pending.inserted));
+        }
+        pending = null;
+    };
+    const startPending = () => {
+        if (!pending)
+            pending = { beforeStart: beforeOffset, afterStart: afterOffset, deleted: "", inserted: "" };
+        return pending;
+    };
+    for (const raw of delta) {
+        if (!raw || typeof raw !== "object") {
+            invalid = true;
+            break;
+        }
+        const operation = raw;
+        if (typeof operation.retain === "number" && Number.isInteger(operation.retain) && operation.retain >= 0) {
+            flushPending();
+            beforeOffset += operation.retain;
+            afterOffset += operation.retain;
+            continue;
+        }
+        if (typeof operation.delete === "number" && Number.isInteger(operation.delete) && operation.delete >= 0) {
+            const length = operation.delete;
+            if (beforeOffset + length > before.length) {
+                invalid = true;
+                break;
+            }
+            startPending().deleted += before.slice(beforeOffset, beforeOffset + length);
+            beforeOffset += length;
+            continue;
+        }
+        if (typeof operation.insert === "string") {
+            startPending().inserted += operation.insert;
+            afterOffset += operation.insert.length;
+            continue;
+        }
+        invalid = true;
+        break;
+    }
+    flushPending();
+    // Yjs normally emits retains for all unchanged text. Be defensive about
+    // omitted trailing retains, then reject anything whose coordinate model does
+    // not reconstruct the actual strings.
+    const beforeRemaining = before.length - beforeOffset;
+    const afterRemaining = after.length - afterOffset;
+    if (beforeRemaining === afterRemaining && beforeRemaining >= 0) {
+        beforeOffset = before.length;
+        afterOffset = after.length;
+    }
+    if (invalid || beforeOffset !== before.length || afterOffset !== after.length || spans.length > MAX_EDIT_SPANS_PER_STEP) {
+        return [wholeDocumentEditSpan(before, after)];
+    }
+    return spans.length ? spans : [wholeDocumentEditSpan(before, after)];
+}
+function wholeDocumentEditSpan(before, after) {
+    const prefix = commonPrefixLength(before, after);
+    const suffix = commonSuffixLength(before, after, prefix);
+    return editSpan(prefix, before.length - suffix, prefix, after.length - suffix, before.slice(prefix, before.length - suffix), after.slice(prefix, after.length - suffix));
+}
+function editSpan(beforeStart, beforeEnd, afterStart, afterEnd, deleted, inserted) {
+    const deletedPreview = previewEditText(deleted);
+    const insertedPreview = previewEditText(inserted);
+    return {
+        beforeStart,
+        beforeEnd,
+        afterStart,
+        afterEnd,
+        deletedLength: deleted.length,
+        insertedLength: inserted.length,
+        deletedPreview,
+        insertedPreview,
+        truncated: deletedPreview.length < deleted.length || insertedPreview.length < inserted.length
+    };
+}
+function previewEditText(value) {
+    if (value.length <= MAX_EDIT_PREVIEW_CHARS)
+        return value;
+    const edge = Math.floor((MAX_EDIT_PREVIEW_CHARS - 1) / 2);
+    return `${value.slice(0, edge)}…${value.slice(value.length - edge)}`;
+}
+function commonPrefixLength(left, right) {
+    const max = Math.min(left.length, right.length);
+    let index = 0;
+    while (index < max && left.charCodeAt(index) === right.charCodeAt(index))
+        index += 1;
+    return index;
+}
+function commonSuffixLength(left, right, prefixLength) {
+    const max = Math.min(left.length, right.length) - prefixLength;
+    let index = 0;
+    while (index < max && left.charCodeAt(left.length - 1 - index) === right.charCodeAt(right.length - 1 - index))
+        index += 1;
+    return index;
+}
 function syncUpdateMessage(update) {
     const encoder = encoding.createEncoder();
     encoding.writeVarUint(encoder, MESSAGE_SYNC);

package/dist/server/commentMentions.js

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+/**
+ * List active users who can access a project.  The owner is included even
+ * though they have no project_members row.  Callers can exclude the author
+ * when presenting a mention picker.
+ */
+export function mentionableUsersForProject(db, projectId, excludeUserId) {
+    const exclusion = excludeUserId ? "AND user.id <> ?" : "";
+    const parameters = excludeUserId ? [projectId, excludeUserId] : [projectId];
+    const rows = db.prepare(`SELECT DISTINCT user.id, user.username, user.display_name
+    FROM users user
+    JOIN projects project ON project.id = ?
+    LEFT JOIN project_members member ON member.project_id = project.id AND member.user_id = user.id
+    WHERE user.disabled = 0
+      AND (user.id = project.owner_id OR member.user_id IS NOT NULL)
+      ${exclusion}
+    ORDER BY user.display_name COLLATE NOCASE, user.username COLLATE NOCASE`)
+        .all(...parameters);
+    return rows.map((user) => ({ id: user.id, username: user.username, displayName: user.display_name }));
+}
+/**
+ * Extract mention tokens without taking ownership of ordinary `@` text.
+ * The surrounding-character rule intentionally excludes e-mail addresses;
+ * the candidate lookup below then makes a token a mention only when it is an
+ * exact, currently accessible username.
+ */
+export function mentionedUsernames(content, candidates) {
+    const available = new Map(candidates.map((candidate) => [candidate.username.toLocaleLowerCase(), candidate.username]));
+    const usernames = new Set();
+    const pattern = /(^|[^\p{L}\p{N}_.-])@([\p{L}\p{N}_.-]+)/gu;
+    for (const match of content.matchAll(pattern)) {
+        let token = match[2];
+        let username = available.get(token.toLocaleLowerCase());
+        // A sentence-ending period or comma is not part of the mention, even
+        // though a username itself is allowed to contain dots and hyphens.
+        while (!username && /[.,;:!?)}\]\u201d\u2019]$/u.test(token)) {
+            token = token.slice(0, -1);
+            username = available.get(token.toLocaleLowerCase());
+        }
+        if (username)
+            usernames.add(username);
+    }
+    return [...usernames];
+}
+/** Persist first-class notifications for exact mentions in one comment item. */
+export function createCommentMentions(db, input) {
+    const candidates = mentionableUsersForProject(db, input.projectId);
+    const previousUsernames = new Set(input.previousContent ? mentionedUsernames(input.previousContent, candidates) : []);
+    const recipients = mentionedUsernames(input.content, candidates)
+        .map((username) => candidates.find((candidate) => candidate.username === username))
+        .filter((candidate) => Boolean(candidate && candidate.id !== input.authorId && !previousUsernames.has(candidate.username)));
+    if (!recipients.length)
+        return;
+    const insert = db.prepare(`INSERT INTO comment_mentions
+    (id, project_id, comment_id, reply_id, mentioned_user_id, mentioned_by_user_id, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT DO UPDATE SET
+      mentioned_by_user_id = excluded.mentioned_by_user_id,
+      created_at = excluded.created_at,
+      read_at = NULL,
+      read_reason = NULL`);
+    for (const recipient of recipients) {
+        insert.run(randomUUID(), input.projectId, input.commentId, input.replyId ?? null, recipient.id, input.authorId, input.createdAt);
+    }
+}
+/** Return unread mention counts scoped to one receiving user. */
+export function unreadMentionCountsForProjects(db, projectIds, userId) {
+    const counts = new Map();
+    for (let offset = 0; offset < projectIds.length; offset += 200) {
+        const chunk = projectIds.slice(offset, offset + 200);
+        const placeholders = chunk.map(() => "?").join(", ");
+        const rows = db.prepare(`SELECT project_id, COUNT(*) AS count
+      FROM comment_mentions
+      WHERE mentioned_user_id = ? AND read_at IS NULL AND project_id IN (${placeholders})
+      GROUP BY project_id`).all(userId, ...chunk);
+        for (const row of rows)
+            counts.set(row.project_id, Number(row.count) || 0);
+    }
+    return counts;
+}
+function mentionFromRow(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        commentId: row.comment_id,
+        replyId: row.reply_id,
+        filePath: row.file_path,
+        content: row.reply_id ? row.reply_content ?? "" : row.comment_content,
+        resolved: Boolean(row.resolved),
+        createdAt: row.created_at,
+        readAt: row.read_at,
+        readReason: row.read_reason
+    };
+}
+const mentionSelect = `SELECT mention.id, mention.project_id, mention.comment_id, mention.reply_id,
+  comment.file_path, comment.content AS comment_content, reply.content AS reply_content,
+  comment.resolved, mention.created_at, mention.read_at, mention.read_reason
+  FROM comment_mentions mention
+  JOIN comments comment ON comment.id = mention.comment_id
+  LEFT JOIN comment_replies reply ON reply.id = mention.reply_id`;
+export function listCommentMentions(db, projectId, userId, options = {}) {
+    const limit = Math.min(100, Math.max(1, options.limit ?? 50));
+    const unreadClause = options.unreadOnly ? "AND mention.read_at IS NULL" : "";
+    const fileClause = options.filePath ? "AND comment.file_path = ?" : "";
+    const parameters = options.filePath
+        ? [projectId, userId, options.filePath, limit]
+        : [projectId, userId, limit];
+    const rows = db.prepare(`${mentionSelect}
+    WHERE mention.project_id = ? AND mention.mentioned_user_id = ? ${unreadClause} ${fileClause}
+    ORDER BY mention.created_at DESC LIMIT ?`).all(...parameters);
+    return rows.map(mentionFromRow);
+}
+export function commentMentionForUser(db, mentionId, projectId, userId) {
+    const row = db.prepare(`${mentionSelect}
+    WHERE mention.id = ? AND mention.project_id = ? AND mention.mentioned_user_id = ?`)
+        .get(mentionId, projectId, userId);
+    return row ? mentionFromRow(row) : null;
+}
+/** Mark an item read after the UI has opened and located its target thread. */
+export function markCommentMentionRead(db, mentionId, userId, readAt, reason = "opened") {
+    return db.prepare(`UPDATE comment_mentions
+    SET read_at = ?, read_reason = ?
+    WHERE id = ? AND mentioned_user_id = ? AND read_at IS NULL`)
+        .run(readAt, reason, mentionId, userId).changes > 0;
+}
+/** Explicitly clear every unread notification in a project for one recipient. */
+export function markAllCommentMentionsRead(db, projectId, userId, readAt) {
+    return db.prepare(`UPDATE comment_mentions
+    SET read_at = ?, read_reason = 'manual'
+    WHERE project_id = ? AND mentioned_user_id = ? AND read_at IS NULL`)
+        .run(readAt, projectId, userId).changes;
+}
+/** Resolving a thread makes all existing unread mentions in it non-actionable. */
+export function markCommentMentionsResolved(db, commentId, resolvedAt) {
+    return db.prepare(`UPDATE comment_mentions
+    SET read_at = ?, read_reason = 'resolved'
+    WHERE comment_id = ? AND read_at IS NULL`)
+        .run(resolvedAt, commentId).changes;
+}