typst-mcp 1.1.0 → 1.3.0

package/dist/client/typst-client.js

@@ -3,14 +3,15 @@ import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { TypstAuthManager } from "./auth.js";
 import { TypstLoadError, formatUnknownError } from "./errors.js";
-import { captureBrowserPreviewScreenshot, captureWorkspacePageScreenshots, compileWorkspaceDiagnostics, compileWorkspacePdf, parseShortDiagnostics, resolveTypstBinary, } from "./compiler.js";
-import { CREATE_PROJECT_MUTATION, DASHBOARD_CONTENT_QUERY, DELETE_FILES_MUTATION, DELETE_PROJECT_MUTATION, PROJECT_FILES_QUERY, UPDATE_FILES_MUTATION, } from "../protocol/graphql.js";
+import { captureBrowserPreviewScreenshot, captureWebDiagnostics, captureWorkspacePageScreenshots, compileWorkspaceDiagnostics, compileWorkspacePdf, hasTypstBinary, parseShortDiagnostics, resolveTypstBinary, } from "./compiler.js";
+import { CREATE_PROJECT_MUTATION, DASHBOARD_CONTENT_QUERY, DELETE_FILES_MUTATION, DELETE_PROJECT_MUTATION, EDIT_PROJECT_MUTATION, PROJECT_FILES_QUERY, UPDATE_FILES_MUTATION, } from "../protocol/graphql.js";
 import { decodeYjsText, editYjsText, replaceYjsText, } from "../protocol/yjs-doc.js";
 import { decodeMessage, encodeMessage, MessageKind, } from "../protocol/ws-codec.js";
-import { truncateHead, formatSize, } from "../utils/truncate.js";
+import { readTextContent, validateReadOptions, hashText } from "../protocol/read-content.js";
+import { validateEdits } from "../protocol/edit-diff.js";
 import { detectSupportedImageMimeType } from "../utils/mime.js";
 import { withFileMutationQueue } from "../utils/file-mutation-queue.js";
-import { matchGlob, searchInContent, replaceInContent, } from "../protocol/search-replace.js";
+import { matchGlob, searchInContent, replaceBatchInContent, resolveReplacementRules, } from "../protocol/search-replace.js";
 export { TypstLoadError, resolveTypstBinary };
 const URL_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 export function generateClientId(size = 8) {
@@ -220,90 +221,14 @@ export class TypstCloudClient {
         return new Uint8Array(await response.arrayBuffer());
     }
     async readFile(projectId, fileIdOrPath, options) {
+        validateReadOptions(options ?? {});
         const file = await this.resolveFile(projectId, fileIdOrPath);
         if (file.isMultiplayable) {
             const yjsBytes = await this.downloadFileYjs(projectId, file.id);
-            const text = decodeYjsText(yjsBytes);
-            const allLines = text.split("\n");
-            const totalLines = allLines.length;
-            if (options?.offset !== undefined && options.offset > totalLines) {
-                throw new Error(`Offset ${options.offset} is beyond end of file (${totalLines} lines total)`);
-            }
-            const startLine = options?.offset ? Math.max(0, options.offset - 1) : 0;
-            const startLineDisplay = startLine + 1;
-            let selectedContent;
-            let userLimitedLines;
-            if (options?.limit !== undefined) {
-                const endLine = Math.min(startLine + options.limit, totalLines);
-                selectedContent = allLines.slice(startLine, endLine).join("\n");
-                userLimitedLines = endLine - startLine;
-            }
-            else {
-                selectedContent = allLines.slice(startLine).join("\n");
-            }
-            const truncation = truncateHead(selectedContent, {
-                maxLines: options?.maxLines,
-                maxBytes: options?.maxBytes,
-            });
-            let outputText;
-            let endLineDisplay = startLineDisplay;
-            if (truncation.firstLineExceedsLimit) {
-                const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine] ?? "", "utf-8"));
-                outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(truncation.maxBytes)} limit]`;
-            }
-            else if (truncation.truncated) {
-                endLineDisplay = startLineDisplay + truncation.outputLines - 1;
-                const nextOffset = endLineDisplay + 1;
-                let body = truncation.content;
-                if (options?.lineNumbers) {
-                    const lines = body.split("\n");
-                    const width = String(endLineDisplay).length;
-                    body = lines
-                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
-                        .join("\n");
-                }
-                if (truncation.truncatedBy === "lines") {
-                    outputText = `${body}\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
-                }
-                else {
-                    outputText = `${body}\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
-                }
-            }
-            else if (userLimitedLines !== undefined &&
-                startLine + userLimitedLines < totalLines) {
-                endLineDisplay = startLine + userLimitedLines;
-                const remaining = totalLines - endLineDisplay;
-                const nextOffset = endLineDisplay + 1;
-                let body = truncation.content;
-                if (options?.lineNumbers) {
-                    const lines = body.split("\n");
-                    const width = String(endLineDisplay).length;
-                    body = lines
-                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
-                        .join("\n");
-                }
-                outputText = `${body}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
-            }
-            else {
-                endLineDisplay = totalLines;
-                let body = truncation.content;
-                if (options?.lineNumbers) {
-                    const lines = body.split("\n");
-                    const width = String(startLineDisplay + lines.length - 1).length;
-                    body = lines
-                        .map((line, idx) => `${String(startLineDisplay + idx).padStart(width, " ")} | ${line}`)
-                        .join("\n");
-                }
-                outputText = body;
-            }
             return {
                 file,
-                content: outputText,
                 encoding: "utf-8",
-                totalLines,
-                startLine: startLineDisplay,
-                endLine: endLineDisplay,
-                truncation: truncation.truncated ? truncation : undefined,
+                ...readTextContent(decodeYjsText(yjsBytes), options),
             };
         }
         const blob = await this.downloadFileBlob(projectId, file.id);
@@ -433,15 +358,20 @@ export class TypstCloudClient {
                 files.find((f) => f.name === normalized || f.name === filePathOrId);
             if (existing) {
                 if (existing.isMultiplayable) {
-                    const remote = await this.downloadFileYjs(projectId, existing.id);
-                    const { encodedUpdate } = replaceYjsText(remote, content);
-                    const { syncChannel } = await this.saveYjsUpdate(projectId, existing.id, encodedUpdate, options?.preferWebSocket ?? true);
-                    return {
-                        file: existing,
-                        created: false,
-                        bytesWritten: Buffer.byteLength(content, "utf8"),
-                        syncChannel,
+                    const replaceExisting = async () => {
+                        const remote = await this.downloadFileYjs(projectId, existing.id);
+                        const { encodedUpdate } = replaceYjsText(remote, content);
+                        const { syncChannel } = await this.saveYjsUpdate(projectId, existing.id, encodedUpdate, options?.preferWebSocket ?? true);
+                        return {
+                            file: existing,
+                            created: false,
+                            bytesWritten: Buffer.byteLength(content, "utf8"),
+                            syncChannel,
+                        };
                     };
+                    // Path-based writes must use the same ID lock as surgical edits.
+                    return normalized === existing.id ? replaceExisting() :
+                        withFileMutationQueue(`${projectId}:${existing.id}`, replaceExisting);
                 }
                 const rawBytes = new TextEncoder().encode(content);
                 const { response } = await this.restCall("PUT", `files/${projectId}/${existing.id}`, { body: rawBytes });
@@ -469,14 +399,29 @@ export class TypstCloudClient {
         });
     }
     async editFile(projectId, filePathOrId, edits, options) {
+        validateEdits(edits);
+        if (options?.expectedHash !== undefined &&
+            (typeof options.expectedHash !== "string" || !/^[a-f\d]{64}$/i.test(options.expectedHash))) {
+            throw new Error("expectedHash must be the SHA-256 contentHash returned by typst_read_file.");
+        }
+        if (options?.matchMode !== undefined && !["exact", "fuzzy"].includes(options.matchMode)) {
+            throw new Error("matchMode must be exact or fuzzy.");
+        }
+        if (options?.dryRun !== undefined && typeof options.dryRun !== "boolean") {
+            throw new Error("dryRun must be a boolean.");
+        }
         const file = await this.resolveFile(projectId, filePathOrId);
         if (!file.isMultiplayable) {
             throw new TypstLoadError(["NOT_MULTIPLAYABLE"], `File "${file.name}" is a binary blob and cannot be surgically text-edited`);
         }
         return withFileMutationQueue(`${projectId}:${file.id}`, async () => {
             const remote = await this.downloadFileYjs(projectId, file.id);
-            const { encodedUpdate, previousText, updatedText, appliedCount, diff, patch, firstChangedLine, } = editYjsText(remote, edits, file.name);
-            const { syncChannel } = await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options?.preferWebSocket ?? true);
+            const currentHash = hashText(decodeYjsText(remote));
+            if (options?.expectedHash !== undefined && currentHash !== options.expectedHash.toLowerCase()) {
+                throw new TypstLoadError(["STALE_CONTENT"], "File changed since read. Read the affected range again and retry with its contentHash.");
+            }
+            const { encodedUpdate, previousText, updatedText, appliedCount, diff, patch, firstChangedLine, usedFuzzyMatch, } = editYjsText(remote, edits, file.name, options?.matchMode ?? "exact");
+            const { syncChannel } = options?.dryRun ? { syncChannel: "none" } : await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options?.preferWebSocket ?? true);
             return {
                 file,
                 appliedCount,
@@ -486,6 +431,9 @@ export class TypstCloudClient {
                 patch,
                 firstChangedLine,
                 syncChannel,
+                contentHash: options?.dryRun ? currentHash : hashText(updatedText),
+                dryRun: Boolean(options?.dryRun),
+                usedFuzzyMatch,
             };
         });
     }
@@ -571,18 +519,92 @@ export class TypstCloudClient {
     static parseShortDiagnostics(stderrText) {
         return parseShortDiagnostics(stderrText);
     }
-    async getDiagnostics(projectId, mainFile) {
-        const { workspaceDir, mainFileName } = await this.materializeProjectWorkspace(projectId, mainFile);
+    async updateProject(projectId, updates) {
+        const res = await this.graphql(EDIT_PROJECT_MUTATION, {
+            projectId,
+            name: updates.name,
+            previewed: updates.previewed,
+            pinnedVersion: updates.pinnedVersion,
+        });
+        return res.updateProject;
+    }
+    async getWebDiagnostics(projectId, mainFile) {
+        const project = await this.getProject(projectId);
+        let effectiveMainFile = mainFile;
+        if (!effectiveMainFile) {
+            const previewedFile = project.files.find((f) => f.id === project.previewed);
+            effectiveMainFile = previewedFile?.name ?? "main.typ";
+        }
+        else {
+            const requestedFile = project.files.find((f) => f.name === mainFile || f.id === mainFile);
+            if (requestedFile && requestedFile.id !== project.previewed) {
+                try {
+                    await this.updateProject(projectId, { previewed: requestedFile.id });
+                }
+                catch {
+                    // If permission denied or mutation rejected, proceed anyway
+                }
+            }
+        }
+        const fileContents = {};
+        for (const f of project.files) {
+            if (f.isMultiplayable) {
+                try {
+                    const res = await this.readFile(projectId, f.name);
+                    if (res.encoding === "utf-8" && typeof res.content === "string") {
+                        fileContents[f.name] = res.content;
+                    }
+                }
+                catch {
+                    // Ignore read failures for auxiliary files
+                }
+            }
+        }
+        return captureWebDiagnostics({
+            appUrl: this.auth.appUrl,
+            projectId,
+            cookieHeader: this.auth.getCookieHeader(),
+            mainFile: effectiveMainFile,
+            fileContents,
+        });
+    }
+    async getDiagnostics(projectId, options) {
+        const opts = typeof options === "string" ? { mainFile: options } : options;
+        const mode = opts?.mode ?? "auto";
+        const requestedMainFile = opts?.mainFile;
+        if (mode === "web") {
+            return await this.getWebDiagnostics(projectId, requestedMainFile);
+        }
+        const typstAvailable = hasTypstBinary(this.typstBin);
+        if (!typstAvailable) {
+            if (mode === "cli") {
+                throw new TypstLoadError(["TYPST_BINARY_NOT_FOUND"], `Typst compiler binary '${this.typstBin}' was not found. Please install the Typst compiler (e.g. 'winget install Typst.Typst' / 'brew install typst') or use mode: 'web' for zero-binary cloud diagnostics.`);
+            }
+            return await this.getWebDiagnostics(projectId, requestedMainFile);
+        }
         try {
-            return compileWorkspaceDiagnostics({
-                typstBin: this.typstBin,
-                projectId,
-                workspaceDir,
-                mainFileName,
-            });
+            const { workspaceDir, mainFileName } = await this.materializeProjectWorkspace(projectId, requestedMainFile);
+            try {
+                const res = compileWorkspaceDiagnostics({
+                    typstBin: this.typstBin,
+                    projectId,
+                    workspaceDir,
+                    mainFileName,
+                });
+                return {
+                    ...res,
+                    mode: "cli",
+                };
+            }
+            finally {
+                rmSync(workspaceDir, { recursive: true, force: true });
+            }
         }
-        finally {
-            rmSync(workspaceDir, { recursive: true, force: true });
+        catch (err) {
+            if (mode === "auto") {
+                return await this.getWebDiagnostics(projectId, requestedMainFile);
+            }
+            throw err;
         }
     }
     async exportPdf(projectId, options) {
@@ -675,7 +697,13 @@ export class TypstCloudClient {
         };
     }
     async findAndReplace(projectId, options) {
+        const rules = resolveReplacementRules(options);
+        const output = options.output ?? (options.replacements ? "summary" : "full");
         const files = await this.listFiles(projectId);
+        if (options.filePath && !files.some(file => file.isMultiplayable &&
+            (file.name === options.filePath.replace(/^\/+/, "") || file.id === options.filePath))) {
+            throw new Error(`Text file not found: ${options.filePath}`);
+        }
         const filesModified = [];
         let totalReplacements = 0;
         for (const file of files) {
@@ -693,14 +721,8 @@ export class TypstCloudClient {
             await withFileMutationQueue(`${projectId}:${file.id}`, async () => {
                 const remote = await this.downloadFileYjs(projectId, file.id);
                 const text = decodeYjsText(remote);
-                const repResult = replaceInContent(file.name, text, {
-                    pattern: options.pattern,
-                    replacement: options.replacement,
-                    regex: options.regex,
-                    ignoreCase: options.ignoreCase,
-                    limit: options.limit,
-                });
-                if (repResult.replacementCount > 0) {
+                const repResult = replaceBatchInContent(file.name, text, rules, output);
+                if (repResult.updatedText !== text) {
                     if (!options.dryRun) {
                         const { encodedUpdate } = replaceYjsText(remote, repResult.updatedText);
                         await this.saveYjsUpdate(projectId, file.id, encodedUpdate, options.preferWebSocket ?? true);
@@ -708,8 +730,9 @@ export class TypstCloudClient {
                     filesModified.push({
                         file: file.name,
                         replacementsCount: repResult.replacementCount,
-                        diff: repResult.diff,
-                        patch: repResult.patch,
+                        ...(repResult.diff !== undefined ? { diff: repResult.diff } : {}),
+                        ...(repResult.patch !== undefined ? { patch: repResult.patch } : {}),
+                        ...(options.replacements ? { replacementCounts: repResult.replacementCounts } : {}),
                         firstChangedLine: repResult.firstChangedLine,
                     });
                     totalReplacements += repResult.replacementCount;

package/dist/index.js

@@ -8,6 +8,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { TypstCloudClient, } from "./client/typst-client.js";
 import { formatUnknownError } from "./client/errors.js";
 import { TYPST_MCP_TOOLS } from "./tools/definitions.js";
+import { validateEdits } from "./protocol/edit-diff.js";
+import { truncateHead } from "./utils/truncate.js";
 export { TYPST_MCP_TOOLS };
 function resolvePreferWebSocket(value) {
     if (typeof value === "boolean") {
@@ -22,32 +24,25 @@ function resolveOptionalNumber(value) {
     return undefined;
 }
 export function prepareEditArguments(input) {
-    if (!input)
+    if (input === undefined)
         return [];
-    if (Array.isArray(input)) {
-        return input.filter((e) => e && typeof e.oldText === "string" && typeof e.newText === "string");
-    }
     if (typeof input === "string") {
         try {
-            const parsed = JSON.parse(input);
-            if (Array.isArray(parsed)) {
-                return parsed.filter((e) => e && typeof e.oldText === "string" && typeof e.newText === "string");
-            }
-            if (parsed &&
-                typeof parsed.oldText === "string" &&
-                typeof parsed.newText === "string") {
-                return [parsed];
-            }
+            input = JSON.parse(input);
         }
-        catch { }
-    }
-    if (typeof input === "object" && input !== null) {
-        const obj = input;
-        if (typeof obj.oldText === "string" && typeof obj.newText === "string") {
-            return [{ oldText: obj.oldText, newText: obj.newText }];
+        catch {
+            throw new Error("edits must be an array of {oldText, newText}; invalid JSON.");
         }
     }
-    return [];
+    const edits = (Array.isArray(input) ? input : [input]);
+    validateEdits(edits);
+    return edits.map(({ oldText, newText }) => ({ oldText, newText }));
+}
+function requiredText(args, key) {
+    if (typeof args[key] !== "string" || !args[key].length) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return args[key];
 }
 export async function dispatchTypstTool(client, name, args = {}) {
     switch (name) {
@@ -78,28 +73,71 @@ export async function dispatchTypstTool(client, name, args = {}) {
         }
         case "typst_list_files":
             return await client.listFiles(String(args.projectId));
-        case "typst_read_file":
-            return await client.readFile(String(args.projectId), String(args.filePath), {
-                offset: resolveOptionalNumber(args.offset),
-                limit: resolveOptionalNumber(args.limit),
-                lineNumbers: typeof args.lineNumbers === "boolean"
-                    ? args.lineNumbers
-                    : undefined,
+        case "typst_read_file": {
+            if (args.output !== undefined && args.output !== "compact" && args.output !== "full") {
+                throw new Error("output must be compact or full.");
+            }
+            const result = await client.readFile(requiredText(args, "projectId"), requiredText(args, "filePath"), {
+                offset: args.offset,
+                limit: args.limit,
+                maxBytes: args.maxBytes,
+                lineNumbers: args.lineNumbers,
             });
+            return args.output === "full" ? result : {
+                ...result, file: { id: result.file.id, name: result.file.name },
+            };
+        }
         case "typst_write_file":
             return await client.writeFile(String(args.projectId), String(args.filePath), String(args.content), {
                 preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
             });
         case "typst_edit_file": {
-            let edits = prepareEditArguments(args.edits);
-            if (edits.length === 0 &&
-                typeof args.oldText === "string" &&
-                typeof args.newText === "string") {
-                edits = [{ oldText: args.oldText, newText: args.newText }];
+            const hasShorthand = args.oldText !== undefined || args.newText !== undefined;
+            if (args.edits !== undefined && hasShorthand) {
+                throw new Error("Use either edits or oldText/newText, not both.");
+            }
+            const edits = prepareEditArguments(args.edits !== undefined ? args.edits :
+                hasShorthand ? { oldText: args.oldText, newText: args.newText } : undefined);
+            const output = args.output ?? (args.dryRun === true ? "diff" : "summary");
+            if (!["summary", "diff", "full"].includes(output)) {
+                throw new Error("output must be summary, diff, or full.");
             }
-            return await client.editFile(String(args.projectId), String(args.filePath), edits, {
+            const maxDiffBytes = args.maxDiffBytes ?? 8192;
+            if (typeof maxDiffBytes !== "number" || !Number.isSafeInteger(maxDiffBytes) ||
+                maxDiffBytes < 1 || maxDiffBytes > 1048576) {
+                throw new Error("maxDiffBytes must be an integer between 1 and 1048576.");
+            }
+            if (args.preferWebSocket !== undefined && typeof args.preferWebSocket !== "boolean") {
+                throw new Error("preferWebSocket must be a boolean.");
+            }
+            const result = await client.editFile(requiredText(args, "projectId"), requiredText(args, "filePath"), edits, {
                 preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
+                expectedHash: args.expectedHash,
+                matchMode: args.matchMode,
+                dryRun: args.dryRun,
             });
+            const compact = {
+                file: { id: result.file.id, name: result.file.name },
+                appliedCount: result.appliedCount,
+                contentHash: result.contentHash,
+                firstChangedLine: result.firstChangedLine,
+                ...(result.dryRun ? { dryRun: true } : {}),
+                ...(result.usedFuzzyMatch ? { usedFuzzyMatch: true } : {}),
+            };
+            if (output === "summary")
+                return compact;
+            const diff = truncateHead(result.diff, { maxLines: 100, maxBytes: maxDiffBytes });
+            const diffFields = {
+                diff: diff.content,
+                ...(diff.truncated ? { diffTruncated: true, hint: "Read the affected range to inspect all changes, or increase maxDiffBytes (100 diff lines maximum)." } : {}),
+            };
+            if (output === "diff")
+                return { ...compact, ...diffFields };
+            const patch = truncateHead(result.patch, { maxLines: 100, maxBytes: maxDiffBytes });
+            return {
+                ...result, ...diffFields, patch: patch.content,
+                ...(patch.truncated ? { patchTruncated: true } : {}),
+            };
         }
         case "typst_upload_asset": {
             let bytes;
@@ -119,7 +157,10 @@ export async function dispatchTypstTool(client, name, args = {}) {
         case "typst_rename_file":
             return await client.renameFile(String(args.projectId), String(args.filePath), String(args.newName));
         case "typst_get_diagnostics":
-            return await client.getDiagnostics(String(args.projectId), args.mainFile);
+            return await client.getDiagnostics(String(args.projectId), {
+                mainFile: args.mainFile,
+                mode: args.mode,
+            });
         case "typst_export_pdf":
             return await client.exportPdf(String(args.projectId), {
                 mainFile: args.mainFile,
@@ -146,13 +187,15 @@ export async function dispatchTypstTool(client, name, args = {}) {
             });
         case "typst_find_and_replace":
             return await client.findAndReplace(String(args.projectId), {
-                pattern: String(args.pattern),
-                replacement: String(args.replacement),
+                pattern: args.pattern,
+                replacement: args.replacement,
+                replacements: args.replacements,
+                output: args.output,
                 filePath: args.filePath,
                 glob: args.glob,
-                regex: Boolean(args.regex),
-                ignoreCase: Boolean(args.ignoreCase),
-                limit: resolveOptionalNumber(args.limit),
+                regex: args.regex,
+                ignoreCase: args.ignoreCase,
+                limit: args.limit,
                 dryRun: Boolean(args.dryRun),
                 preferWebSocket: resolvePreferWebSocket(args.preferWebSocket),
             });
@@ -164,7 +207,7 @@ export function createTypstMcpServer(options = {}) {
     const client = new TypstCloudClient(options);
     const server = new Server({
         name: "typst-mcp",
-        version: "1.1.0",
+        version: "1.3.0",
     }, {
         capabilities: {
             tools: {},
@@ -207,7 +250,7 @@ export function createTypstMcpServer(options = {}) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(result, null, name === "typst_read_file" || name === "typst_edit_file" ? undefined : 2),
                     },
                 ],
             };

package/dist/protocol/edit-diff.js

@@ -133,10 +133,13 @@ export function fuzzyFindText(content, oldText) {
             contentForReplacement: content,
         };
     }
-    const fuzzyContent = normalizeForFuzzyMatch(content);
+    const { normalized: fuzzyContent, starts, ends } = fuzzyTextWithOffsets(content);
     const fuzzyOldText = normalizeForFuzzyMatch(oldText);
-    const fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);
-    if (fuzzyIndex === -1) {
+    const fuzzyIndex = fuzzyOldText.length ? fuzzyContent.indexOf(fuzzyOldText) : -1;
+    // Do not replace part of an expanded Unicode grapheme (e.g. one f in ffi).
+    const last = fuzzyIndex + fuzzyOldText.length - 1;
+    if (fuzzyIndex === -1 || starts[fuzzyIndex] === starts[fuzzyIndex - 1] ||
+        ends[last] === ends[last + 1]) {
         return {
             found: false,
             index: -1,
@@ -147,20 +150,69 @@ export function fuzzyFindText(content, oldText) {
     }
     return {
         found: true,
-        index: fuzzyIndex,
-        matchLength: fuzzyOldText.length,
+        index: starts[fuzzyIndex],
+        matchLength: ends[last] - starts[fuzzyIndex],
         usedFuzzyMatch: true,
-        contentForReplacement: fuzzyContent,
+        contentForReplacement: content,
     };
 }
+/** Keep original offsets so fallback matching cannot normalize unrelated text. */
+function fuzzyTextWithOffsets(content) {
+    let normalized = "";
+    const starts = [];
+    const ends = [];
+    const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+    for (const { segment, index } of segmenter.segment(content)) {
+        // Append a sentinel so trailing spaces are retained until the line-level trim.
+        const value = normalizeForFuzzyMatch(segment + "\u0000").slice(0, -1);
+        normalized += value;
+        for (let i = 0; i < value.length; i++) {
+            starts.push(index);
+            ends.push(index + segment.length);
+        }
+    }
+    let offset = 0;
+    const keptStarts = [];
+    const keptEnds = [];
+    const trimmedLines = normalized.split("\n").map(line => {
+        const trimmed = line.trimEnd();
+        for (let i = 0; i < trimmed.length; i++) {
+            keptStarts.push(starts[offset + i]);
+            keptEnds.push(ends[offset + i]);
+        }
+        offset += line.length;
+        if (offset < normalized.length) {
+            keptStarts.push(starts[offset]);
+            keptEnds.push(ends[offset]);
+            offset++;
+        }
+        return trimmed;
+    });
+    return { normalized: trimmedLines.join("\n"), starts: keptStarts, ends: keptEnds };
+}
 export function countOccurrences(content, oldText) {
-    const fuzzyContent = normalizeForFuzzyMatch(content);
-    const fuzzyOldText = normalizeForFuzzyMatch(oldText);
-    if (fuzzyOldText.length === 0)
+    if (!oldText.length)
         return 0;
-    return fuzzyContent.split(fuzzyOldText).length - 1;
+    let count = 0;
+    let offset = content.indexOf(oldText);
+    while (offset !== -1) {
+        count++;
+        offset = content.indexOf(oldText, offset + 1);
+    }
+    return count;
+}
+export function validateEdits(edits) {
+    if (!Array.isArray(edits) || edits.length === 0) {
+        throw new Error("At least one edit operation is required");
+    }
+    for (const [index, edit] of edits.entries()) {
+        if (!edit || typeof edit.oldText !== "string" || typeof edit.newText !== "string" || !edit.oldText.length) {
+            throw new Error(`Edit ${index + 1} requires a non-empty oldText and a string newText.`);
+        }
+    }
 }
-export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
+export function applyEditsToNormalizedContent(normalizedContent, edits, path, matchMode = "fuzzy") {
+    validateEdits(edits);
     const normalizedEdits = edits.map((e) => ({
         oldText: normalizeToLF(e.oldText),
         newText: normalizeToLF(e.newText),
@@ -170,19 +222,20 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
             throw new Error(`oldText cannot be empty for edit in ${path}`);
         }
     }
-    const initialMatches = normalizedEdits.map((e) => fuzzyFindText(normalizedContent, e.oldText));
-    const usedFuzzyMatch = initialMatches.some((m) => m.usedFuzzyMatch);
-    const replacementBaseContent = usedFuzzyMatch
-        ? normalizeForFuzzyMatch(normalizedContent)
-        : normalizedContent;
+    let usedFuzzyMatch = false;
     const matchedEdits = [];
     for (let i = 0; i < normalizedEdits.length; i++) {
         const edit = normalizedEdits[i];
-        const matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);
+        const exactIndex = normalizedContent.indexOf(edit.oldText);
+        const matchResult = exactIndex !== -1 ? {
+            found: true, index: exactIndex, matchLength: edit.oldText.length, usedFuzzyMatch: false,
+        } : matchMode === "fuzzy" ? fuzzyFindText(normalizedContent, edit.oldText) : { found: false };
         if (!matchResult.found) {
             throw new Error(`Could not find match for oldText in ${path}: ${JSON.stringify(edit.oldText.slice(0, 80))}`);
         }
-        const occurrences = countOccurrences(replacementBaseContent, edit.oldText);
+        const fuzzy = Boolean(matchResult.usedFuzzyMatch);
+        usedFuzzyMatch ||= fuzzy;
+        const occurrences = countOccurrences(fuzzy ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent, fuzzy ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText);
         if (occurrences > 1) {
             throw new Error(`Found ${occurrences} occurrences of oldText in ${path} (must be unique): ${JSON.stringify(edit.oldText.slice(0, 80))}`);
         }
@@ -202,13 +255,11 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
         }
     }
     const baseContent = normalizedContent;
-    const newContent = usedFuzzyMatch
-        ? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)
-        : applyReplacements(replacementBaseContent, matchedEdits);
+    const newContent = applyReplacements(normalizedContent, matchedEdits);
     if (baseContent === newContent) {
         throw new Error(`No changes made to ${path}: newText equals oldText.`);
     }
-    return { baseContent, newContent };
+    return { baseContent, newContent, matchedEdits, usedFuzzyMatch };
 }
 /**
  * Generate a standard unified patch.
@@ -239,7 +290,7 @@ export function generateDiffString(oldContent, newContent, contextLines = 4) {
             raw.pop();
         }
         if (part.added || part.removed) {
-            if (firstChangedLine === undefined && part.added) {
+            if (firstChangedLine === undefined) {
                 firstChangedLine = newLineNum;
             }
             for (const line of raw) {