texlite 0.9.0 → 0.9.2

package/dist/server/routes/projects.js

@@ -10,9 +10,12 @@ import { lucideIconSvg, resolveLucideIconName } from "../lucideIcons.js";
 import { accessibleProject, canEdit } from "../projects.js";
 import { writeProjectArchive } from "../archive.js";
 import { extractProjectZip, ZipValidationError } from "../zip.js";
-import { HarperUnavailableError } from "../harper.js";
+import { HarperLintSupersededError, HarperUnavailableError } from "../harper.js";
+import { digestToken } from "../security.js";
+import { supportsWritingChecks } from "../../shared/writingChecks.js";
 import { unreadMentionCountsForProjects } from "../commentMentions.js";
 import { commentsSummaryForProject, commentsSummaryForProjects, dictionaryWord, escapeLikePattern, now, projectJson, requireProjectOwnerPermission, tagColors, tagsForProject, tagsForProjects, text } from "./projectShared.js";
+const clientIdPattern = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i;
 /** Register project catalog, metadata, archive, dictionary, tag, export, and deletion routes. */
 export function registerProjectCatalogRoutes(app, context) {
     const { config, db, collaboration, projectMutations, latexCompletions, projectOutlines, harper, recordHistory } = context;
@@ -362,15 +365,49 @@ export function registerProjectCatalogRoutes(app, context) {
         if (!accessibleProject(db, id, user))
             return apiError(reply, 404, "PROJECT_NOT_FOUND");
         const body = request.body;
-        if (typeof body?.source !== "string" || typeof body.path !== "string")
+        const source = body?.source;
+        const sourcePath = body?.path;
+        const clientId = body?.clientId;
+        const sequence = body?.sequence;
+        if (typeof source !== "string" || typeof sourcePath !== "string") {
             return apiError(reply, 400, "SPELLCHECK_SOURCE_INVALID");
-        if (Buffer.byteLength(body.source, "utf8") > maxCollaborativeFileBytes(config)) {
+        }
+        // Accept already-open clients during a rolling update. Current clients
+        // pair a page-local UUID with a monotonically increasing sequence so a
+        // delayed HTTP request cannot replace a newer queued check.
+        if (clientId !== undefined && (typeof clientId !== "string" || !clientIdPattern.test(clientId))) {
+            return apiError(reply, 400, "SPELLCHECK_SOURCE_INVALID");
+        }
+        if (sequence !== undefined && (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence <= 0 || clientId === undefined)) {
+            return apiError(reply, 400, "SPELLCHECK_SOURCE_INVALID");
+        }
+        if (Buffer.byteLength(source, "utf8") > maxCollaborativeFileBytes(config)) {
             return apiError(reply, 413, "SPELLCHECK_SOURCE_TOO_LARGE");
         }
+        let filePath;
         try {
-            return { lints: await harper.lint(body.source, body.path) };
+            filePath = safeRelativePath(sourcePath);
+        }
+        catch {
+            return apiError(reply, 400, "SPELLCHECK_SOURCE_INVALID");
+        }
+        // Bibliography files are structured reference data rather than prose.
+        // Keep this server-side guard for legacy clients and direct API callers.
+        if (!supportsWritingChecks(filePath))
+            return { lints: [] };
+        // A login session is shared by browser tabs. Pair the authenticated user
+        // with the page-local client ID so each new editor can replace only its
+        // own obsolete waiting work. Legacy clients retain their former session
+        // grouping until their page is refreshed.
+        const laneClientId = clientId ?? `legacy:${digestToken(request.cookies.texlite_session ?? "")}`;
+        const lane = `${id}\0${user.id}\0${laneClientId}\0${filePath}`;
+        try {
+            return { lints: await harper.lint(source, filePath, lane, typeof sequence === "number" ? sequence : undefined) };
         }
         catch (error) {
+            if (error instanceof HarperLintSupersededError) {
+                return apiError(reply, 409, "SPELLCHECK_SUPERSEDED");
+            }
             // A missing optional command is an expected fallback condition. Keep it
             // out of normal logs while preserving diagnostics for an actual failure.
             if (error instanceof HarperUnavailableError)

package/dist/server/routes/system.js

@@ -8,6 +8,7 @@ export function registerSystemRoutes(app, context) {
     app.get("/api/config", async () => ({
         siteName: config.siteName,
         adminEmail: config.adminEmail,
+        basePath: config.basePath,
         minPasswordLength: MIN_PASSWORD_LENGTH,
         maxCitationBibtexBytes: MAX_CITATION_BIBTEX_BYTES,
         maxUploadSizeMB: Math.floor(config.maxUploadBytes / 1024 / 1024),

package/dist/server/zip.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import yauzl from "yauzl";
+import { hasLatexDocumentClass } from "../shared/latexRoot.js";
 import { assertNoSymbolicLinks, safeRelativePath } from "./files.js";
 const MAX_ENTRIES = 1_000;
 const MAX_TOTAL_BYTES = 200 * 1024 * 1024;
@@ -180,22 +181,7 @@ function discoverMainFile(root, files) {
     }) ?? "";
 }
 export function hasDocumentClass(source) {
-    const withoutComments = source.split(/(?<=\n)/).map((line) => {
-        for (let index = 0; index < line.length; index += 1) {
-            if (line[index] !== "%")
-                continue;
-            let slashes = 0;
-            for (let cursor = index - 1; cursor >= 0 && line[cursor] === "\\"; cursor -= 1)
-                slashes += 1;
-            if (slashes % 2 === 0)
-                return `${line.slice(0, index)}${line.endsWith("\n") ? "\n" : ""}`;
-        }
-        return line;
-    }).join("");
-    const withoutVerbatim = withoutComments
-        .replace(/\\verb\*?([^\s]).*?\1/g, "")
-        .replace(/\\begin\{(?:verbatim\*?|Verbatim|lstlisting|minted)\}(?:\[[^\]]*\])?[\s\S]*?\\end\{(?:verbatim\*?|Verbatim|lstlisting|minted)\}/g, "");
-    return /\\documentclass\s*(?:\[[^\]]*\]\s*)?\{/.test(withoutVerbatim);
+    return hasLatexDocumentClass(source);
 }
 function formatMB(bytes) {
     return Math.floor(bytes / 1024 / 1024);

package/dist/shared/basePath.js

@@ -0,0 +1,44 @@
+export const ROOT_BASE_PATH = "/";
+/**
+ * Normalize a configured URL path prefix. Root is represented as `/`; every
+ * other value starts with one slash and has no trailing slash.
+ */
+export function normalizeBasePath(value) {
+    const trimmed = value.trim();
+    if (trimmed === ROOT_BASE_PATH)
+        return ROOT_BASE_PATH;
+    const normalized = trimmed.replace(/\/+$/, "");
+    if (!normalized.startsWith("/") || normalized.includes("//"))
+        return null;
+    const segments = normalized.slice(1).split("/");
+    if (!segments.length || segments.some((segment) => segment === "." || segment === ".." || !/^[A-Za-z0-9._~-]+$/.test(segment)))
+        return null;
+    return normalized;
+}
+/** Return the prefix used when registering or composing a path. */
+export function basePathPrefix(basePath) {
+    return basePath === ROOT_BASE_PATH ? "" : basePath;
+}
+/** Prefix an origin-local absolute path with the configured application path. */
+export function withBasePath(basePath, pathname) {
+    if (!pathname.startsWith("/"))
+        throw new Error(`Application path must start with /: ${pathname}`);
+    const prefix = basePathPrefix(basePath);
+    if (!prefix)
+        return pathname;
+    return pathname === "/" ? `${prefix}/` : `${prefix}${pathname}`;
+}
+/** Remove the configured prefix, or return null when a path belongs elsewhere. */
+export function withoutBasePath(basePath, pathname) {
+    const prefix = basePathPrefix(basePath);
+    if (!prefix)
+        return pathname;
+    if (pathname === prefix || pathname === `${prefix}/`)
+        return "/";
+    if (!pathname.startsWith(`${prefix}/`))
+        return null;
+    return pathname.slice(prefix.length) || "/";
+}
+export function basePathHref(basePath) {
+    return basePath === ROOT_BASE_PATH ? ROOT_BASE_PATH : `${basePath}/`;
+}

package/dist/shared/bibtexReferences.js

@@ -0,0 +1,135 @@
+/**
+ * Lightweight BibTeX entry-key scanner for server-side completion and source
+ * navigation. The browser editor uses the full Lezer grammar; this companion
+ * deliberately only finds complete entry boundaries and keys, so server code
+ * does not need to load a browser-oriented CodeMirror parser.
+ */
+import { isLatexCommentStart, skipLatexComment, skipLatexTrivia } from "./latexScanner.js";
+function readBibtexBlock(source, start) {
+    const opening = source[start];
+    const closing = opening === "{" ? "}" : ")";
+    if (opening !== "{" && opening !== "(")
+        return null;
+    // Braced and parenthesized BibTeX entries have different nesting rules. A
+    // quote is ordinary content inside a braced entry, while a parenthesized
+    // entry must protect its closing paren from braced and quoted values.
+    let depth = 0;
+    let braceDepth = 0;
+    let quoted = false;
+    for (let index = start; index < source.length; index += 1) {
+        const character = source[index];
+        if (character === "\\" && index + 1 < source.length) {
+            index += 1;
+            continue;
+        }
+        if (opening === "{") {
+            if (character === "{") {
+                depth += 1;
+                continue;
+            }
+            if (character !== "}")
+                continue;
+            depth -= 1;
+            if (depth === 0) {
+                return { from: start, to: index + 1, contentFrom: start + 1, contentTo: index };
+            }
+            continue;
+        }
+        if (quoted) {
+            if (character === "\"")
+                quoted = false;
+            continue;
+        }
+        if (braceDepth > 0) {
+            if (character === "{")
+                braceDepth += 1;
+            else if (character === "}")
+                braceDepth -= 1;
+            continue;
+        }
+        if (character === "{") {
+            braceDepth = 1;
+            continue;
+        }
+        if (character === "\"") {
+            quoted = true;
+            continue;
+        }
+        if (character === "(") {
+            depth += 1;
+            continue;
+        }
+        if (character !== closing)
+            continue;
+        depth -= 1;
+        if (depth === 0) {
+            return { from: start, to: index + 1, contentFrom: start + 1, contentTo: index };
+        }
+    }
+    return null;
+}
+function bibtexKeyRange(source, entry) {
+    let from = entry.contentFrom;
+    while (from < entry.contentTo && /\s/.test(source[from]))
+        from += 1;
+    if (from >= entry.contentTo)
+        return null;
+    let to = from;
+    while (to < entry.contentTo && source[to] !== "," && !/\s/.test(source[to]))
+        to += 1;
+    let trimmedTo = to;
+    while (trimmedTo > from && /\s/.test(source[trimmedTo - 1]))
+        trimmedTo -= 1;
+    if (trimmedTo <= from)
+        return null;
+    const separator = skipLatexTrivia(source, to);
+    if (separator < entry.contentTo && source[separator] !== ",")
+        return null;
+    return { key: source.slice(from, trimmedTo), from, to: trimmedTo };
+}
+/**
+ * Find ordinary BibTeX/BibLaTeX entry keys. `@string`, `@preamble`, and
+ * `@comment` are intentionally skipped because their leading token is not a
+ * citeable entry key.
+ */
+export function findBibtexEntryKeys(source) {
+    const entries = [];
+    let index = 0;
+    while (index < source.length) {
+        // Percent signs are comments at top level. Once inside an entry a percent
+        // may be part of a braced URL (for example `%20`), so the block reader
+        // must receive the original source unchanged.
+        if (isLatexCommentStart(source, index)) {
+            index = skipLatexComment(source, index);
+            continue;
+        }
+        if (source[index] !== "@") {
+            index += 1;
+            continue;
+        }
+        let typeEnd = index + 1;
+        while (typeEnd < source.length && /[A-Za-z]/.test(source[typeEnd]))
+            typeEnd += 1;
+        if (typeEnd === index + 1) {
+            index += 1;
+            continue;
+        }
+        let opening = typeEnd;
+        while (opening < source.length && /\s/.test(source[opening]))
+            opening += 1;
+        const block = readBibtexBlock(source, opening);
+        if (!block) {
+            index = typeEnd;
+            continue;
+        }
+        const type = source.slice(index + 1, typeEnd).toLowerCase();
+        if (type !== "string" && type !== "preamble" && type !== "comment") {
+            const key = bibtexKeyRange(source, block);
+            if (key)
+                entries.push({ ...key, entryFrom: index, entryTo: block.to });
+        }
+        // Do not scan @-looking text inside an already complete entry.
+        index = block.to;
+    }
+    return entries;
+}

package/dist/shared/latexCommandSnippets.js

@@ -0,0 +1,91 @@
+function skipWhitespace(source, position) {
+    let cursor = position;
+    while (/[ \t\r\n]/.test(source[cursor] ?? ""))
+        cursor += 1;
+    return cursor;
+}
+export function readBalancedLatexArgument(source, start, open = "{", close = "}") {
+    const from = skipWhitespace(source, start);
+    if (source[from] !== open)
+        return null;
+    let depth = 1;
+    for (let cursor = from + 1; cursor < source.length; cursor += 1) {
+        if (source[cursor] === "\\") {
+            cursor += 1;
+            continue;
+        }
+        if (source[cursor] === open)
+            depth += 1;
+        else if (source[cursor] === close && --depth === 0) {
+            return { from, to: cursor + 1, content: source.slice(from + 1, cursor) };
+        }
+    }
+    return null;
+}
+export function commandSnippet(name, arguments_) {
+    if (arguments_.length === 0)
+        return undefined;
+    return name + arguments_.map((argument, index) => {
+        const placeholder = `\${${index + 1}}`;
+        return argument.optional ? `[${placeholder}]` : `{${placeholder}}`;
+    }).join("");
+}
+export function newCommandArguments(argumentCount, hasDefault) {
+    if (!Number.isFinite(argumentCount) || argumentCount <= 0)
+        return [];
+    if (!hasDefault)
+        return Array.from({ length: argumentCount }, () => ({ optional: false }));
+    return [{ optional: true }, ...Array.from({ length: Math.max(0, argumentCount - 1) }, () => ({ optional: false }))];
+}
+/**
+ * Interpret only xparse forms that have a safe ordinary LaTeX insertion. For
+ * delimiter, verbatim, star, and token arguments, omit a snippet rather than
+ * generate invalid syntax.
+ */
+export function xparseCommandArguments(specification) {
+    const result = [];
+    for (let cursor = 0; cursor < specification.length;) {
+        const character = specification[cursor];
+        if (/[ \t\r\n+\-!]/.test(character)) {
+            cursor += 1;
+            continue;
+        }
+        if (character === "m") {
+            result.push({ optional: false });
+            cursor += 1;
+            continue;
+        }
+        if (character === "o") {
+            result.push({ optional: true });
+            cursor += 1;
+            continue;
+        }
+        if (character === "O") {
+            const defaultValue = readBalancedLatexArgument(specification, cursor + 1);
+            if (!defaultValue)
+                return null;
+            result.push({ optional: true });
+            cursor = defaultValue.to;
+            continue;
+        }
+        return null;
+    }
+    return result;
+}
+const xparseDeclaration = /\\(?:NewDocumentCommand|RenewDocumentCommand|ProvideDocumentCommand|DeclareDocumentCommand|DeclareExpandableDocumentCommand|RenewExpandableDocumentCommand|ProvideExpandableDocumentCommand)\b/g;
+export function xparseCommandDefinitions(source) {
+    const definitions = [];
+    for (const match of source.matchAll(xparseDeclaration)) {
+        const target = readBalancedLatexArgument(source, match.index + match[0].length);
+        if (!target)
+            continue;
+        const name = /^\s*\\([A-Za-z@][A-Za-z@0-9:_]*)\s*$/.exec(target.content)?.[1];
+        if (!name)
+            continue;
+        const specification = readBalancedLatexArgument(source, target.to);
+        if (!specification)
+            continue;
+        definitions.push({ name, specification: specification.content });
+    }
+    return definitions;
+}

package/dist/shared/latexDependencies.js

@@ -0,0 +1,71 @@
+/** Lightweight extraction of source and bibliography dependencies from TeX. */
+import { forEachLatexCommand, readLatexMandatoryArguments } from "./latexScanner.js";
+function pathRanges(source, argument, splitOnComma) {
+    const paths = [];
+    let segmentStart = argument.contentFrom;
+    for (let index = argument.contentFrom; index <= argument.contentTo; index += 1) {
+        if (index !== argument.contentTo && (!splitOnComma || source[index] !== ","))
+            continue;
+        let from = segmentStart;
+        let to = index;
+        while (from < to && /\s/.test(source[from]))
+            from += 1;
+        while (to > from && /\s/.test(source[to - 1]))
+            to -= 1;
+        if (to > from)
+            paths.push({ path: source.slice(from, to), command: "", from, to });
+        segmentStart = index + 1;
+    }
+    return paths;
+}
+/**
+ * Find source files pulled into a LaTeX document. Paths intentionally remain
+ * raw: project-level code is responsible for resolving them safely.
+ */
+export function findLatexSourceIncludes(source) {
+    const includes = [];
+    forEachLatexCommand(source, (command) => {
+        const name = command.name.toLowerCase();
+        if (name === "input" || name === "include" || name === "subfile") {
+            const argument = readLatexMandatoryArguments(source, command.to, 1)[0];
+            if (!argument)
+                return;
+            for (const include of pathRanges(source, argument, false))
+                includes.push({ ...include, command: command.name });
+            return;
+        }
+        if (name !== "import" && name !== "subimport" && name !== "includefrom" && name !== "inputfrom")
+            return;
+        const argumentsFound = readLatexMandatoryArguments(source, command.to, 2);
+        if (argumentsFound.length !== 2)
+            return;
+        const directory = source.slice(argumentsFound[0].contentFrom, argumentsFound[0].contentTo).trim();
+        const file = source.slice(argumentsFound[1].contentFrom, argumentsFound[1].contentTo).trim();
+        if (!directory || !file)
+            return;
+        const separator = directory.endsWith("/") ? "" : "/";
+        includes.push({
+            path: directory + separator + file,
+            command: command.name,
+            from: argumentsFound[1].contentFrom,
+            to: argumentsFound[1].contentTo
+        });
+    });
+    return includes;
+}
+/** Find bibliography resources declared by a LaTeX document. */
+export function findLatexBibliographyFiles(source) {
+    const files = [];
+    forEachLatexCommand(source, (command) => {
+        const name = command.name.toLowerCase();
+        if (name !== "bibliography" && name !== "addbibresource" && name !== "addglobalbib" && name !== "addsectionbib")
+            return;
+        const argument = readLatexMandatoryArguments(source, command.to, 1)[0];
+        if (!argument)
+            return;
+        const splitOnComma = name === "bibliography";
+        for (const file of pathRanges(source, argument, splitOnComma))
+            files.push({ ...file, command: command.name });
+    });
+    return files;
+}

package/dist/shared/latexLiterals.js

@@ -0,0 +1,215 @@
+// Literal TeX syntax used as opaque editor regions. `alltt` does permit a
+// subset of TeX commands, but treating its raw body as opaque prevents its
+// delimiters from leaking into ordinary source highlighting and tooling.
+export const literalEnvironmentNames = [
+    "verbatim", "verbatim*", "Verbatim", "BVerbatim", "LVerbatim", "SaveVerbatim", "VerbatimOut",
+    "bverbatim", "bverbatim*", "lverbatim", "lverbatim*", "saveverbatim", "saveverbatim*", "verbatimout",
+    "verbatimwrite", "lstlisting", "lstlisting*", "minted", "minted*", "tcblisting", "tcblisting*", "pygmented", "alltt",
+    "filecontents", "filecontents*", "luacode", "luacodestar", "comment"
+];
+const literalEnvironments = new Set(literalEnvironmentNames);
+export function isLatexLiteralEnvironment(name) {
+    return literalEnvironments.has(name);
+}
+function skipOptionalArgument(source, position, end) {
+    if (source[position] !== "[")
+        return position;
+    let depth = 1;
+    for (let index = position + 1; index < end; index += 1) {
+        if (source[index] === "\\") {
+            index += 1;
+            continue;
+        }
+        if (source[index] === "[")
+            depth += 1;
+        if (source[index] === "]") {
+            depth -= 1;
+            if (depth === 0)
+                return index + 1;
+        }
+    }
+    return null;
+}
+function skipRequiredArgument(source, position, end) {
+    if (source[position] !== "{")
+        return null;
+    let depth = 1;
+    for (let index = position + 1; index < end; index += 1) {
+        if (source[index] === "\\") {
+            index += 1;
+            continue;
+        }
+        if (source[index] === "{")
+            depth += 1;
+        if (source[index] === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return index + 1;
+        }
+    }
+    return null;
+}
+function inlineLatexLiteralSpan(source, start, end = source.length) {
+    const newline = source.indexOf("\n", start);
+    if (newline >= 0)
+        end = Math.min(end, newline);
+    const command = /^\\(verb\*?|Verb\*?|lstinline\*?|mintinline\*?)(?![A-Za-z@])/.exec(source.slice(start, end));
+    if (!command)
+        return null;
+    const name = command[1].replace(/\*$/, "");
+    let position = start + command[0].length;
+    if (name !== "verb") {
+        const optionalEnd = skipOptionalArgument(source, position, end);
+        if (optionalEnd === null)
+            return null;
+        position = optionalEnd;
+    }
+    if (name === "mintinline") {
+        const languageEnd = skipRequiredArgument(source, position, end);
+        if (languageEnd === null)
+            return null;
+        position = languageEnd;
+    }
+    const delimiter = source[position];
+    if (!delimiter || /\s/.test(delimiter))
+        return null;
+    // For verb, '{' is still a symmetric delimiter, not an argument opener.
+    if (delimiter === "{" && name !== "verb") {
+        const requiredEnd = skipRequiredArgument(source, position, end);
+        return { end: requiredEnd ?? end, closed: requiredEnd !== null };
+    }
+    const closing = source.indexOf(delimiter, position + 1);
+    if (closing < 0 || closing >= end)
+        return { end, closed: false };
+    return { end: closing + 1, closed: true };
+}
+export function inlineLatexLiteralEnd(source, start, end = source.length) {
+    return inlineLatexLiteralSpan(source, start, end)?.end ?? null;
+}
+export function literalEnvironmentEnd(source, start, name) {
+    const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(String.raw `\\end\s*\{\s*${escapedName}\s*\}`, "g");
+    pattern.lastIndex = start;
+    const match = pattern.exec(source);
+    return match ? { from: match.index, to: match.index + match[0].length } : null;
+}
+function isEscaped(source, index) {
+    let backslashes = 0;
+    for (let cursor = index - 1; cursor >= 0 && source[cursor] === "\\"; cursor -= 1)
+        backslashes += 1;
+    return backslashes % 2 === 1;
+}
+function commandEnd(source, start) {
+    let cursor = start + 1;
+    if (/[A-Za-z@]/.test(source[cursor] ?? "")) {
+        while (/[A-Za-z@]/.test(source[cursor] ?? ""))
+            cursor += 1;
+        if (source[cursor] === "*")
+            cursor += 1;
+        return cursor;
+    }
+    return Math.min(source.length, cursor + 1);
+}
+function literalEnvironmentBegin(source, start) {
+    const match = /^\\begin\s*\{\s*([A-Za-z0-9@:_*.\-]+)\s*\}/.exec(source.slice(start));
+    if (!match || !isLatexLiteralEnvironment(match[1]))
+        return null;
+    return { name: match[1], to: start + match[0].length };
+}
+/**
+ * Return whether a position is inside a TeX comment or one of the literal
+ * code forms shared by editor tooling. Positions after a completed literal are
+ * deliberately treated as normal source, including when its delimiter is '%'.
+ */
+export function latexOpaqueContextAt(source, position) {
+    const target = Math.max(0, Math.min(source.length, position));
+    for (let cursor = 0; cursor < target;) {
+        if (source[cursor] === "%" && !isEscaped(source, cursor)) {
+            const newline = source.indexOf("\n", cursor);
+            const end = newline < 0 ? source.length : newline;
+            if (target <= end)
+                return "comment";
+            cursor = end + 1;
+            continue;
+        }
+        if (source[cursor] !== "\\" || isEscaped(source, cursor)) {
+            cursor += 1;
+            continue;
+        }
+        const inline = inlineLatexLiteralSpan(source, cursor);
+        if (inline !== null) {
+            if (target < inline.end || (!inline.closed && target <= inline.end))
+                return "literal";
+            cursor = inline.end;
+            continue;
+        }
+        const environment = literalEnvironmentBegin(source, cursor);
+        if (environment) {
+            const close = literalEnvironmentEnd(source, environment.to, environment.name);
+            const end = close?.to ?? source.length;
+            if (target < end || (!close && target <= end))
+                return "literal";
+            cursor = end;
+            continue;
+        }
+        cursor = commandEnd(source, cursor);
+    }
+    return null;
+}
+function maskRange(source, from, to) {
+    return source.slice(from, to).replace(/[^\r\n]/g, " ");
+}
+/** Mask ordinary TeX comments while preserving every source offset. */
+export function maskLatexComments(source) {
+    const characters = source.split("");
+    for (let cursor = 0; cursor < source.length; cursor += 1) {
+        if (source[cursor] !== "%" || isEscaped(source, cursor))
+            continue;
+        const newline = source.indexOf("\n", cursor);
+        const end = newline < 0 ? source.length : newline;
+        for (let index = cursor; index < end; index += 1)
+            characters[index] = " ";
+        cursor = end;
+    }
+    return characters.join("");
+}
+/**
+ * Mask literal source while preserving offsets and line structure. Callers can
+ * then use lightweight regular expressions without learning project commands
+ * declared inside listings or verbatim examples.
+ */
+export function maskLatexLiteralContent(source) {
+    let result = "";
+    let cursor = 0;
+    while (cursor < source.length) {
+        if (source[cursor] === "%" && !isEscaped(source, cursor)) {
+            const newline = source.indexOf("\n", cursor);
+            const end = newline < 0 ? source.length : newline;
+            result += source.slice(cursor, end);
+            cursor = end;
+            continue;
+        }
+        if (source[cursor] !== "\\" || isEscaped(source, cursor)) {
+            result += source[cursor];
+            cursor += 1;
+            continue;
+        }
+        const inlineEnd = inlineLatexLiteralEnd(source, cursor);
+        if (inlineEnd !== null) {
+            result += maskRange(source, cursor, inlineEnd);
+            cursor = inlineEnd;
+            continue;
+        }
+        const environment = literalEnvironmentBegin(source, cursor);
+        if (environment) {
+            const close = literalEnvironmentEnd(source, environment.to, environment.name);
+            const end = close?.to ?? source.length;
+            result += maskRange(source, cursor, end);
+            cursor = end;
+            continue;
+        }
+        result += source[cursor];
+        cursor += 1;
+    }
+    return result;
+}