texlite 0.9.0 → 0.9.2

package/dist/server/app.js

@@ -29,6 +29,7 @@ import { registerCitationRoutes } from "./routes/citations.js";
 import { registerCommentRoutes } from "./routes/comments.js";
 import { registerProjectMemberRoutes } from "./routes/projectMembers.js";
 import { registerProjectFileRoutes } from "./routes/projectFiles.js";
+import { registerProjectReferenceRoutes } from "./routes/projectReferences.js";
 import { registerProjectHistoryRoutes } from "./routes/projectHistory.js";
 import { registerProjectGitRoutes } from "./routes/projectGit.js";
 import { registerProjectCatalogRoutes } from "./routes/projects.js";
@@ -37,10 +38,36 @@ import { registerUserManagementRoutes } from "./routes/users.js";
 import { registerWordCountRoutes } from "./routes/wordCount.js";
 import { HarperService } from "./harper.js";
 import { TexcountService } from "./texcount.js";
+import { basePathHref, basePathPrefix, withoutBasePath } from "../shared/basePath.js";
 // Retained public helper for callers and tests; implementation lives with the file routes.
 export { escapeGlobPattern } from "./routes/projectShared.js";
 const SESSION_CLEANUP_INTERVAL_MS = 15 * 60_000;
 const now = () => new Date().toISOString();
+/** Inject the runtime mount point into a single, path-independent Vite build. */
+export function renderClientIndex(source, basePath) {
+    const href = escapeHtmlAttribute(basePathHref(basePath));
+    const value = escapeHtmlAttribute(basePath);
+    const baseElement = `<base href="${href}" />`;
+    const metaElement = `<meta name="texlite-base-path" content="${value}" />`;
+    let hadBase = false;
+    let rendered = source.replace(/<base\s+href=(?:"[^"]*"|'[^']*')\s*\/?\s*>/i, () => {
+        hadBase = true;
+        return baseElement;
+    });
+    if (!hadBase)
+        rendered = rendered.replace(/<head(?:\s[^>]*)?>/i, (head) => `${head}\n    ${baseElement}`);
+    let hadMeta = false;
+    rendered = rendered.replace(/<meta\s+name=(?:"texlite-base-path"|'texlite-base-path')\s+content=(?:"[^"]*"|'[^']*')\s*\/?\s*>/i, () => {
+        hadMeta = true;
+        return metaElement;
+    });
+    if (!hadMeta)
+        rendered = rendered.replace(baseElement, `${baseElement}\n    ${metaElement}`);
+    return rendered;
+}
+function escapeHtmlAttribute(value) {
+    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
 export async function buildApp(config, db, options = {}) {
     const app = Fastify({
         logger: options.logger ?? true,
@@ -161,7 +188,10 @@ export async function buildApp(config, db, options = {}) {
         const startedAt = requestStarts.get(request);
         if (startedAt === undefined)
             return;
-        const route = request.routeOptions.url;
+        const registeredRoute = request.routeOptions.url;
+        const route = registeredRoute
+            ? withoutBasePath(config.basePath, registeredRoute) ?? registeredRoute
+            : null;
         if (!route)
             return;
         const metric = {
@@ -193,93 +223,110 @@ export async function buildApp(config, db, options = {}) {
             void apiError(reply, 500, "SERVER_ERROR");
         }
     });
-    registerSystemRoutes(app, {
-        config,
-        db,
-        queue,
-        collaboration,
-        latexCompletions,
-        projectOutlines,
-        metrics,
-        eventLoopDelay
-    });
-    registerCollaborationRoutes(app, { db, collaboration, metrics });
-    registerAuthRoutes(app, { config, db, loginLimiter });
-    registerCitationRoutes(app, { db });
-    registerUserManagementRoutes(app, {
-        config,
-        db,
-        collaboration,
-        projectMutations,
-        latexCompletions,
-        projectOutlines
-    });
-    registerCommentRoutes(app, { config, db, collaboration, projectMutations });
-    registerProjectMemberRoutes(app, { db, collaboration, projectMutations });
-    registerProjectFileRoutes(app, {
-        config,
-        db,
-        collaboration,
-        projectMutations,
-        latexCompletions,
-        projectOutlines,
-        metrics,
-        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,
-        db,
-        collaboration,
-        projectMutations,
-        latexCompletions,
-        projectOutlines,
-        harper,
-        recordHistory
-    });
-    registerWordCountRoutes(app, { config, db, projectMutations, texcount });
-    registerCompileRoutes(app, { config, db, collaboration, projectMutations, compileCoordinator, metrics, pruneCompileRuns });
-    // The factory owns shared services and lifecycle hooks; route modules own endpoint behavior.
-    app.addHook("onRequest", async (request) => {
-        if (request.url.startsWith("/api/") && request.url !== "/api/auth/login" && request.url !== "/api/health" && request.url !== "/api/config") {
-            const token = request.cookies.texlite_session;
-            if (token && !currentUser(request, db)) {
-                db.prepare("DELETE FROM sessions WHERE id = ?").run(digestToken(token));
-            }
-        }
-    });
     app.addHook("onClose", async () => collaboration.destroy());
-    if (fs.existsSync(config.clientDir)) {
-        await app.register(staticPlugin, {
-            root: config.clientDir,
-            wildcard: false,
-            // Vite fingerprints everything under assets/. These large JS/WASM files
-            // are safe to cache indefinitely; a new build produces a new URL. Keep
-            // index.html fresh so it always points at the current fingerprints.
-            cacheControl: false,
-            setHeaders(reply, filePath) {
-                const relativePath = path.relative(config.clientDir, filePath).split(path.sep).join("/");
-                if (relativePath === "index.html") {
-                    reply.header("Cache-Control", "no-store");
-                }
-                else if (relativePath.startsWith("assets/")) {
-                    reply.header("Cache-Control", "public, max-age=31536000, immutable");
-                }
-                else {
-                    reply.header("Cache-Control", "public, max-age=3600");
+    const indexPath = path.join(config.clientDir, "index.html");
+    const renderedIndex = fs.existsSync(indexPath)
+        ? renderClientIndex(fs.readFileSync(indexPath, "utf8"), config.basePath)
+        : null;
+    const routePrefix = basePathPrefix(config.basePath);
+    await app.register(async (routes) => {
+        routes.addHook("onRequest", async (request) => {
+            const requestPath = withoutBasePath(config.basePath, request.url) ?? request.url;
+            if (requestPath.startsWith("/api/")
+                && requestPath !== "/api/auth/login"
+                && requestPath !== "/api/health"
+                && requestPath !== "/api/config") {
+                const token = request.cookies.texlite_session;
+                if (token && !currentUser(request, db)) {
+                    db.prepare("DELETE FROM sessions WHERE id = ?").run(digestToken(token));
                 }
             }
         });
-        app.get("/*", async (request, reply) => {
-            if (request.url.startsWith("/api/"))
-                return apiError(reply, 404, "API_NOT_FOUND");
-            reply.header("Cache-Control", "no-store");
-            return reply.sendFile("index.html");
+        registerSystemRoutes(routes, {
+            config,
+            db,
+            queue,
+            collaboration,
+            latexCompletions,
+            projectOutlines,
+            metrics,
+            eventLoopDelay
         });
-    }
+        registerCollaborationRoutes(routes, { db, collaboration, metrics });
+        registerAuthRoutes(routes, { config, db, loginLimiter });
+        registerCitationRoutes(routes, { db });
+        registerUserManagementRoutes(routes, {
+            config,
+            db,
+            collaboration,
+            projectMutations,
+            latexCompletions,
+            projectOutlines
+        });
+        registerCommentRoutes(routes, { config, db, collaboration, projectMutations });
+        registerProjectMemberRoutes(routes, { db, collaboration, projectMutations });
+        registerProjectFileRoutes(routes, {
+            config,
+            db,
+            collaboration,
+            projectMutations,
+            latexCompletions,
+            projectOutlines,
+            metrics,
+            recordHistory
+        });
+        registerProjectReferenceRoutes(routes, { config, db, projectMutations });
+        registerProjectHistoryRoutes(routes, { config, db, history, editHistory, projectMutations, recordHistory,
+            clearPendingEdits: (id) => { editRetry.clear(id); failedEdits.delete(id); signalHistory(id); },
+            scheduleHistoryRetention: (id) => historyRetention.schedule(id) });
+        registerProjectGitRoutes(routes, { config, db, collaboration, projectMutations, projectGit, recordHistory });
+        registerProjectCatalogRoutes(routes, {
+            config,
+            db,
+            collaboration,
+            projectMutations,
+            latexCompletions,
+            projectOutlines,
+            harper,
+            recordHistory
+        });
+        registerWordCountRoutes(routes, { config, db, projectMutations, texcount });
+        registerCompileRoutes(routes, { config, db, collaboration, projectMutations, compileCoordinator, metrics, pruneCompileRuns });
+        // The factory owns shared services and lifecycle hooks; route modules own endpoint behavior.
+        if (renderedIndex !== null) {
+            await routes.register(staticPlugin, {
+                root: config.clientDir,
+                wildcard: false,
+                index: false,
+                globIgnore: ["index.html"],
+                // Vite fingerprints everything under assets/. These large JS/WASM
+                // files are safe to cache indefinitely; a new build produces a new
+                // URL. The rendered SPA shell below always remains fresh.
+                cacheControl: false,
+                setHeaders(reply, filePath) {
+                    const relativePath = path.relative(config.clientDir, filePath).split(path.sep).join("/");
+                    if (relativePath.startsWith("assets/")) {
+                        reply.header("Cache-Control", "public, max-age=31536000, immutable");
+                    }
+                    else {
+                        reply.header("Cache-Control", "public, max-age=3600");
+                    }
+                }
+            });
+            const sendIndex = async (_request, reply) => {
+                reply.header("Cache-Control", "no-store");
+                return reply.type("text/html; charset=utf-8").send(renderedIndex);
+            };
+            routes.get("/", sendIndex);
+            routes.get("/index.html", sendIndex);
+            routes.get("/*", async (request, reply) => {
+                const requestPath = withoutBasePath(config.basePath, request.url) ?? request.url;
+                if (requestPath.startsWith("/api/"))
+                    return apiError(reply, 404, "API_NOT_FOUND");
+                return sendIndex(request, reply);
+            });
+        }
+    }, { prefix: routePrefix });
     const cleanupExpiredSessions = () => {
         try {
             pruneExpiredSessions(db, now());

package/dist/server/cli.js

@@ -12,6 +12,7 @@ import { assertEnvironment, hostRequirementsSatisfied, inspectHostEnvironment, i
 import { serve } from "./index.js";
 import { processStatus, restartManaged, startManaged, stopManaged, streamLogs, waitForOnline } from "./pm2.js";
 import { defaultDataDirectory, resolveConfigPath } from "./runtimePaths.js";
+import { basePathHref } from "../shared/basePath.js";
 const HELP = `TexLite ${packageVersion()}
 
 Usage:
@@ -106,7 +107,7 @@ function writeInitialConfig(configPath, siteName, adminEmail) {
         siteName,
         adminEmail,
         sessionDays: CONFIG_DEFAULTS.sessionDays,
-        server: { host: CONFIG_DEFAULTS.host, port: CONFIG_DEFAULTS.port },
+        server: { host: CONFIG_DEFAULTS.host, port: CONFIG_DEFAULTS.port, basePath: CONFIG_DEFAULTS.basePath },
         storage: { dataDir: dataDirectory },
         uploads: { maxFileSizeMB: CONFIG_DEFAULTS.maxFileSizeMB },
         pdf: {
@@ -277,6 +278,7 @@ async function printConfig(options) {
         siteName: config.siteName,
         host: config.host,
         port: config.port,
+        basePath: config.basePath,
         dataDir: config.dataDir,
         databasePath: config.databasePath,
         projectsDir: config.projectsDir,
@@ -304,7 +306,7 @@ async function start(options, restart = false) {
     const managed = await waitForOnline(config);
     const status = managed.description?.pm2_env?.status ?? "unknown";
     output(`TexLite ${status}: ${config.siteName}`);
-    output(`Address: http://${config.host}:${config.port}`);
+    output(`Address: http://${config.host}:${config.port}${basePathHref(config.basePath)}`);
     output(`Configuration file: ${configPath}`);
     output(`PM2 process: ${managed.name}`);
 }

package/dist/server/compileArtifacts.js

@@ -4,6 +4,7 @@ import { publishedCompileArtifacts } from "./compiler.js";
 import { outputRoot, resolveSourcePath, safeRelativePath, sourceRoot, texFileStem } from "./files.js";
 import { isMainDocumentCandidateSync } from "./latexRoot.js";
 import { MAX_TEXT_PREVIEW_BYTES } from "./limits.js";
+import { withBasePath } from "../shared/basePath.js";
 export function pdfLoadingMode(config, pdfSizeBytes) {
     if (config.pdfLoadingStrategy === "full" || config.pdfLoadingStrategy === "range") {
         return config.pdfLoadingStrategy;
@@ -77,8 +78,8 @@ export function compileMainFile(config, projectId, defaultMainFile, value) {
     }
     return mainFile;
 }
-export function compilePdfUrl(projectId, mainFile, version) {
-    return `/api/projects/${projectId}/pdf?mainFile=${encodeURIComponent(mainFile)}&run=${encodeURIComponent(version)}`;
+export function compilePdfUrl(config, projectId, mainFile, version) {
+    return withBasePath(config.basePath, `/api/projects/${projectId}/pdf?mainFile=${encodeURIComponent(mainFile)}&run=${encodeURIComponent(version)}`);
 }
 export function listCompileArtifacts(directory) {
     const artifacts = [];

package/dist/server/config.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { defaultDataDirectory, packageClientDirectory, resolveConfigPath } from "./runtimePaths.js";
+import { normalizeBasePath, ROOT_BASE_PATH } from "../shared/basePath.js";
 export const LATEX_ENGINES = ["pdflatex", "xelatex", "lualatex"];
 export const PDF_LOADING_STRATEGIES = ["auto", "full", "range"];
 /** Effective values used when the corresponding file/env setting is omitted. */
@@ -9,6 +10,7 @@ export const CONFIG_DEFAULTS = {
     adminEmail: "",
     host: "127.0.0.1",
     port: 3000,
+    basePath: ROOT_BASE_PATH,
     dataDir: defaultDataDirectory(),
     clientDir: packageClientDirectory(),
     sessionDays: 14,
@@ -74,12 +76,14 @@ export function loadConfig(configPathOverride) {
     const historyMaxStorageMB = integerSetting("history.maxStorageMB", process.env.TEXLITE_HISTORY_MAX_STORAGE_MB, fileConfig.history?.maxStorageMB, CONFIG_DEFAULTS.historyMaxStorageMB, CONFIG_LIMITS.historyMaxStorageMB);
     const editHistoryMaxStorageMB = integerSetting("editHistory.maxStorageMB", process.env.TEXLITE_EDIT_HISTORY_MAX_STORAGE_MB, fileConfig.editHistory?.maxStorageMB, CONFIG_DEFAULTS.editHistoryMaxStorageMB, CONFIG_LIMITS.editHistoryMaxStorageMB);
     const gitOperationTimeoutSeconds = integerSetting("git.operationTimeoutSeconds", process.env.TEXLITE_GIT_TIMEOUT, fileConfig.git?.operationTimeoutSeconds, CONFIG_DEFAULTS.gitOperationTimeoutSeconds, CONFIG_LIMITS.gitOperationTimeoutSeconds);
+    const basePath = resolveBasePath(fileConfig);
     const config = {
         configPath,
         siteName: stringSetting("siteName", process.env.TEXLITE_SITE_NAME, fileConfig.siteName, CONFIG_DEFAULTS.siteName, { min: 1, max: 120 }),
         adminEmail: stringSetting("adminEmail", process.env.TEXLITE_ADMIN_EMAIL, fileConfig.adminEmail, CONFIG_DEFAULTS.adminEmail, { min: 0, max: 320 }),
         host: stringSetting("server.host", process.env.TEXLITE_HOST, fileConfig.server?.host, CONFIG_DEFAULTS.host, { min: 1, max: 255 }),
         port: integerSetting("server.port", process.env.TEXLITE_PORT, fileConfig.server?.port, CONFIG_DEFAULTS.port, CONFIG_LIMITS.port),
+        basePath,
         dataDir,
         databasePath: path.join(dataDir, "texlite.db"),
         projectsDir: path.join(dataDir, "projects"),
@@ -105,6 +109,17 @@ export function loadConfig(configPathOverride) {
     validateConfig(config);
     return config;
 }
+/**
+ * Read only the configured public mount path. Vite uses this during local UI
+ * development, where checking server data paths would be unnecessary and can
+ * prevent the frontend from starting before the API server is configured.
+ */
+export function loadBasePath(configPathOverride) {
+    const configPath = resolveConfigPath(configPathOverride);
+    const fileConfig = readConfigFile(configPath);
+    validateFileConfig(fileConfig);
+    return resolveBasePath(fileConfig);
+}
 /** Validate an already materialized configuration (useful for startup/tests). */
 export function validateConfig(config) {
     if (!config.dataDir || path.parse(config.dataDir).root === config.dataDir) {
@@ -126,6 +141,9 @@ export function validateConfig(config) {
         throw configurationError("latex.defaultEngine", "must be one of the engines listed in latex.allowedEngines");
     }
     validateInteger("server.port", config.port, CONFIG_LIMITS.port);
+    if (normalizeBasePath(config.basePath) !== config.basePath) {
+        throw configurationError("server.basePath", "must be / or a normalized URL path such as /texlite or /tools/texlite");
+    }
     validateInteger("sessionDays", config.sessionDays, CONFIG_LIMITS.sessionDays);
     validateInteger("latex.compileTimeoutSeconds", config.compileTimeoutMs / 1000, CONFIG_LIMITS.compileTimeoutSeconds);
     validateInteger("latex.maxCompileJobs", config.maxCompileJobs, CONFIG_LIMITS.maxCompileJobs);
@@ -139,6 +157,14 @@ export function validateConfig(config) {
     validateInteger("editHistory.maxStorageMB", config.editHistoryMaxStorageBytes / (1024 * 1024), CONFIG_LIMITS.editHistoryMaxStorageMB);
     validateInteger("git.operationTimeoutSeconds", config.gitOperationTimeoutMs / 1000, CONFIG_LIMITS.gitOperationTimeoutSeconds);
 }
+function resolveBasePath(fileConfig) {
+    const configuredBasePath = stringSetting("server.basePath", process.env.TEXLITE_BASE_PATH, fileConfig.server?.basePath, CONFIG_DEFAULTS.basePath, { min: 1, max: 1_024 });
+    const basePath = normalizeBasePath(configuredBasePath);
+    if (!basePath) {
+        throw configurationError("server.basePath", `must be / or a URL path such as /texlite or /tools/texlite; received ${displayValue(configuredBasePath)}`);
+    }
+    return basePath;
+}
 function isEngine(value) {
     return typeof value === "string" && LATEX_ENGINES.includes(value);
 }
@@ -168,6 +194,7 @@ function validateFileConfig(config) {
     const server = optionalSection(config.server, "server");
     optionalString(server?.host, "server.host", { min: 1, max: 255 });
     optionalInteger(server?.port, "server.port", CONFIG_LIMITS.port);
+    optionalString(server?.basePath, "server.basePath", { min: 1, max: 1_024 });
     const storage = optionalSection(config.storage, "storage");
     optionalString(storage?.dataDir, "storage.dataDir", { min: 1, max: 4_096 });
     const uploads = optionalSection(config.uploads, "uploads");

package/dist/server/harper.js

@@ -11,12 +11,26 @@ const maxCachedSourceBytes = 512 * 1024;
 const maxCachedResults = 24;
 const cacheTtlMs = 15_000;
 const unavailableRetryMs = 15_000;
+// A browser can send an older request after a newer one when HTTP requests
+// race. Keep the latest sequence briefly so that late arrivals cannot replace
+// a newer queued revision. The bound is intentionally generous for a small
+// collaborative installation while keeping abandoned browser-page lanes from
+// accumulating forever.
+const laneSequenceRetentionMs = 10 * 60_000;
+const maxTrackedLaneSequences = 512;
 export class HarperUnavailableError extends Error {
     constructor(message) {
         super(message);
         this.name = "HarperUnavailableError";
     }
 }
+/** A newer source revision made a waiting writing check irrelevant. */
+export class HarperLintSupersededError extends Error {
+    constructor() {
+        super("A newer writing check replaced this request.");
+        this.name = "HarperLintSupersededError";
+    }
+}
 function lintCacheKey(source, filePath) {
     // Harper selects its parser from the input suffix, so equivalent text in a
     // .tex and a .sty file must not share a diagnostic result.
@@ -78,8 +92,20 @@ export class HarperService {
     availability = "unknown";
     lastUnavailableAt = 0;
     probePromise = null;
-    queue = Promise.resolve();
+    /** One harper-cli process at a time; Harper itself is comparatively heavy. */
+    queueRunner = null;
+    // Set preserves insertion order, giving the scheduler FIFO behaviour while
+    // allowing a superseded waiting item to be removed immediately. An array
+    // would otherwise retain its complete source string until the active check
+    // finishes.
+    queued = new Set();
+    /** Only waiting work belongs here; a running process must finish safely. */
+    waitingByLane = new Map();
+    /** Latest accepted browser revision for each project/user/page/file lane. */
+    latestSequenceByLane = new Map();
     inFlight = new Map();
+    /** Lets coalesced browser lanes share one queued operation safely. */
+    scheduledByKey = new Map();
     cache = new Map();
     activeChild = null;
     disposed = false;
@@ -89,35 +115,206 @@ export class HarperService {
     async preload() {
         await this.ensureAvailable();
     }
-    async lint(source, filePath = "main.tex") {
+    /**
+     * Schedule one host-side check. A lane represents one browser page's
+     * current file, so an edit can replace only its own stale waiting request
+     * without cancelling checks requested by collaborators.
+     */
+    async lint(source, filePath = "main.tex", lane, sequence) {
         if (this.disposed)
             throw new HarperUnavailableError("Harper service stopped.");
         const key = lintCacheKey(source, filePath);
+        const laneKey = lane || null;
+        if (laneKey && sequence !== undefined)
+            this.acceptLaneSequence(laneKey, sequence, key);
+        const waiting = laneKey ? this.waitingByLane.get(laneKey) : undefined;
+        // Repeated requests for the same queued revision share it. A newer
+        // revision replaces only work that has not started yet.
+        if (waiting?.key === key)
+            return waiting.promise;
+        if (laneKey && waiting)
+            this.releaseWaitingLane(laneKey, waiting);
         const cacheable = Buffer.byteLength(source, "utf8") <= maxCachedSourceBytes;
         const cached = cacheable ? this.cachedResult(key) : null;
         if (cached)
             return cached;
-        const existing = cacheable ? this.inFlight.get(key) : undefined;
-        if (existing)
+        // Result caching is deliberately size-bounded, but duplicate active work
+        // is still coalesced for large files. The latter is transient and avoids
+        // starting multiple expensive CLI processes for identical content.
+        const existing = this.inFlight.get(key);
+        if (existing) {
+            const scheduled = this.scheduledByKey.get(key);
+            if (laneKey && scheduled)
+                this.addWaitingLane(scheduled, laneKey);
+            else if (scheduled && !scheduled.started)
+                scheduled.hasUnscopedWaiter = true;
             return existing;
-        const operation = this.queue.then(() => this.lintOnce(source, filePath));
-        this.queue = operation.then(() => undefined, () => undefined);
+        }
+        let resolve;
+        let reject;
+        const operation = new Promise((resolveOperation, rejectOperation) => {
+            resolve = resolveOperation;
+            reject = rejectOperation;
+        });
+        const scheduled = {
+            key,
+            source,
+            filePath,
+            started: false,
+            cancelled: false,
+            lanes: laneKey ? new Set([laneKey]) : new Set(),
+            hasUnscopedWaiter: laneKey === null,
+            promise: operation,
+            resolve,
+            reject
+        };
+        this.inFlight.set(key, operation);
+        this.scheduledByKey.set(key, scheduled);
+        if (laneKey)
+            this.waitingByLane.set(laneKey, scheduled);
+        this.queued.add(scheduled);
+        this.startQueue();
         if (cacheable) {
-            this.inFlight.set(key, operation);
             void operation.then((lints) => this.cacheResult(key, lints), () => undefined).finally(() => {
                 if (this.inFlight.get(key) === operation)
                     this.inFlight.delete(key);
+                if (this.scheduledByKey.get(key) === scheduled)
+                    this.scheduledByKey.delete(key);
+            });
+        }
+        else {
+            // Attach a rejection handler even for uncached results. This keeps a
+            // superseded request from becoming an unhandled rejection when a client
+            // disconnects before it awaits the response.
+            void operation.catch(() => undefined).finally(() => {
+                if (this.inFlight.get(key) === operation)
+                    this.inFlight.delete(key);
+                if (this.scheduledByKey.get(key) === scheduled)
+                    this.scheduledByKey.delete(key);
             });
         }
         return operation;
     }
     async dispose() {
         this.disposed = true;
+        const stopped = new HarperUnavailableError("Harper service stopped.");
+        for (const scheduled of [...this.queued]) {
+            if (!scheduled.cancelled && !scheduled.started) {
+                scheduled.cancelled = true;
+                this.discardQueuedLint(scheduled);
+                scheduled.reject(stopped);
+            }
+        }
+        this.waitingByLane.clear();
+        this.latestSequenceByLane.clear();
         this.activeChild?.kill("SIGTERM");
-        await this.queue.catch(() => undefined);
+        await this.queueRunner?.catch(() => undefined);
         this.inFlight.clear();
+        this.scheduledByKey.clear();
         this.cache.clear();
     }
+    addWaitingLane(scheduled, lane) {
+        if (scheduled.started || scheduled.cancelled)
+            return;
+        scheduled.lanes.add(lane);
+        this.waitingByLane.set(lane, scheduled);
+    }
+    releaseWaitingLane(lane, scheduled) {
+        if (this.waitingByLane.get(lane) === scheduled)
+            this.waitingByLane.delete(lane);
+        scheduled.lanes.delete(lane);
+        // The exact same queued source can be requested by multiple sessions.
+        // Discard it only after every interested lane has moved on.
+        if (scheduled.started || scheduled.cancelled || scheduled.hasUnscopedWaiter || scheduled.lanes.size > 0)
+            return;
+        this.cancelScheduledLint(scheduled);
+    }
+    cancelScheduledLint(scheduled) {
+        if (scheduled.started || scheduled.cancelled)
+            return;
+        scheduled.cancelled = true;
+        for (const lane of scheduled.lanes) {
+            if (this.waitingByLane.get(lane) === scheduled)
+                this.waitingByLane.delete(lane);
+        }
+        scheduled.lanes.clear();
+        // Remove this rejected promise immediately so a later return to the same
+        // text can enqueue fresh work instead of inheriting a stale rejection.
+        if (this.inFlight.get(scheduled.key) === scheduled.promise) {
+            this.inFlight.delete(scheduled.key);
+        }
+        if (this.scheduledByKey.get(scheduled.key) === scheduled) {
+            this.scheduledByKey.delete(scheduled.key);
+        }
+        this.discardQueuedLint(scheduled);
+        scheduled.reject(new HarperLintSupersededError());
+    }
+    /** Remove a waiting task and promptly release its potentially large text. */
+    discardQueuedLint(scheduled) {
+        this.queued.delete(scheduled);
+        scheduled.source = "";
+        scheduled.filePath = "";
+    }
+    /** Reject an out-of-order request before it can alter queued work. */
+    acceptLaneSequence(lane, sequence, key) {
+        if (!Number.isSafeInteger(sequence) || sequence <= 0) {
+            throw new HarperLintSupersededError();
+        }
+        const now = Date.now();
+        this.pruneLaneSequences(now);
+        const previous = this.latestSequenceByLane.get(lane);
+        if (previous && (sequence < previous.sequence || (sequence === previous.sequence && previous.key !== key))) {
+            throw new HarperLintSupersededError();
+        }
+        // Refresh insertion order so the bounded map evicts the least recently
+        // used abandoned page lane first.
+        this.latestSequenceByLane.delete(lane);
+        this.latestSequenceByLane.set(lane, { sequence, key, seenAt: now });
+        while (this.latestSequenceByLane.size > maxTrackedLaneSequences) {
+            const oldest = this.latestSequenceByLane.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.latestSequenceByLane.delete(oldest);
+        }
+    }
+    pruneLaneSequences(now) {
+        for (const [lane, state] of this.latestSequenceByLane) {
+            if (now - state.seenAt <= laneSequenceRetentionMs)
+                continue;
+            this.latestSequenceByLane.delete(lane);
+        }
+    }
+    startQueue() {
+        if (this.queueRunner)
+            return;
+        this.queueRunner = (async () => {
+            while (!this.disposed) {
+                const scheduled = this.queued.values().next().value;
+                if (!scheduled)
+                    return;
+                this.queued.delete(scheduled);
+                if (scheduled.cancelled)
+                    continue;
+                scheduled.started = true;
+                for (const lane of scheduled.lanes) {
+                    if (this.waitingByLane.get(lane) === scheduled)
+                        this.waitingByLane.delete(lane);
+                }
+                scheduled.lanes.clear();
+                try {
+                    scheduled.resolve(await this.lintOnce(scheduled.source, scheduled.filePath));
+                }
+                catch (error) {
+                    scheduled.reject(error);
+                }
+            }
+        })().finally(() => {
+            this.queueRunner = null;
+            // A request can arrive just after the loop observes an empty queue.
+            if (!this.disposed && this.queued.size)
+                this.startQueue();
+        });
+    }
     async ensureAvailable() {
         if (this.availability === "available")
             return;