@adecore/editor-core 0.22.0 → 0.23.0

package/dist/enter.js

@@ -1,3 +1,4 @@
+import { editRegions } from './edit-regions.js';
 import { commentSyntax } from './languages.js';
 import { hasHashComments, isBraced, isPhp, openers } from './lexical.js';
 import { whitespaceOf } from './line-text.js';
@@ -27,13 +28,14 @@ function escapeForPattern(text) {
  * `if` or `for`, after `else`, `=>` or a binary operator. Languages with braces only.
  */
 export function continues(text, context, language) {
-    if (!isBraced(language) || context.mode !== 'code') {
+    const effectiveLanguage = context.embedded ?? language;
+    if (!isBraced(effectiveLanguage) || context.mode !== 'code') {
         return false;
     }
     if (context.word === 'control-close' || context.word === 'else' || context.word === 'do') {
         return true;
     }
-    if (isPhp(language) && /(?<!\.)\.$/.test(text)) {
+    if (isPhp(effectiveLanguage) && /(?<!\.)\.$/.test(text)) {
         return true;
     }
     return trailingOperator.test(text);
@@ -113,6 +115,16 @@ class Enter {
         const base = context.mode === 'code' ? this.baseIndent(index) : leading;
         const start = leading.length < before.length ? base : leading;
         const plain = (indent) => ({ from, to: afterWhitespace, text: newline + indent, caret: newline.length + indent.length });
+        if (context.mode === 'code' || (isPhp(language) && context.mode === 'html')) {
+            const tag = this.openTag(trimmed, index);
+            if (tag) {
+                const inner = start + unit;
+                if (new RegExp(`^</${escapeForPattern(tag)}\\s*>`, 'i').test(source.slice(afterWhitespace, line.end))) {
+                    return { from, to: afterWhitespace, text: newline + inner + newline + start, caret: newline.length + inner.length };
+                }
+                return plain(inner);
+            }
+        }
         if (context.mode !== 'code') {
             return plain(leading);
         }
@@ -125,14 +137,6 @@ class Enter {
             const closing = last === '{' && source.unclosedBrace(context.bracket.at) ? this.closeBrace(from, afterWhitespace, line, rest, newline, start, inner) : null;
             return closing ?? plain(inner);
         }
-        const tag = this.openTag(trimmed, index);
-        if (tag) {
-            const inner = start + unit;
-            if (new RegExp(`^</${escapeForPattern(tag)}\\s*>`, 'i').test(source.slice(afterWhitespace, line.end))) {
-                return { from, to: afterWhitespace, text: newline + inner + newline + start, caret: newline.length + inner.length };
-            }
-            return plain(inner);
-        }
         if (this.opensIndentedBlock(trimmed, context)) {
             return plain(this.blockIndent(line.text, start) + unit);
         }
@@ -159,7 +163,7 @@ class Enter {
     /* The name of the tag the text ends in, when it is an open tag with children to come. */
     openTag(trimmed, index) {
         const { language } = this.options;
-        if (!markupLanguages.test(language)) {
+        if (!markupLanguages.test(language) && !isPhp(language)) {
             return null;
         }
         if (/^vue$/i.test(language) && this.source.region(index) === 'script') {
@@ -169,6 +173,14 @@ class Enter {
         if (!match || trimmed.endsWith('/>') || (voidElements.test(match[1]) && !/^xml$/i.test(language))) {
             return null;
         }
+        if (isPhp(language)) {
+            const offset = this.source.line(index).start + trimmed.indexOf('<', match.index);
+            // Only earlier tags establish this opener's region; its content can be script or style.
+            const regions = editRegions(this.source, language);
+            if (regions(index, offset) !== 'template') {
+                return null;
+            }
+        }
         return match[1];
     }
     /* Python's `def f():`, a YAML `key:` and a `case x:`. */
@@ -232,7 +244,7 @@ class Enter {
     }
     inString(from, context, index) {
         const { source, options } = this;
-        const operator = concatenation.get(options.language.toLowerCase());
+        const operator = concatenation.get(context.embedded ?? options.language.toLowerCase());
         const quote = context.quote;
         if (operator === undefined || (quote !== '"' && quote !== "'")) {
             return null;

package/dist/index.d.ts

@@ -2,8 +2,9 @@ export { DocumentModel } from './document.ts';
 export type { DocumentEditOptions, DocumentLine, OffsetRange, ReplaceAllOptions, ReplaceOptions, TypeTextOptions } from './document.ts';
 export { scanBrackets, type BracketIndex } from './brackets.ts';
 export { replaceWithCaseRespect } from './preserve-case.ts';
-export { findMatches, replacementText, type FindMatch, type FindNextOptions, type FindOptions } from './search.ts';
+export { findMatches, iterateMatches, findMatchFrom, replacementText, type FindMatch, type FindNextOptions, type FindOptions } from './search.ts';
 export { indentationColumn } from './structure.ts';
+export { findDocComments, MAX_DOC_COMMENTS, type DocComment } from './doc-comments.ts';
 export type { FoldHints, FoldRangeHint, FoldRole, FoldSymbolHint, FoldingOptions, FoldingRange } from './structure.ts';
 export { isHumpBoundary, isWordBoundary, wordBoundary, type WordText } from './words.ts';
 export type { ChangeSource, CommandOptions, ContentEdit, Disposable, DocumentChange, EditOptions, EditorCommand, EditorSnapshot, Position, Selection, TextEdit } from './types.ts';

package/dist/index.js

@@ -1,7 +1,8 @@
 export { DocumentModel } from './document.js';
 export { scanBrackets } from './brackets.js';
 export { replaceWithCaseRespect } from './preserve-case.js';
-export { findMatches, replacementText } from './search.js';
+export { findMatches, iterateMatches, findMatchFrom, replacementText } from './search.js';
 export { indentationColumn } from './structure.js';
+export { findDocComments, MAX_DOC_COMMENTS } from './doc-comments.js';
 export { isHumpBoundary, isWordBoundary, wordBoundary } from './words.js';
 export { changedSpan, changedSpans } from './text-span.js';

package/dist/languages.d.ts

@@ -7,6 +7,7 @@ export interface CommentSyntax {
     block: BlockComment | null;
 }
 export type VueRegion = 'template' | 'script' | 'style';
-export declare function commentSyntax(language: string, region?: VueRegion | null): CommentSyntax;
+export type EditRegion = VueRegion | 'jsx' | 'mixed';
+export declare function commentSyntax(language: string, region?: EditRegion | null): CommentSyntax;
 export declare function isPlainText(language: string): boolean;
 export declare function vueRegionAt(lineText: (line: number) => string, line: number): VueRegion | null;

package/dist/languages.js

@@ -22,7 +22,13 @@ register('plaintext text txt log', none);
 /* An id nothing knows has no comment syntax, which toggling a comment answers by doing nothing. */
 export function commentSyntax(language, region) {
     const id = language.toLowerCase();
-    if (id === 'vue') {
+    if (region === 'mixed') {
+        return none;
+    }
+    if (region === 'jsx') {
+        return { line: null, block: { open: '{/*', close: '*/}' } };
+    }
+    if (id === 'vue' || (id === 'php' && region !== null && region !== undefined)) {
         if (region === 'script') {
             return cLike;
         }

package/dist/markup-regions.d.ts

@@ -3,6 +3,7 @@ export declare function jsxRanges(text: string): {
     from: number;
     to: number;
 }[];
+export declare function jsxChildren(text: string): (offset: number) => boolean;
 export declare function hasJsx(language: string): boolean;
 export declare function isJsxAttributeValue(text: string, offset: number): boolean;
 export declare function markupGuard(source: EditSource, language: string): (line: number) => boolean;

package/dist/markup-regions.js

@@ -12,13 +12,16 @@ const CLOSERS = { '{': '}', '(': ')', '[': ']' };
  */
 class JsxScanner {
     ranges = [];
+    children = [];
+    collectChildren;
     /* The quoted values of attributes, quotes included. */
     values = [];
     text;
     depth = 0;
     budget;
-    constructor(text) {
+    constructor(text, collectChildren = false) {
         this.text = text;
+        this.collectChildren = collectChildren;
         this.budget = text.length * 12 + 1_000;
     }
     scan() {
@@ -174,14 +177,34 @@ class JsxScanner {
     }
     /* An element from its `<`, recorded when no element holds it, and the offset after its closing tag; -1 when it is not one. */
     element(from, outermost) {
+        const children = this.children.length;
+        const previousEnd = this.children.at(-1)?.to;
         this.depth++;
         const end = this.parseElement(from);
         this.depth--;
+        if (end < 0) {
+            this.children.length = children;
+            if (previousEnd !== undefined) {
+                this.children[children - 1].to = previousEnd;
+            }
+        }
         if (end >= 0 && outermost && this.depth === 0) {
             this.ranges.push({ from, to: end });
         }
         return end;
     }
+    child(from, to) {
+        if (!this.collectChildren || from >= to) {
+            return;
+        }
+        const previous = this.children.at(-1);
+        if (previous !== undefined && previous.to === from) {
+            previous.to = to;
+        }
+        else {
+            this.children.push({ from, to });
+        }
+    }
     skipSpace(from) {
         let at = from;
         while (at < this.text.length && /\s/.test(this.text[at])) {
@@ -202,6 +225,22 @@ class JsxScanner {
             if (char === undefined || --this.budget < 0) {
                 return -1;
             }
+            if (char === '/' && text[at + 1] === '/') {
+                const end = text.indexOf('\n', at + 2);
+                if (end < 0) {
+                    return -1;
+                }
+                at = end + 1;
+                continue;
+            }
+            if (char === '/' && text[at + 1] === '*') {
+                const end = text.indexOf('*/', at + 2);
+                if (end < 0) {
+                    return -1;
+                }
+                at = end + 2;
+                continue;
+            }
             if (char === '/' && text[at + 1] === '>') {
                 return at + 2;
             }
@@ -250,14 +289,21 @@ class JsxScanner {
             }
         }
         for (;;) {
+            const start = at;
             while (at < text.length && text[at] !== '<' && text[at] !== '{') {
                 at++;
             }
+            this.child(start, text[at] === '<' ? at + 1 : at);
             if (at >= text.length || --this.budget < 0) {
                 return -1;
             }
             if (text[at] === '{') {
+                this.child(at, at + 1);
+                const from = at;
                 at = this.code(at + 1, '}');
+                if (at >= 0 && /^\{\s*\/\*/.test(text.slice(from, from + 20))) {
+                    this.child(from + 1, at);
+                }
             }
             else if (text[at + 1] === '/') {
                 const closing = /^<\/\s*([\w$.:-]*)\s*>/.exec(text.slice(at, at + 200));
@@ -300,6 +346,12 @@ function insideAny(ranges, offset) {
     }
     return false;
 }
+/* Child text and nested tags use JSX comments; attributes and embedded expressions stay code. */
+export function jsxChildren(text) {
+    const scanner = new JsxScanner(text, true);
+    scanner.scan();
+    return (offset) => insideAny(scanner.children, offset);
+}
 /* Whether a language is one whose scripts can hold JSX. */
 export function hasJsx(language) {
     return JSX_LANGUAGES.test(language);

package/dist/offsets.d.ts

@@ -1,2 +1,3 @@
 import type { TextEdit } from './types.ts';
 export declare function mapOffset(offset: number, edits: readonly TextEdit[], stayBefore?: boolean): number;
+export declare function offsetMapper(edits: readonly TextEdit[]): (offset: number, stayBefore?: boolean) => number;

package/dist/offsets.js

@@ -12,3 +12,26 @@ export function mapOffset(offset, edits, stayBefore = false) {
     }
     return offset + delta;
 }
+/* Reuse this index across selections while retaining both endpoint affinities. */
+export function offsetMapper(edits) {
+    const deltas = new Float64Array(edits.length + 1);
+    for (let index = 0; index < edits.length; index++) {
+        const edit = edits[index];
+        deltas[index + 1] = deltas[index] + edit.text.length - (edit.to - edit.from);
+    }
+    return (offset, stayBefore = false) => {
+        let low = 0, high = edits.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            const edit = edits[middle];
+            if (edit.to < offset || (edit.to === offset && !(stayBefore && edit.from === edit.to))) {
+                low = middle + 1;
+            }
+            else {
+                high = middle;
+            }
+        }
+        const edit = edits[low];
+        return edit !== undefined && edit.from <= offset && offset < edit.to ? edit.from + deltas[low] + edit.text.length : offset + deltas[low];
+    };
+}

package/dist/php-markup.d.ts

@@ -0,0 +1,7 @@
+import type { TypingContext } from './typing-context.ts';
+interface ScriptLexer {
+    initial(): TypingContext;
+    step(state: TypingContext, text: string, at: number, end: number, offset: number): number;
+}
+export declare function scanPhpMarkup(state: TypingContext, text: string, from: number, end: number, offset: number, script: ScriptLexer): number;
+export {};

package/dist/php-markup.js

@@ -0,0 +1,99 @@
+const TAG = /<(\/?)([a-z][\w:-]*)(?=[\s/>]|$)/iy;
+const PHP = /<\?(?:php\b|=)/y;
+function finishTag(state, selfClosing, script, start) {
+    state.markup = !selfClosing && state.element !== undefined ? 'raw' : undefined;
+    state.markupQuote = undefined;
+    state.embed = state.markup === 'raw' && state.element === 'script' ? script.initial() : undefined;
+    if (state.embed !== undefined) {
+        state.embed.embedStart = start;
+    }
+    if (selfClosing) {
+        state.element = undefined;
+    }
+}
+export function scanPhpMarkup(state, text, from, end, offset, script) {
+    for (let at = from; at < end; at++) {
+        const char = text[at];
+        if (char === '<' && text[at + 1] === '?') {
+            PHP.lastIndex = at;
+            const open = PHP.exec(text);
+            if (open !== null) {
+                if (state.markup === 'equals') {
+                    state.markup = 'value';
+                }
+                state.mode = 'code';
+                state.expression = true;
+                state.word = '';
+                return at + open[0].length - 1;
+            }
+        }
+        if (state.markup === 'comment') {
+            if (text.startsWith('-->', at) && at + 3 <= end) {
+                state.markup = undefined;
+                at += 2;
+            }
+            continue;
+        }
+        if (state.markup === 'value' && state.markupQuote !== undefined) {
+            if (char === state.markupQuote) {
+                state.markup = 'tag';
+                state.markupQuote = undefined;
+            }
+            continue;
+        }
+        if (char === '<') {
+            if (state.markup !== 'raw' && text.startsWith('<!--', at)) {
+                // HTML also closes these two comments immediately, without a later -->.
+                const empty = text.startsWith('<!-->', at) ? 5 : text.startsWith('<!--->', at) ? 6 : 0;
+                state.markup = empty > 0 && at + empty <= end ? undefined : 'comment';
+                state.element = undefined;
+                at += (empty || 4) - 1;
+                continue;
+            }
+            TAG.lastIndex = at;
+            const tag = TAG.exec(text);
+            const name = tag?.[2]?.toLowerCase();
+            if (state.markup === 'raw' && (tag?.[1] !== '/' || name !== state.element)) {
+                if (state.embed !== undefined) {
+                    at = script.step(state.embed, text, at, end, offset);
+                }
+                continue;
+            }
+            state.embed = undefined;
+            state.element = tag?.[1] !== '/' && (name === 'script' || name === 'style' || name === 'textarea' || name === 'title') ? name : undefined;
+            state.markup = tag === null ? undefined : 'tag';
+            state.markupQuote = undefined;
+            if (tag !== null) {
+                at += tag[0].length - 1;
+            }
+            continue;
+        }
+        if (state.embed !== undefined) {
+            at = script.step(state.embed, text, at, end, offset);
+            continue;
+        }
+        if (state.markup === undefined || state.markup === 'raw') {
+            continue;
+        }
+        if (char === '>') {
+            finishTag(state, false, script, offset + at + 1);
+        }
+        else if (char === '/' && text[at + 1] === '>' && at + 2 <= end) {
+            finishTag(state, true, script, offset + at + 2);
+            at++;
+        }
+        else if (/\s/u.test(char)) {
+            if (state.markup === 'value') {
+                state.markup = 'tag';
+            }
+        }
+        else if (state.markup === 'equals') {
+            state.markup = 'value';
+            state.markupQuote = char === '"' || char === "'" ? char : undefined;
+        }
+        else if (state.markup === 'tag' && char === '=') {
+            state.markup = 'equals';
+        }
+    }
+    return end - 1;
+}

package/dist/rope.d.ts

@@ -4,6 +4,7 @@ export interface DocumentLine {
     next: number;
     text: string;
 }
+export declare const ROPE_CHUNK_SIZE = 2048;
 export declare function clampInteger(value: number, maximum: number): number;
 export declare class TextRope {
     private readonly root;
@@ -14,6 +15,11 @@ export declare class TextRope {
     charAt(offset: number): string;
     slice(from?: number, to?: number): string;
     replace(from: number, to: number, text: string): TextRope;
+    rebuild(edits: readonly {
+        from: number;
+        to: number;
+        text: string;
+    }[]): TextRope;
     equalsRange(other: TextRope, from: number, to: number): boolean;
     lineAt(offset: number): number;
     lineBounds(index: number): Omit<DocumentLine, 'text'>;

package/dist/rope.js

@@ -1,4 +1,4 @@
-const chunkSize = 2048;
+export const ROPE_CHUNK_SIZE = 2048;
 function leaf(text) {
     if (!text.length) {
         return null;
@@ -36,7 +36,7 @@ function join(left, right) {
     if (!right) {
         return left;
     }
-    if ('text' in left && 'text' in right && left.length + right.length <= chunkSize) {
+    if ('text' in left && 'text' in right && left.length + right.length <= ROPE_CHUNK_SIZE) {
         return leaf(left.text + right.text);
     }
     if (left.height > right.height + 1 && 'left' in left) {
@@ -66,8 +66,8 @@ function split(node, offset) {
 }
 function build(text) {
     const leaves = [];
-    for (let offset = 0; offset < text.length; offset += chunkSize) {
-        leaves.push(leaf(text.slice(offset, offset + chunkSize)));
+    for (let offset = 0; offset < text.length; offset += ROPE_CHUNK_SIZE) {
+        leaves.push(leaf(text.slice(offset, offset + ROPE_CHUNK_SIZE)));
     }
     const tree = (from, to) => {
         if (from === to) {
@@ -156,6 +156,35 @@ export class TextRope {
         const [, after] = split(rest, to - from);
         return new TextRope(join(join(before, build(text)), after));
     }
+    /* Dense validated batches rebuild once, rather than repeatedly splitting and rescanning leaves. */
+    rebuild(edits) {
+        const chunks = chunksOf(this.root, 0, this.length);
+        let chunk = chunks.next();
+        let column = 0;
+        let offset = 0;
+        const pieces = [];
+        const advance = (end, keep) => {
+            while (offset < end && !chunk.done) {
+                const count = Math.min(end - offset, chunk.value.length - column);
+                if (keep) {
+                    pieces.push(chunk.value.slice(column, column + count));
+                }
+                offset += count;
+                column += count;
+                if (column === chunk.value.length) {
+                    chunk = chunks.next();
+                    column = 0;
+                }
+            }
+        };
+        for (const edit of edits) {
+            advance(edit.from, true);
+            pieces.push(edit.text);
+            advance(edit.to, false);
+        }
+        advance(this.length, true);
+        return TextRope.from(pieces.join(''));
+    }
     /* Whether both ropes hold the same text in `[from, to)`, which has to be the same range of both. */
     equalsRange(other, from, to) {
         if (this.root === other.root) {

package/dist/script-source.d.ts

@@ -0,0 +1,2 @@
+import type { TypingContext } from './typing-context.ts';
+export declare function scriptSource(text: string, start: number, complete: boolean, context: (offset: number) => TypingContext | null): string | undefined;

package/dist/script-source.js

@@ -0,0 +1,44 @@
+export function scriptSource(text, start, complete, context) {
+    const events = /<\?(?:php\b|=)|\?>|<\/script(?=[\s/>]|$)/gi;
+    const chunks = [];
+    let cursor = 0;
+    let island;
+    const finish = (end) => {
+        chunks.push(text.slice(cursor, island ?? end));
+        if (island !== undefined) {
+            chunks.push(' '.repeat(end - island));
+        }
+        return chunks.join('');
+    };
+    for (const match of text.matchAll(events)) {
+        const state = context(start + match.index);
+        if (state === null) {
+            return undefined;
+        }
+        const inScript = state.embedded === 'javascript' && state.embedStart === start;
+        if (/^<\?(?:php\b|=)/.test(match[0])) {
+            if (inScript) {
+                island = match.index;
+            }
+        }
+        else if (match[0] === '?>') {
+            if (island !== undefined && state.embed?.embedStart === start && (state.mode === 'code' || state.mode === 'line-comment')) {
+                let end = match.index + 2;
+                if (text.startsWith('\r\n', end)) {
+                    end += 2;
+                }
+                else if (text[end] === '\n') {
+                    end++;
+                }
+                // Spaces preserve document offsets without treating PHP source newlines as script text.
+                chunks.push(text.slice(cursor, island), ' '.repeat(end - island));
+                cursor = end;
+                island = undefined;
+            }
+        }
+        else if (match[0].startsWith('</') && inScript) {
+            return finish(match.index);
+        }
+    }
+    return complete ? finish(text.length) : undefined;
+}

package/dist/search.d.ts

@@ -23,4 +23,6 @@ export declare function splitsSurrogate(text: {
     charAt(offset: number): string;
 }, offset: number): boolean;
 export declare function findMatches(text: string, query: string, revision: number, options?: FindOptions): FindMatch[];
-export declare function replacementText(text: string, match: FindMatch, replacement: string, literal?: boolean, preserveCase?: boolean): string;
+export declare function iterateMatches(text: string, query: string, revision: number, options?: FindOptions): Generator<FindMatch, void, unknown>;
+export declare function findMatchFrom(text: string, query: string, revision: number, offset: number, options?: FindNextOptions): FindMatch | null;
+export declare function replacementText(text: string, match: FindMatch, replacement: string, literal?: boolean, preserveCase?: boolean, maxCharacters?: number): string;

package/dist/search.js

@@ -1,3 +1,4 @@
+import { clampInteger } from './rope.js';
 import { replaceWithCaseRespect } from './preserve-case.js';
 const wordCharacter = /[\p{L}\p{N}\p{M}\p{Pc}$]/u;
 /* Whether `offset` sits between the two halves of a surrogate pair. */
@@ -9,8 +10,13 @@ function characterBefore(text, offset) {
 }
 /* Invalid bounds throw `RangeError`, an invalid expression `SyntaxError`. A zero-width match advances by one code point. */
 export function findMatches(text, query, revision, options = {}) {
+    return Array.from(iterateMatches(text, query, revision, options));
+}
+/* Validation and regex execution start when the iterator advances. */
+export function* iterateMatches(text, query, revision, options = {}) {
+    options = { ...options };
     if (!query && !options.regex) {
-        return [];
+        return;
     }
     const from = options.from ?? 0;
     const to = options.to ?? text.length;
@@ -24,8 +30,8 @@ export function findMatches(text, query, revision, options = {}) {
     const source = options.regex ? query : query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const expression = new RegExp(source, `gmu${options.caseSensitive ? '' : 'i'}`);
     expression.lastIndex = from;
-    const matches = [];
-    while (matches.length < maximum) {
+    let count = 0;
+    while (count < maximum) {
         const match = expression.exec(text);
         if (!match || match.index > to) {
             break;
@@ -34,7 +40,8 @@ export function findMatches(text, query, revision, options = {}) {
         const wholeWord = !options.wholeWord ||
             (!wordCharacter.test(characterBefore(text, match.index)) && !wordCharacter.test(String.fromCodePoint(text.codePointAt(end) ?? 0)));
         if (match.index >= from && end <= to && !splitsSurrogate(text, match.index) && !splitsSurrogate(text, end) && wholeWord) {
-            matches.push({
+            count++;
+            yield {
                 from: match.index,
                 to: end,
                 text: match[0],
@@ -42,21 +49,62 @@ export function findMatches(text, query, revision, options = {}) {
                 groups: match.groups ? { ...match.groups } : undefined,
                 regex: options.regex === true,
                 revision
-            });
+            };
         }
         if (!match[0].length) {
             expression.lastIndex = match.index + ((text.codePointAt(match.index) ?? 0) > 0xffff ? 2 : 1);
         }
     }
-    return matches;
+}
+/* Keeps the original match grid; starting RegExp at the caret would create overlapping matches. */
+export function findMatchFrom(text, query, revision, offset, options = {}) {
+    const position = clampInteger(offset, text.length);
+    let first = null;
+    let last = null;
+    let previous = null;
+    for (const match of iterateMatches(text, query, revision, options)) {
+        first ??= match;
+        last = match;
+        if (!options.backwards && match.from >= position) {
+            return match;
+        }
+        if (options.backwards) {
+            if (match.to <= position) {
+                previous = match;
+            }
+            else if (previous !== null || options.wrap === false) {
+                return previous;
+            }
+        }
+    }
+    return options.backwards ? (previous ?? (options.wrap === false ? null : last)) : options.wrap === false ? null : first;
 }
 /* Expands the JavaScript `$` patterns of a regex replacement, and gives it the case of the match when asked. Literal replacements are returned as they are. */
-export function replacementText(text, match, replacement, literal = false, preserveCase = false) {
-    const expanded = literal || !match.regex ? replacement : expandPatterns(text, match, replacement);
-    return preserveCase ? replaceWithCaseRespect(expanded, match.text) : expanded;
+export function replacementText(text, match, replacement, literal = false, preserveCase = false, maxCharacters = Infinity) {
+    if (maxCharacters !== Infinity && (!Number.isSafeInteger(maxCharacters) || maxCharacters < 0)) {
+        throw new RangeError('The replacement character limit must be nonnegative.');
+    }
+    const expanded = literal || !match.regex ? replacement : expandPatterns(text, match, replacement, maxCharacters);
+    if (expanded.length > maxCharacters) {
+        throw new RangeError('Replacement output exceeds its character limit.');
+    }
+    const result = preserveCase ? replaceWithCaseRespect(expanded, match.text) : expanded;
+    if (result.length > maxCharacters) {
+        throw new RangeError('Replacement output exceeds its character limit.');
+    }
+    return result;
 }
-function expandPatterns(text, match, replacement) {
-    return replacement.replace(/\$(\$|&|`|'|\d{1,2}|<[^>]*>)/g, (token, group) => {
+function expandPatterns(text, match, replacement, maxCharacters) {
+    const pieces = [];
+    let characters = 0, cursor = 0;
+    const append = (value) => {
+        characters += value.length;
+        if (characters > maxCharacters) {
+            throw new RangeError('Replacement output exceeds its character limit.');
+        }
+        pieces.push(value);
+    };
+    const expand = (token, group) => {
         if (group === '$') {
             return '$';
         }
@@ -81,5 +129,12 @@ function expandPatterns(text, match, replacement) {
             return (match.captures[first - 1] ?? '') + group[1];
         }
         return token;
-    });
+    };
+    for (const found of replacement.matchAll(/\$(\$|&|`|'|\d{1,2}|<[^>]*>)/g)) {
+        append(replacement.slice(cursor, found.index));
+        append(expand(found[0], found[1]));
+        cursor = found.index + found[0].length;
+    }
+    append(replacement.slice(cursor));
+    return pieces.join('');
 }