texlite 0.7.5 → 0.7.6

package/dist/server/auth.js

@@ -1,3 +1,4 @@
+import { apiError } from "./http.js";
 import { digestToken } from "./security.js";
 export function publicUser(user) {
     return {
@@ -36,7 +37,7 @@ export function currentUser(request, db) {
 export function requireUser(request, reply, db) {
     const user = currentUser(request, db);
     if (!user) {
-        void reply.code(401).send({ code: "AUTH_REQUIRED", error: "请先登录" });
+        void apiError(reply, 401, "AUTH_REQUIRED");
         return null;
     }
     return user;
@@ -46,7 +47,7 @@ export function requireAdmin(request, reply, db) {
     if (!user)
         return null;
     if (user.role !== "admin") {
-        void reply.code(403).send({ code: "ADMIN_REQUIRED", error: "需要管理员权限" });
+        void apiError(reply, 403, "ADMIN_REQUIRED");
         return null;
     }
     return user;

package/dist/server/cli.js

@@ -7,7 +7,7 @@ import { stdin, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
 import { CONFIG_DEFAULTS, loadConfig } from "./config.js";
 import { activeAdminCount, openDatabase } from "./db.js";
-import { hashPassword } from "./security.js";
+import { hashPassword, MIN_PASSWORD_LENGTH } from "./security.js";
 import { assertEnvironment, assertGitAvailable } from "./environment.js";
 import { serve } from "./index.js";
 import { processStatus, restartManaged, startManaged, stopManaged, streamLogs, waitForOnline } from "./pm2.js";
@@ -110,6 +110,10 @@ function writeInitialConfig(configPath, siteName, adminEmail) {
         server: { host: CONFIG_DEFAULTS.host, port: CONFIG_DEFAULTS.port },
         storage: { dataDir: dataDirectory },
         uploads: { maxFileSizeMB: CONFIG_DEFAULTS.maxFileSizeMB },
+        pdf: {
+            loadingStrategy: CONFIG_DEFAULTS.pdfLoadingStrategy,
+            rangeThresholdMB: CONFIG_DEFAULTS.pdfRangeThresholdMB
+        },
         history: {
             maxVersions: CONFIG_DEFAULTS.historyMaxVersions,
             maxStorageMB: CONFIG_DEFAULTS.historyMaxStorageMB
@@ -172,7 +176,7 @@ async function initialize(options) {
         const displayName = process.env.TEXLITE_INIT_DISPLAY_NAME
             ?? (rl ? (await rl.question("Administrator display name [Administrator]: ")).trim() || "Administrator" : "Administrator");
         const password = process.env.TEXLITE_INIT_PASSWORD
-            ?? (rl ? await rl.question("Administrator password (at least 8 characters; input is visible): ") : "");
+            ?? (rl ? await rl.question(`Administrator password (at least ${MIN_PASSWORD_LENGTH} characters; input is visible): `) : "");
         if (!password)
             throw new Error("Non-interactive initialization requires TEXLITE_INIT_PASSWORD to be set.");
         const timestamp = new Date().toISOString();
@@ -234,6 +238,8 @@ async function printConfig(options) {
         defaultEngine: config.defaultEngine,
         allowedEngines: config.allowedEngines,
         maxUploadBytes: config.maxUploadBytes,
+        pdfLoadingStrategy: config.pdfLoadingStrategy,
+        pdfRangeThresholdMB: config.pdfRangeThresholdBytes / (1024 * 1024),
         historyMaxVersions: config.historyMaxVersions,
         historyMaxStorageBytes: config.historyMaxStorageBytes,
         git: config.git

package/dist/server/collaboration.js

@@ -22,12 +22,15 @@ const MESSAGE_PERMISSION = 7;
 // Source text still uses the normal Yjs sync protocol; this message prevents
 // an old IndexedDB metadata entry from being treated as an active compile.
 const MESSAGE_COMPILE_STATES = 8;
+// Ephemeral, per-file formatter leases. These are deliberately kept out of
+// the Yjs document and source persistence state.
+const MESSAGE_FORMAT_LEASE = 9;
 /**
  * Increment this when a wire-level collaboration change cannot be decoded by
  * an older browser. The epoch marker is rotated at the same time, which makes
  * already-open older pages discard their local draft and reload safely.
  */
-export const COLLABORATION_PROTOCOL_VERSION = 2;
+export const COLLABORATION_PROTOCOL_VERSION = 3;
 const VERSIONED_EPOCH_PREFIX = `${COLLABORATION_PROTOCOL_VERSION}:`;
 const SOURCE_PREFIX = "source:";
 const MAX_PROJECT_SESSIONS = 10;
@@ -38,6 +41,8 @@ const META_ORIGIN = Symbol("meta");
 const SAVE_DELAY_MS = 750;
 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;
 const EPHEMERAL_META_KEYS = ["compileStates", "filesEvent", "commentsRevision", "dictionaryRevision"];
 const COLORS = [
     ["#1677c8", "#1677c833"], ["#d65745", "#d6574533"], ["#16866a", "#16866a33"],
@@ -262,6 +267,11 @@ export class CollaborationService {
         const room = this.rooms.get(projectId);
         if (!room)
             return;
+        if (permission === "read" || permission === "revoked") {
+            const connectionIds = new Set([...room.connections].filter((connection) => connection.user.id === userId));
+            for (const connection of connectionIds)
+                this.releaseFormatLeasesForConnection(room, connection);
+        }
         const encoder = encoding.createEncoder();
         encoding.writeVarUint(encoder, MESSAGE_PERMISSION);
         encoding.writeVarString(encoder, userId);
@@ -657,7 +667,9 @@ export class CollaborationService {
             snapshotFlushPending: false,
             pendingFlushes: [],
             rejectedPaths: new Set(),
-            compileMetaValidationPending: false
+            compileMetaValidationPending: false,
+            formatLeases: new Map(),
+            formatLeaseWaiters: new Map()
         };
         room.awareness.setLocalState(null);
         // A recovered Yjs document may contain metadata from a process that no
@@ -859,6 +871,7 @@ export class CollaborationService {
                 this.sendSyncStep1(room, connection.socket);
                 this.sendCompileStates(room, connection.socket);
                 this.sendAwareness(room, connection.socket);
+                this.sendFormatLeaseStates(room, connection);
             }
             return;
         }
@@ -916,6 +929,10 @@ export class CollaborationService {
             this.sendFlushReceipt(connection, requestId, receipt);
             return;
         }
+        if (messageType === MESSAGE_FORMAT_LEASE) {
+            this.handleFormatLeaseMessage(room, connection, decoder, current);
+            return;
+        }
         if (messageType !== MESSAGE_AWARENESS)
             return;
         const update = decoding.readVarUint8Array(decoder);
@@ -946,6 +963,7 @@ export class CollaborationService {
     disconnect(room, connection) {
         if (!room.connections.delete(connection))
             return;
+        this.releaseFormatLeasesForConnection(room, connection);
         room.pendingFlushes = room.pendingFlushes.filter((pending) => pending.connection !== connection);
         if (connection.protocolTimer)
             clearTimeout(connection.protocolTimer);
@@ -972,6 +990,219 @@ export class CollaborationService {
             if (connection !== except)
                 send(connection.socket, message);
     }
+    /**
+     * Serialize access to one source file while a browser-side formatter is
+     * calculating and applying its replacement. This is intentionally an
+     * in-memory room primitive: the lease is advisory to the live collaboration
+     * room, while the Yjs update + flush ordering remains the authoritative
+     * durability boundary. A disconnected holder can never keep a lease alive.
+     */
+    handleFormatLeaseMessage(room, connection, decoder, currentProject) {
+        const operation = decoding.hasContent(decoder) ? decoding.readVarString(decoder).slice(0, 16) : "";
+        const requestId = decoding.hasContent(decoder) ? decoding.readVarString(decoder).slice(0, 128) : "";
+        const rawPath = decoding.hasContent(decoder) ? decoding.readVarString(decoder) : "";
+        const token = decoding.hasContent(decoder) ? decoding.readVarString(decoder).slice(0, 128) : "";
+        let filePath;
+        try {
+            filePath = safeRelativePath(rawPath);
+        }
+        catch {
+            this.sendFormatLeaseResponse(connection, "denied", requestId, rawPath, "invalid path");
+            return;
+        }
+        if (!requestId || !isCollaborativeTextFile(filePath) || !room.allowedPaths.has(filePath)) {
+            this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "file is not format-able");
+            return;
+        }
+        if (!canEdit(currentProject)) {
+            this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "write permission is required");
+            return;
+        }
+        if (operation === "acquire") {
+            const current = this.activeFormatLease(room, filePath);
+            if (!current) {
+                // Expiring a lease may have immediately granted the next queued
+                // request. Do not overwrite that grant with this new request.
+                if (room.formatLeases.has(filePath)) {
+                    const waiters = room.formatLeaseWaiters.get(filePath) ?? [];
+                    if (waiters.length >= MAX_FORMAT_LEASE_WAITERS) {
+                        this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "too many formatters are waiting");
+                        return;
+                    }
+                    waiters.push({ path: filePath, requestId, connection });
+                    room.formatLeaseWaiters.set(filePath, waiters);
+                    return;
+                }
+                this.grantFormatLease(room, { path: filePath, requestId, connection });
+                return;
+            }
+            if (current.connection === connection) {
+                this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "this session already holds the lease");
+                return;
+            }
+            const waiters = room.formatLeaseWaiters.get(filePath) ?? [];
+            if (waiters.some((waiter) => waiter.connection === connection && waiter.requestId === requestId))
+                return;
+            if (waiters.length >= MAX_FORMAT_LEASE_WAITERS) {
+                this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "too many formatters are waiting");
+                return;
+            }
+            waiters.push({ path: filePath, requestId, connection });
+            room.formatLeaseWaiters.set(filePath, waiters);
+            return;
+        }
+        if (operation === "renew") {
+            const lease = this.activeFormatLease(room, filePath);
+            if (!lease || lease.connection !== connection || lease.token !== token) {
+                this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "format lease is no longer valid");
+                return;
+            }
+            this.extendFormatLease(room, lease);
+            this.sendFormatLeaseResponse(connection, "renewed", requestId, filePath, "", lease.expiresAt, lease.token);
+            this.broadcastFormatLeaseState(room, lease);
+            return;
+        }
+        if (operation === "release") {
+            const lease = this.activeFormatLease(room, filePath);
+            if (!lease || lease.connection !== connection || lease.token !== token) {
+                this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "format lease is no longer valid");
+                return;
+            }
+            this.releaseFormatLease(room, lease);
+            this.sendFormatLeaseResponse(connection, "released", requestId, filePath);
+            return;
+        }
+        if (operation === "cancel") {
+            const waiters = room.formatLeaseWaiters.get(filePath) ?? [];
+            const remaining = waiters.filter((waiter) => !(waiter.connection === connection && waiter.requestId === requestId));
+            if (remaining.length)
+                room.formatLeaseWaiters.set(filePath, remaining);
+            else
+                room.formatLeaseWaiters.delete(filePath);
+            // A timeout may race with the server granting the request. In that
+            // window the request is no longer in the waiter queue, so also revoke a
+            // matching active lease instead of leaving it until the TTL expires.
+            const active = this.activeFormatLease(room, filePath);
+            if (active?.connection === connection && active.requestId === requestId) {
+                this.releaseFormatLease(room, active);
+            }
+            this.sendFormatLeaseResponse(connection, "released", requestId, filePath);
+            return;
+        }
+        this.sendFormatLeaseResponse(connection, "denied", requestId, filePath, "unknown format lease operation");
+    }
+    activeFormatLease(room, filePath) {
+        const lease = room.formatLeases.get(filePath);
+        if (!lease)
+            return null;
+        if (lease.expiresAt > Date.now())
+            return lease;
+        this.releaseFormatLease(room, lease);
+        return null;
+    }
+    grantFormatLease(room, waiter) {
+        if (!room.connections.has(waiter.connection) || waiter.connection.socket.readyState !== WebSocket.OPEN)
+            return false;
+        const lease = {
+            path: waiter.path,
+            token: randomUUID(),
+            requestId: waiter.requestId,
+            connection: waiter.connection,
+            expiresAt: Date.now() + FORMAT_LEASE_TTL_MS,
+            timer: setTimeout(() => this.expireFormatLease(room, waiter.path), FORMAT_LEASE_TTL_MS + 25)
+        };
+        room.formatLeases.set(waiter.path, lease);
+        this.sendFormatLeaseResponse(waiter.connection, "grant", waiter.requestId, lease.path, "", lease.expiresAt, lease.token);
+        this.broadcastFormatLeaseState(room, lease);
+        return true;
+    }
+    extendFormatLease(room, lease) {
+        clearTimeout(lease.timer);
+        lease.expiresAt = Date.now() + FORMAT_LEASE_TTL_MS;
+        lease.timer = setTimeout(() => this.expireFormatLease(room, lease.path), FORMAT_LEASE_TTL_MS + 25);
+    }
+    expireFormatLease(room, filePath) {
+        const lease = room.formatLeases.get(filePath);
+        if (!lease)
+            return;
+        if (lease.expiresAt > Date.now()) {
+            lease.timer = setTimeout(() => this.expireFormatLease(room, filePath), lease.expiresAt - Date.now() + 25);
+            return;
+        }
+        this.releaseFormatLease(room, lease);
+    }
+    releaseFormatLease(room, lease) {
+        if (room.formatLeases.get(lease.path) !== lease)
+            return;
+        clearTimeout(lease.timer);
+        room.formatLeases.delete(lease.path);
+        this.broadcastFormatLeaseState(room, null, lease.path);
+        this.grantNextFormatLease(room, lease.path);
+    }
+    grantNextFormatLease(room, filePath) {
+        if (room.formatLeases.has(filePath))
+            return;
+        const waiters = room.formatLeaseWaiters.get(filePath);
+        if (!waiters?.length) {
+            room.formatLeaseWaiters.delete(filePath);
+            return;
+        }
+        while (waiters.length) {
+            const waiter = waiters.shift();
+            if (!room.connections.has(waiter.connection) || waiter.connection.socket.readyState !== WebSocket.OPEN)
+                continue;
+            // Keep all later requests in the room queue while the first valid
+            // waiter owns the lease. The previous implementation deleted the map
+            // before granting and silently dropped every later waiter.
+            if (waiters.length)
+                room.formatLeaseWaiters.set(filePath, waiters);
+            else
+                room.formatLeaseWaiters.delete(filePath);
+            if (this.grantFormatLease(room, waiter))
+                return;
+        }
+        room.formatLeaseWaiters.delete(filePath);
+    }
+    releaseFormatLeasesForConnection(room, connection) {
+        const pathsToGrant = new Set();
+        for (const [filePath, lease] of room.formatLeases) {
+            if (lease.connection !== connection)
+                continue;
+            pathsToGrant.add(filePath);
+            clearTimeout(lease.timer);
+            room.formatLeases.delete(filePath);
+            this.broadcastFormatLeaseState(room, null, filePath);
+        }
+        for (const [filePath, waiters] of room.formatLeaseWaiters) {
+            const remaining = waiters.filter((waiter) => waiter.connection !== connection);
+            if (remaining.length)
+                room.formatLeaseWaiters.set(filePath, remaining);
+            else
+                room.formatLeaseWaiters.delete(filePath);
+        }
+        for (const filePath of pathsToGrant)
+            this.grantNextFormatLease(room, filePath);
+    }
+    sendFormatLeaseResponse(connection, status, requestId, filePath, reason = "", expiresAt = 0, token = "") {
+        const encoder = encoding.createEncoder();
+        encoding.writeVarUint(encoder, MESSAGE_FORMAT_LEASE);
+        encoding.writeVarString(encoder, status);
+        encoding.writeVarString(encoder, requestId);
+        encoding.writeVarString(encoder, filePath);
+        encoding.writeVarString(encoder, token);
+        encoding.writeVarString(encoder, expiresAt > 0 ? String(expiresAt) : "");
+        encoding.writeVarString(encoder, reason.slice(0, 256));
+        send(connection.socket, encoding.toUint8Array(encoder));
+    }
+    broadcastFormatLeaseState(room, lease, filePath = lease?.path ?? "") {
+        this.broadcast(room, formatLeaseStateMessage(lease, filePath), null);
+    }
+    sendFormatLeaseStates(room, connection) {
+        for (const lease of room.formatLeases.values()) {
+            if (lease.expiresAt > Date.now())
+                send(connection.socket, formatLeaseStateMessage(lease, lease.path));
+        }
+    }
     scheduleRoomCleanup(room) {
         if (room.connections.size === 0 && !room.cleanupTimer) {
             room.cleanupTimer = setTimeout(() => this.destroyRoom(room), ROOM_IDLE_MS);
@@ -1147,6 +1378,10 @@ export class CollaborationService {
             connection.protocolTimer = null;
         }
         room.connections.clear();
+        for (const lease of room.formatLeases.values())
+            clearTimeout(lease.timer);
+        room.formatLeases.clear();
+        room.formatLeaseWaiters.clear();
         room.pendingFlushes.splice(0);
         room.rejectedPaths.clear();
         room.awarenessOwners.clear();
@@ -1302,6 +1537,19 @@ function maintenanceMessage(reason) {
     encoding.writeVarString(encoder, reason);
     return encoding.toUint8Array(encoder);
 }
+function formatLeaseStateMessage(lease, filePath) {
+    const encoder = encoding.createEncoder();
+    encoding.writeVarUint(encoder, MESSAGE_FORMAT_LEASE);
+    encoding.writeVarString(encoder, "state");
+    encoding.writeVarString(encoder, "");
+    encoding.writeVarString(encoder, filePath);
+    encoding.writeVarString(encoder, "");
+    encoding.writeVarString(encoder, lease ? String(lease.expiresAt) : "");
+    encoding.writeVarString(encoder, "");
+    encoding.writeVarString(encoder, lease?.connection.user.id ?? "");
+    encoding.writeVarString(encoder, lease?.connection.user.display_name ?? "");
+    return encoding.toUint8Array(encoder);
+}
 function awarenessClientIds(update) {
     const decoder = decoding.createDecoder(update);
     const count = decoding.readVarUint(decoder);

package/dist/server/compileArtifacts.js

@@ -2,7 +2,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { publishedCompileArtifacts } from "./compiler.js";
 import { outputRoot, resolveSourcePath, safeRelativePath, sourceRoot, texFileStem } from "./files.js";
-import { hasDocumentClass } from "./zip.js";
+import { isMainDocumentCandidateSync } from "./latexRoot.js";
+import { MAX_TEXT_PREVIEW_BYTES } from "./limits.js";
+export function pdfLoadingMode(config, pdfSizeBytes) {
+    if (config.pdfLoadingStrategy === "full" || config.pdfLoadingStrategy === "range") {
+        return config.pdfLoadingStrategy;
+    }
+    return pdfSizeBytes > config.pdfRangeThresholdBytes ? "range" : "full";
+}
 export function availablePdf(config, projectId, mainFile, defaultMainFile) {
     const isDefault = mainFile === defaultMainFile;
     const published = publishedCompileArtifacts(config, projectId, mainFile, isDefault);
@@ -62,11 +69,7 @@ export function compileMainFile(config, projectId, defaultMainFile, value) {
     try {
         if (!fs.statSync(absolute).isFile())
             return null;
-        // A project may intentionally contain only one fragmentary .tex file; the
-        // upload flow keeps it as the configured root and latexmk reports the
-        // resulting compile error. Session-selected alternate roots are stricter:
-        // they must identify an actual document rather than an included fragment.
-        if (mainFile !== defaultMainFile && !hasDocumentClass(fs.readFileSync(absolute, "utf8")))
+        if (!isMainDocumentCandidateSync(config, projectId, mainFile))
             return null;
     }
     catch {
@@ -87,7 +90,7 @@ export function listCompileArtifacts(directory) {
                 visit(absolute, relative);
             else if (entry.isFile()) {
                 const size = fs.statSync(absolute).size;
-                artifacts.push({ path: relative, size, viewable: size <= 2 * 1024 * 1024 && isTextCompileArtifact(relative) });
+                artifacts.push({ path: relative, size, viewable: size <= MAX_TEXT_PREVIEW_BYTES && isTextCompileArtifact(relative) });
             }
         }
     };

package/dist/server/compiler.js

@@ -242,7 +242,7 @@ export function cleanCompileArtifacts(config, projectId, mainFile, defaultMainFi
 }
 export function publishCompileArtifacts(config, projectId, snapshot, result) {
     if (!result.ok || !result.pdfPath)
-        throw new Error("无法发布失败的编译结果");
+        throw new Error("Cannot publish a failed compilation result");
     const manifestDirectory = compileTargetRoot(config, projectId, snapshot.mainFile);
     const previous = publishedCompileArtifacts(config, projectId, snapshot.mainFile);
     const manifest = {
@@ -535,14 +535,14 @@ function rewriteSynctexSource(synctexPath, cacheSource, snapshotSource) {
 export async function compileProject(config, snapshot, mainFileInput, engine, latexmkrcInput) {
     const mainFile = safeRelativePath(mainFileInput);
     if (!/\.tex$/i.test(mainFile))
-        throw new Error("主文件必须是 .tex 文件");
+        throw new Error("The main file must have a .tex extension");
     const startedAt = performance.now();
     let latexmkrc = null;
     if (config.allowProjectLatexmkrc && latexmkrcInput) {
         latexmkrc = safeRelativePath(latexmkrcInput);
         const absoluteRc = path.join(snapshot.sourceDir, latexmkrc);
         if (!fs.existsSync(absoluteRc) || !fs.statSync(absoluteRc).isFile()) {
-            throw new Error(`项目 latexmkrc 不存在：${latexmkrc}`);
+            throw new Error(`The configured project latexmkrc does not exist: ${latexmkrc}`);
         }
     }
     const cacheStartedAt = performance.now();
@@ -553,6 +553,11 @@ export async function compileProject(config, snapshot, mainFileInput, engine, la
     const engineFlag = engine === "xelatex" ? "-xelatex" : engine === "lualatex" ? "-lualatex" : "-pdf";
     const args = [
         engineFlag,
+        // latexmk otherwise reads a .latexmkrc from the compile working
+        // directory automatically.  Project sources may contain one after a ZIP
+        // import or a Git checkout, so only an rc file explicitly selected in the
+        // project settings may be loaded below with -r.
+        "-norc",
         "-interaction=nonstopmode",
         "-file-line-error",
         "-halt-on-error",
@@ -582,7 +587,7 @@ export async function compileProject(config, snapshot, mainFileInput, engine, la
         child.stderr.on("data", append);
         child.on("error", reject);
         const timeout = setTimeout(() => {
-            log += `\n编译超过 ${config.compileTimeoutMs / 1000} 秒，已终止。\n`;
+            log += `\nCompilation exceeded ${config.compileTimeoutMs / 1000} seconds and was terminated.\n`;
             killProcessGroup(child);
         }, config.compileTimeoutMs);
         child.on("close", (code) => {

package/dist/server/config.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { defaultDataDirectory, packageClientDirectory, resolveConfigPath } from "./runtimePaths.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. */
 export const CONFIG_DEFAULTS = {
     siteName: "TexLite",
@@ -19,8 +20,10 @@ export const CONFIG_DEFAULTS = {
     extraArgs: [],
     allowProjectLatexmkrc: true,
     maxFileSizeMB: 50,
+    pdfLoadingStrategy: "auto",
+    pdfRangeThresholdMB: 5,
     historyMaxVersions: 200,
-    historyMaxStorageMB: 512,
+    historyMaxStorageMB: 128,
     git: "git",
     gitOperationTimeoutSeconds: 120,
     githubApiBaseUrl: "https://api.github.com"
@@ -31,6 +34,7 @@ const CONFIG_LIMITS = {
     compileTimeoutSeconds: [1, 3_600],
     maxCompileJobs: [1, 32],
     maxFileSizeMB: [1, 2_048],
+    pdfRangeThresholdMB: [1, 2_048],
     historyMaxVersions: [10, 5_000],
     historyMaxStorageMB: [16, 102_400],
     gitOperationTimeoutSeconds: [1, 3_600]
@@ -59,6 +63,11 @@ export function loadConfig(configPathOverride) {
     const compileTimeoutSeconds = integerSetting("latex.compileTimeoutSeconds", process.env.TEXLITE_COMPILE_TIMEOUT, fileConfig.latex?.compileTimeoutSeconds, CONFIG_DEFAULTS.compileTimeoutSeconds, CONFIG_LIMITS.compileTimeoutSeconds);
     const maxCompileJobs = integerSetting("latex.maxCompileJobs", process.env.TEXLITE_MAX_COMPILE_JOBS, fileConfig.latex?.maxCompileJobs, CONFIG_DEFAULTS.maxCompileJobs, CONFIG_LIMITS.maxCompileJobs);
     const maxFileSizeMB = integerSetting("uploads.maxFileSizeMB", process.env.TEXLITE_MAX_UPLOAD_SIZE_MB, fileConfig.uploads?.maxFileSizeMB, CONFIG_DEFAULTS.maxFileSizeMB, CONFIG_LIMITS.maxFileSizeMB);
+    const configuredPdfLoadingStrategy = setting("pdf.loadingStrategy", process.env.TEXLITE_PDF_LOADING_STRATEGY, fileConfig.pdf?.loadingStrategy, CONFIG_DEFAULTS.pdfLoadingStrategy);
+    if (!isPdfLoadingStrategy(configuredPdfLoadingStrategy)) {
+        throw configurationError("pdf.loadingStrategy", `must be one of ${PDF_LOADING_STRATEGIES.join(", ")}; received ${displayValue(configuredPdfLoadingStrategy)}`);
+    }
+    const pdfRangeThresholdMB = integerSetting("pdf.rangeThresholdMB", process.env.TEXLITE_PDF_RANGE_THRESHOLD_MB, fileConfig.pdf?.rangeThresholdMB, CONFIG_DEFAULTS.pdfRangeThresholdMB, CONFIG_LIMITS.pdfRangeThresholdMB);
     const historyMaxVersions = integerSetting("history.maxVersions", process.env.TEXLITE_HISTORY_MAX_VERSIONS, fileConfig.history?.maxVersions, CONFIG_DEFAULTS.historyMaxVersions, CONFIG_LIMITS.historyMaxVersions);
     const historyMaxStorageMB = integerSetting("history.maxStorageMB", process.env.TEXLITE_HISTORY_MAX_STORAGE_MB, fileConfig.history?.maxStorageMB, CONFIG_DEFAULTS.historyMaxStorageMB, CONFIG_LIMITS.historyMaxStorageMB);
     const gitOperationTimeoutSeconds = integerSetting("git.operationTimeoutSeconds", process.env.TEXLITE_GIT_TIMEOUT, fileConfig.git?.operationTimeoutSeconds, CONFIG_DEFAULTS.gitOperationTimeoutSeconds, CONFIG_LIMITS.gitOperationTimeoutSeconds);
@@ -81,6 +90,8 @@ export function loadConfig(configPathOverride) {
         extraArgs: fileConfig.latex?.extraArgs === undefined ? [] : [...fileConfig.latex.extraArgs],
         allowProjectLatexmkrc: fileConfig.latex?.allowProjectLatexmkrc ?? CONFIG_DEFAULTS.allowProjectLatexmkrc,
         maxUploadBytes: maxFileSizeMB * 1024 * 1024,
+        pdfLoadingStrategy: configuredPdfLoadingStrategy,
+        pdfRangeThresholdBytes: pdfRangeThresholdMB * 1024 * 1024,
         historyMaxVersions,
         historyMaxStorageBytes: historyMaxStorageMB * 1024 * 1024,
         git: stringSetting("git.binary", process.env.TEXLITE_GIT, fileConfig.git?.binary, CONFIG_DEFAULTS.git, { min: 1, max: 256 }),
@@ -115,6 +126,10 @@ export function validateConfig(config) {
     validateInteger("latex.compileTimeoutSeconds", config.compileTimeoutMs / 1000, CONFIG_LIMITS.compileTimeoutSeconds);
     validateInteger("latex.maxCompileJobs", config.maxCompileJobs, CONFIG_LIMITS.maxCompileJobs);
     validateInteger("uploads.maxFileSizeMB", config.maxUploadBytes / (1024 * 1024), CONFIG_LIMITS.maxFileSizeMB);
+    if (!isPdfLoadingStrategy(config.pdfLoadingStrategy)) {
+        throw configurationError("pdf.loadingStrategy", `must be one of ${PDF_LOADING_STRATEGIES.join(", ")}`);
+    }
+    validateInteger("pdf.rangeThresholdMB", config.pdfRangeThresholdBytes / (1024 * 1024), CONFIG_LIMITS.pdfRangeThresholdMB);
     validateInteger("history.maxVersions", config.historyMaxVersions, CONFIG_LIMITS.historyMaxVersions);
     validateInteger("history.maxStorageMB", config.historyMaxStorageBytes / (1024 * 1024), CONFIG_LIMITS.historyMaxStorageMB);
     validateInteger("git.operationTimeoutSeconds", config.gitOperationTimeoutMs / 1000, CONFIG_LIMITS.gitOperationTimeoutSeconds);
@@ -122,6 +137,9 @@ export function validateConfig(config) {
 function isEngine(value) {
     return typeof value === "string" && LATEX_ENGINES.includes(value);
 }
+function isPdfLoadingStrategy(value) {
+    return typeof value === "string" && PDF_LOADING_STRATEGIES.includes(value);
+}
 function readConfigFile(configPath) {
     if (!fs.existsSync(configPath))
         return {};
@@ -149,6 +167,12 @@ function validateFileConfig(config) {
     optionalString(storage?.dataDir, "storage.dataDir", { min: 1, max: 4_096 });
     const uploads = optionalSection(config.uploads, "uploads");
     optionalInteger(uploads?.maxFileSizeMB, "uploads.maxFileSizeMB", CONFIG_LIMITS.maxFileSizeMB);
+    const pdf = optionalSection(config.pdf, "pdf");
+    if (pdf && Object.prototype.hasOwnProperty.call(pdf, "loadingStrategy")
+        && !isPdfLoadingStrategy(pdf.loadingStrategy)) {
+        throw configurationError("pdf.loadingStrategy", `must be one of ${PDF_LOADING_STRATEGIES.join(", ")}; received ${displayValue(pdf.loadingStrategy)}`);
+    }
+    optionalInteger(pdf?.rangeThresholdMB, "pdf.rangeThresholdMB", CONFIG_LIMITS.pdfRangeThresholdMB);
     const history = optionalSection(config.history, "history");
     optionalInteger(history?.maxVersions, "history.maxVersions", CONFIG_LIMITS.historyMaxVersions);
     optionalInteger(history?.maxStorageMB, "history.maxStorageMB", CONFIG_LIMITS.historyMaxStorageMB);

package/dist/server/environment.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { httpError } from "./http.js";
 import { detachedProcessGroup, killProcessGroup } from "./processTree.js";
 export async function assertEnvironment(config) {
     const commands = [
@@ -26,7 +27,10 @@ export async function assertGitAvailable(config) {
     const result = await commandVersion(item.command, Math.min(config.gitOperationTimeoutMs, 10_000));
     if (result.error || result.status !== 0) {
         const detail = result.error || result.stderr.trim() || `exit ${result.status ?? "unknown"}`;
-        throw Object.assign(new Error(`Git integration is unavailable: could not run the configured command "${item.command}" (${detail}). Install Git or correct git.binary and try again.`), { statusCode: 503, code: "GIT_UNAVAILABLE" });
+        // Command output can reveal host paths; it remains a startup diagnostic,
+        // while API clients receive the localized, stable error code.
+        void detail;
+        throw httpError(503, "GIT_UNAVAILABLE");
     }
     const version = `${result.stdout || result.stderr}`.trim().split("\n")[0]?.slice(0, 160) || "available";
     return { ...item, version };

package/dist/server/files.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { httpError } from "./http.js";
 export function projectRoot(config, projectId) {
     return path.join(config.projectsDir, projectId);
 }
@@ -49,14 +50,14 @@ export async function duplicateProjectFiles(config, sourceProjectId, targetProje
 }
 export function safeRelativePath(input) {
     if (!input || input.includes("\0") || path.isAbsolute(input)) {
-        throw Object.assign(new Error("无效的文件路径"), { statusCode: 400, code: "INVALID_PATH" });
+        throw httpError(400, "INVALID_PATH");
     }
     const normalized = path.posix.normalize(input.replaceAll("\\", "/"));
     if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
-        throw Object.assign(new Error("无效的文件路径"), { statusCode: 400, code: "INVALID_PATH" });
+        throw httpError(400, "INVALID_PATH");
     }
     if (normalized.split("/").some((segment) => segment.toLocaleLowerCase() === ".git")) {
-        throw Object.assign(new Error(".git 是系统保留目录"), { statusCode: 400, code: "RESERVED_PATH" });
+        throw httpError(400, "RESERVED_PATH");
     }
     return normalized;
 }
@@ -64,12 +65,12 @@ export function safeRelativePath(input) {
 export function safePathSegment(input) {
     const name = input.trim();
     if (!name || name.includes("\0") || name.includes("/") || name.includes("\\")) {
-        throw Object.assign(new Error("无效的文件名"), { statusCode: 400, code: "INVALID_PATH" });
+        throw httpError(400, "INVALID_PATH");
     }
     return safeRelativePath(name);
 }
 export function symbolicLinkError(relativePath) {
-    return Object.assign(new Error(`项目源文件包含不受支持的符号链接，已拒绝访问：${relativePath || "source"}`), { statusCode: 409, code: "SYMLINK_FORBIDDEN" });
+    return httpError(409, "SYMLINK_FORBIDDEN", { path: relativePath || "source" });
 }
 /**
  * Check every existing component below the project directory without
@@ -256,7 +257,7 @@ export function removeProjectDirectory(config, projectId) {
     catch {
         fs.rmSync(root, { recursive: true, force: true });
         if (fs.existsSync(root)) {
-            throw new Error(`无法清理项目目录: ${root}`);
+            throw new Error(`Unable to remove project directory: ${root}`);
         }
     }
 }