@wdprlib/ast 4.2.0 → 5.0.0

package/dist/index.d.cts

@@ -5,71 +5,6 @@ declare const buildInfo: Readonly<{
 	dirty: boolean | null;
 }>;
 /**
-* Source position tracking for Wikidot markup.
-*
-* Every token produced by the parser can carry a {@link Position} that maps it
-* back to its original location in the source text. This is used for error
-* reporting, source-map generation, and editor integration.
-*
-* Both {@link Point} and {@link Position} follow the
-* [unist Position](https://github.com/syntax-tree/unist#position) convention:
-* lines and columns are **1-based**, offsets are **0-based**.
-*
-* @module
-*/
-/**
-* A single point in the source text.
-*
-* Represents one end (start or end) of a {@link Position} range.
-* Line and column are 1-based to match text-editor conventions;
-* offset is 0-based for direct use with `String.prototype.slice()`.
-*
-* @group Source Position
-*/
-interface Point {
-	/** Line number in the source text (1-based: the first line is line 1) */
-	line: number;
-	/** Column number within the line (1-based: the first character is column 1) */
-	column: number;
-	/** Character offset from the beginning of the source string (0-based) */
-	offset: number;
-}
-/**
-* A contiguous range in the source text, defined by a start and end {@link Point}.
-*
-* The range is inclusive of `start` and exclusive of `end` — i.e., the
-* character at `end.offset` is **not** part of the range.
-*
-* @group Source Position
-*/
-interface Position {
-	/** The first character of the range */
-	start: Point;
-	/** One past the last character of the range */
-	end: Point;
-}
-/**
-* Create a {@link Point} value.
-*
-* @param line - 1-based line number
-* @param column - 1-based column number
-* @param offset - 0-based character offset
-* @returns A frozen {@link Point} object
-*
-* @group Source Position
-*/
-declare function createPoint(line: number, column: number, offset: number): Point;
-/**
-* Create a {@link Position} range from two {@link Point}s.
-*
-* @param start - Beginning of the range (inclusive)
-* @param end - End of the range (exclusive)
-* @returns A {@link Position} spanning `start..end`
-*
-* @group Source Position
-*/
-declare function createPosition(start: Point, end: Point): Position;
-/**
 * Shared CSS value definitions used across parser and renderer.
 *
 * @module
@@ -93,6 +28,54 @@ declare const CSS_LENGTH_UNITS: readonly ["cqmax", "cqmin", "cqw", "cqh", "cqi",
 * @group CSS
 */
 type CssLengthUnit = (typeof CSS_LENGTH_UNITS)[number];
+/** A rating always belongs to the host's displayed page. */
+type RatingRef = {
+	kind: "main";
+} | {
+	kind: "custom";
+	axisKey: string;
+};
+/** Zero is a neutral vote, not a cancellation. */
+type RatingVote = -1 | 0 | 1;
+/** Aggregates and the treatment of neutral votes are computed by the host. */
+interface RatingAggregate {
+	points: number;
+	votes: number;
+	percent: number;
+}
+/** An authorized, registered rating supplied by the host for the current viewer. */
+interface RatingState {
+	ref: RatingRef;
+	label: string;
+	/** Plain-text vote labels, e.g. { 1: "+", 0: "φ", [-1]: "-" }. Omitted entries use + / Ø / –. */
+	voteLabels?: Readonly<Partial<Record<RatingVote, string>>>;
+	/** Host policy: e.g. [1, -1], [1], [-1], or [1, 0, -1]. */
+	allowedVotes: readonly RatingVote[];
+	/** False keeps a visible, read-only widget. Omit the state to hide it entirely. */
+	canVote: boolean;
+	/** Independent of permission to cast a vote. */
+	canCancel: boolean;
+	/** Null means no vote; zero is a saved neutral vote. */
+	currentVote: RatingVote | null;
+	/** Null hides all aggregate values without preventing voting. */
+	aggregate: RatingAggregate | null;
+}
+/** `[[module Rate]]` accepts no attributes. A null reference marks an invalid declaration. */
+interface RateModuleData {
+	module: "rate";
+	ref: Extract<RatingRef, {
+		kind: "main";
+	}> | null;
+	state?: RatingState;
+}
+/** `[[module CustomRate key="theme"]]` accepts only key; it never registers or changes policy. */
+interface CustomRateModuleData {
+	module: "custom-rate";
+	ref: Extract<RatingRef, {
+		kind: "custom";
+	}> | null;
+	state?: RatingState;
+}
 /**
 * Key-value map of HTML attributes.
 * Populated from the Wikidot `_ class="foo" style="color:red"` attribute syntax.
@@ -171,7 +154,7 @@ interface AlignType {
 *
 * @group Container Types
 */
-type StringContainerType = "bold" | "italics" | "underline" | "superscript" | "subscript" | "strikethrough" | "monospace" | "span" | "div" | "blockquote" | "size" | "paragraph" | "heading" | "collapsible" | "definition-list" | "definition-list-item" | "definition-list-key" | "definition-list-value" | "table-row" | "table-cell";
+type StringContainerType = "bold" | "italics" | "underline" | "superscript" | "subscript" | "strikethrough" | "monospace" | "span" | "div" | "note" | "blockquote" | "size" | "paragraph" | "heading" | "collapsible" | "definition-list" | "definition-list-item" | "definition-list-key" | "definition-list-value" | "table-row" | "table-cell";
 /**
 * Union of all container type discriminators.
 * Every container element in the AST carries one of these to identify
@@ -498,10 +481,7 @@ type Module = {
 	"show-root": boolean;
 	/** Max depth, or null for unlimited */
 	depth: number | null;
-} | {
-	/** `[[module Rate]]` — page rating widget */
-	module: "rate";
-} | {
+} | RateModuleData | CustomRateModuleData | {
 	/** `[[module TagCloud]]` — weighted cloud of page tags */
 	module: "tag-cloud";
 	/** Numeric part of the font size for the lightest-weighted tag */
@@ -542,6 +522,7 @@ type Module = {
 	"created-at"?: string;
 	"updated-at"?: string;
 	rating?: string;
+	"rating-axis"?: string;
 	votes?: string;
 	name?: string;
 	fullname?: string;
@@ -799,9 +780,29 @@ interface DateData {
 	value: DateItem;
 	/** strftime-style format string, or null for default */
 	format: string | null;
-	/** Whether to show a tooltip with the full date on hover */
+	/** Whether to show elapsed time in a tooltip on hover */
 	hover: boolean;
 }
+/** Standalone page-option action, used by [[button action]].
+* @group Element Data
+*/
+type PageButtonAction = "edit" | "edit-append" | "edit-sections" | "history" | "print" | "files" | "tags" | "source" | "backlinks" | "talk" | "delete" | "rename" | "site-tools" | "edit-meta" | "watchers" | "parent" | "lock-page";
+/** Data for a standalone [[button]] element.
+* @group Element Data
+*/
+interface PageButtonData {
+	/** Unknown actions remain representable so the renderer can display the error. */
+	action: string;
+	text: string | null;
+	attributes: AttributeMap;
+}
+/** Data for [[social]], with null selecting the default services.
+* @group Element Data
+*/
+interface SocialData {
+	/** Unsupported names remain representable, but produce no share link. */
+	sites: string[] | null;
+}
 /**
 * Data for `##color|text##` inline color syntax.
 *
@@ -958,6 +959,8 @@ type ElementDataMap = {
 	"bibliography-block": BibliographyBlockData;
 	user: UserData;
 	date: DateData;
+	button: PageButtonData;
+	social: SocialData;
 	color: ColorData;
 	code: CodeBlockData;
 	math: MathData;
@@ -1162,6 +1165,114 @@ declare function isContainerTypeParagraphSafe(type: ContainerType): boolean;
 * @group Utilities
 */
 declare function isParagraphSafe(element: Element): boolean;
+/** Whether a standalone button names a supported page action. */
+declare function isPageButtonAction(action: string): action is PageButtonAction;
+interface ReadableTextOptions {
+	/** Exclude a subtree, for example an ACS/license container identified by the host. */
+	exclude?: (element: Element) => boolean;
+	/** Match host-rendered labels or supply text for date/math leaves. Undefined uses the default. */
+	resolveText?: (element: Extract<Element, {
+		element: "link" | "user" | "date" | "math" | "math-inline";
+	}>) => string | undefined;
+}
+/** Count graphemes, including whitespace, in the supplied readable text. */
+declare function countCharacters(text: string): number;
+/**
+* Extract semantic text from a resolved document, without executing HTML, CSS or JS.
+* Paragraph boundaries become blank lines; other whitespace is normalized. Tabs and
+* collapsibles include all panels. Footnotes are appended once, without reference UI.
+* Math/date leaves require resolveText; source TeX and timestamps are not prose.
+*/
+declare function extractReadableText(ast: SyntaxTree, options?: ReadableTextOptions): string;
+/** Extract the first nonempty paragraph, excluding headings and appended footnotes. */
+declare function extractFirstParagraph(ast: SyntaxTree, options?: ReadableTextOptions): string;
+interface TextExcerptOptions {
+	/** RE2 pattern, without / delimiters. Omit to truncate the entire text. */
+	pattern?: string;
+	/** Supported flags: i (case insensitive), m (line anchors), s (dot includes newline). */
+	flags?: string;
+	/** Capture number or name. Defaults to 0, the complete match. */
+	group?: number | string;
+	/** One-based, non-overlapping match number. Defaults to 1; maximum 10,000. */
+	match?: number;
+	/** Grapheme limit, default 200. Invalid, negative, or zero lengths return empty text. */
+	maxLength?: number;
+}
+/**
+* Compile once and reuse across pages. Invalid options, unsupported RE2 syntax, missing
+* matches/groups and exceeded limits return empty text. Regex inputs are limited to
+* 4,096 pattern code units and 1,000,000 text code units. The compiled program is limited
+* to 4,096 instructions; searches share a conservative 16,000,000-unit work budget
+* based on program size, capture count and remaining input length. No native RegExp fallback.
+*/
+declare function compileTextExcerpt(options?: TextExcerptOptions): (text: string) => string;
+/** Select a regex match/capture and truncate without splitting a grapheme cluster. */
+declare function excerptText(text: string, options?: TextExcerptOptions): string;
+/**
+* Source position tracking for Wikidot markup.
+*
+* Every token produced by the parser can carry a {@link Position} that maps it
+* back to its original location in the source text. This is used for error
+* reporting, source-map generation, and editor integration.
+*
+* Both {@link Point} and {@link Position} follow the
+* [unist Position](https://github.com/syntax-tree/unist#position) convention:
+* lines and columns are **1-based**, offsets are **0-based**.
+*
+* @module
+*/
+/**
+* A single point in the source text.
+*
+* Represents one end (start or end) of a {@link Position} range.
+* Line and column are 1-based to match text-editor conventions;
+* offset is 0-based for direct use with `String.prototype.slice()`.
+*
+* @group Source Position
+*/
+interface Point {
+	/** Line number in the source text (1-based: the first line is line 1) */
+	line: number;
+	/** Column number within the line (1-based: the first character is column 1) */
+	column: number;
+	/** Character offset from the beginning of the source string (0-based) */
+	offset: number;
+}
+/**
+* A contiguous range in the source text, defined by a start and end {@link Point}.
+*
+* The range is inclusive of `start` and exclusive of `end` — i.e., the
+* character at `end.offset` is **not** part of the range.
+*
+* @group Source Position
+*/
+interface Position {
+	/** The first character of the range */
+	start: Point;
+	/** One past the last character of the range */
+	end: Point;
+}
+/**
+* Create a {@link Point} value.
+*
+* @param line - 1-based line number
+* @param column - 1-based column number
+* @param offset - 0-based character offset
+* @returns A frozen {@link Point} object
+*
+* @group Source Position
+*/
+declare function createPoint(line: number, column: number, offset: number): Point;
+/**
+* Create a {@link Position} range from two {@link Point}s.
+*
+* @param start - Beginning of the range (inclusive)
+* @param end - End of the range (exclusive)
+* @returns A {@link Position} spanning `start..end`
+*
+* @group Source Position
+*/
+declare function createPosition(start: Point, end: Point): Position;
 /**
 * Severity level of a diagnostic.
 *
@@ -1454,4 +1565,4 @@ interface WikitextPageContext {
 * @group Core
 */
 type Version = "wikidot";
-export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isTruthy, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, formatExprValue, evaluateExpression, createSettings, createPosition, createPoint, container, buildInfo, bold, WikitextSettings, WikitextPageFile, WikitextPageContext, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, STYLE_SLOT_PREFIX, STYLE_ANCHOR_PREFIX, Position, Point, ParseResult, PagerData, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FootnoteBlockData, FloatAlignment, ExprResult, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DiagnosticSeverity, Diagnostic, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, CssLengthUnit, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, CSS_LENGTH_UNITS, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };
+export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isTruthy, isStringContainerType, isParagraphSafe, isPageButtonAction, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, formatExprValue, extractReadableText, extractFirstParagraph, excerptText, evaluateExpression, createSettings, createPosition, createPoint, countCharacters, container, compileTextExcerpt, buildInfo, bold, WikitextSettings, WikitextPageFile, WikitextPageContext, WikitextMode, Version, VariableMap, UserData, TocEntry, TextExcerptOptions, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, SocialData, STYLE_SLOT_PREFIX, STYLE_ANCHOR_PREFIX, ReadableTextOptions, RatingVote, RatingState, RatingRef, RatingAggregate, RateModuleData, Position, Point, ParseResult, PagerData, PageRef, PageButtonData, PageButtonAction, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FootnoteBlockData, FloatAlignment, ExprResult, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DiagnosticSeverity, Diagnostic, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, CustomRateModuleData, CssLengthUnit, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, CSS_LENGTH_UNITS, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };

package/dist/index.d.ts

@@ -5,71 +5,6 @@ declare const buildInfo: Readonly<{
 	dirty: boolean | null;
 }>;
 /**
-* Source position tracking for Wikidot markup.
-*
-* Every token produced by the parser can carry a {@link Position} that maps it
-* back to its original location in the source text. This is used for error
-* reporting, source-map generation, and editor integration.
-*
-* Both {@link Point} and {@link Position} follow the
-* [unist Position](https://github.com/syntax-tree/unist#position) convention:
-* lines and columns are **1-based**, offsets are **0-based**.
-*
-* @module
-*/
-/**
-* A single point in the source text.
-*
-* Represents one end (start or end) of a {@link Position} range.
-* Line and column are 1-based to match text-editor conventions;
-* offset is 0-based for direct use with `String.prototype.slice()`.
-*
-* @group Source Position
-*/
-interface Point {
-	/** Line number in the source text (1-based: the first line is line 1) */
-	line: number;
-	/** Column number within the line (1-based: the first character is column 1) */
-	column: number;
-	/** Character offset from the beginning of the source string (0-based) */
-	offset: number;
-}
-/**
-* A contiguous range in the source text, defined by a start and end {@link Point}.
-*
-* The range is inclusive of `start` and exclusive of `end` — i.e., the
-* character at `end.offset` is **not** part of the range.
-*
-* @group Source Position
-*/
-interface Position {
-	/** The first character of the range */
-	start: Point;
-	/** One past the last character of the range */
-	end: Point;
-}
-/**
-* Create a {@link Point} value.
-*
-* @param line - 1-based line number
-* @param column - 1-based column number
-* @param offset - 0-based character offset
-* @returns A frozen {@link Point} object
-*
-* @group Source Position
-*/
-declare function createPoint(line: number, column: number, offset: number): Point;
-/**
-* Create a {@link Position} range from two {@link Point}s.
-*
-* @param start - Beginning of the range (inclusive)
-* @param end - End of the range (exclusive)
-* @returns A {@link Position} spanning `start..end`
-*
-* @group Source Position
-*/
-declare function createPosition(start: Point, end: Point): Position;
-/**
 * Shared CSS value definitions used across parser and renderer.
 *
 * @module
@@ -93,6 +28,54 @@ declare const CSS_LENGTH_UNITS: readonly ["cqmax", "cqmin", "cqw", "cqh", "cqi",
 * @group CSS
 */
 type CssLengthUnit = (typeof CSS_LENGTH_UNITS)[number];
+/** A rating always belongs to the host's displayed page. */
+type RatingRef = {
+	kind: "main";
+} | {
+	kind: "custom";
+	axisKey: string;
+};
+/** Zero is a neutral vote, not a cancellation. */
+type RatingVote = -1 | 0 | 1;
+/** Aggregates and the treatment of neutral votes are computed by the host. */
+interface RatingAggregate {
+	points: number;
+	votes: number;
+	percent: number;
+}
+/** An authorized, registered rating supplied by the host for the current viewer. */
+interface RatingState {
+	ref: RatingRef;
+	label: string;
+	/** Plain-text vote labels, e.g. { 1: "+", 0: "φ", [-1]: "-" }. Omitted entries use + / Ø / –. */
+	voteLabels?: Readonly<Partial<Record<RatingVote, string>>>;
+	/** Host policy: e.g. [1, -1], [1], [-1], or [1, 0, -1]. */
+	allowedVotes: readonly RatingVote[];
+	/** False keeps a visible, read-only widget. Omit the state to hide it entirely. */
+	canVote: boolean;
+	/** Independent of permission to cast a vote. */
+	canCancel: boolean;
+	/** Null means no vote; zero is a saved neutral vote. */
+	currentVote: RatingVote | null;
+	/** Null hides all aggregate values without preventing voting. */
+	aggregate: RatingAggregate | null;
+}
+/** `[[module Rate]]` accepts no attributes. A null reference marks an invalid declaration. */
+interface RateModuleData {
+	module: "rate";
+	ref: Extract<RatingRef, {
+		kind: "main";
+	}> | null;
+	state?: RatingState;
+}
+/** `[[module CustomRate key="theme"]]` accepts only key; it never registers or changes policy. */
+interface CustomRateModuleData {
+	module: "custom-rate";
+	ref: Extract<RatingRef, {
+		kind: "custom";
+	}> | null;
+	state?: RatingState;
+}
 /**
 * Key-value map of HTML attributes.
 * Populated from the Wikidot `_ class="foo" style="color:red"` attribute syntax.
@@ -171,7 +154,7 @@ interface AlignType {
 *
 * @group Container Types
 */
-type StringContainerType = "bold" | "italics" | "underline" | "superscript" | "subscript" | "strikethrough" | "monospace" | "span" | "div" | "blockquote" | "size" | "paragraph" | "heading" | "collapsible" | "definition-list" | "definition-list-item" | "definition-list-key" | "definition-list-value" | "table-row" | "table-cell";
+type StringContainerType = "bold" | "italics" | "underline" | "superscript" | "subscript" | "strikethrough" | "monospace" | "span" | "div" | "note" | "blockquote" | "size" | "paragraph" | "heading" | "collapsible" | "definition-list" | "definition-list-item" | "definition-list-key" | "definition-list-value" | "table-row" | "table-cell";
 /**
 * Union of all container type discriminators.
 * Every container element in the AST carries one of these to identify
@@ -498,10 +481,7 @@ type Module = {
 	"show-root": boolean;
 	/** Max depth, or null for unlimited */
 	depth: number | null;
-} | {
-	/** `[[module Rate]]` — page rating widget */
-	module: "rate";
-} | {
+} | RateModuleData | CustomRateModuleData | {
 	/** `[[module TagCloud]]` — weighted cloud of page tags */
 	module: "tag-cloud";
 	/** Numeric part of the font size for the lightest-weighted tag */
@@ -542,6 +522,7 @@ type Module = {
 	"created-at"?: string;
 	"updated-at"?: string;
 	rating?: string;
+	"rating-axis"?: string;
 	votes?: string;
 	name?: string;
 	fullname?: string;
@@ -799,9 +780,29 @@ interface DateData {
 	value: DateItem;
 	/** strftime-style format string, or null for default */
 	format: string | null;
-	/** Whether to show a tooltip with the full date on hover */
+	/** Whether to show elapsed time in a tooltip on hover */
 	hover: boolean;
 }
+/** Standalone page-option action, used by [[button action]].
+* @group Element Data
+*/
+type PageButtonAction = "edit" | "edit-append" | "edit-sections" | "history" | "print" | "files" | "tags" | "source" | "backlinks" | "talk" | "delete" | "rename" | "site-tools" | "edit-meta" | "watchers" | "parent" | "lock-page";
+/** Data for a standalone [[button]] element.
+* @group Element Data
+*/
+interface PageButtonData {
+	/** Unknown actions remain representable so the renderer can display the error. */
+	action: string;
+	text: string | null;
+	attributes: AttributeMap;
+}
+/** Data for [[social]], with null selecting the default services.
+* @group Element Data
+*/
+interface SocialData {
+	/** Unsupported names remain representable, but produce no share link. */
+	sites: string[] | null;
+}
 /**
 * Data for `##color|text##` inline color syntax.
 *
@@ -958,6 +959,8 @@ type ElementDataMap = {
 	"bibliography-block": BibliographyBlockData;
 	user: UserData;
 	date: DateData;
+	button: PageButtonData;
+	social: SocialData;
 	color: ColorData;
 	code: CodeBlockData;
 	math: MathData;
@@ -1162,6 +1165,114 @@ declare function isContainerTypeParagraphSafe(type: ContainerType): boolean;
 * @group Utilities
 */
 declare function isParagraphSafe(element: Element): boolean;
+/** Whether a standalone button names a supported page action. */
+declare function isPageButtonAction(action: string): action is PageButtonAction;
+interface ReadableTextOptions {
+	/** Exclude a subtree, for example an ACS/license container identified by the host. */
+	exclude?: (element: Element) => boolean;
+	/** Match host-rendered labels or supply text for date/math leaves. Undefined uses the default. */
+	resolveText?: (element: Extract<Element, {
+		element: "link" | "user" | "date" | "math" | "math-inline";
+	}>) => string | undefined;
+}
+/** Count graphemes, including whitespace, in the supplied readable text. */
+declare function countCharacters(text: string): number;
+/**
+* Extract semantic text from a resolved document, without executing HTML, CSS or JS.
+* Paragraph boundaries become blank lines; other whitespace is normalized. Tabs and
+* collapsibles include all panels. Footnotes are appended once, without reference UI.
+* Math/date leaves require resolveText; source TeX and timestamps are not prose.
+*/
+declare function extractReadableText(ast: SyntaxTree, options?: ReadableTextOptions): string;
+/** Extract the first nonempty paragraph, excluding headings and appended footnotes. */
+declare function extractFirstParagraph(ast: SyntaxTree, options?: ReadableTextOptions): string;
+interface TextExcerptOptions {
+	/** RE2 pattern, without / delimiters. Omit to truncate the entire text. */
+	pattern?: string;
+	/** Supported flags: i (case insensitive), m (line anchors), s (dot includes newline). */
+	flags?: string;
+	/** Capture number or name. Defaults to 0, the complete match. */
+	group?: number | string;
+	/** One-based, non-overlapping match number. Defaults to 1; maximum 10,000. */
+	match?: number;
+	/** Grapheme limit, default 200. Invalid, negative, or zero lengths return empty text. */
+	maxLength?: number;
+}
+/**
+* Compile once and reuse across pages. Invalid options, unsupported RE2 syntax, missing
+* matches/groups and exceeded limits return empty text. Regex inputs are limited to
+* 4,096 pattern code units and 1,000,000 text code units. The compiled program is limited
+* to 4,096 instructions; searches share a conservative 16,000,000-unit work budget
+* based on program size, capture count and remaining input length. No native RegExp fallback.
+*/
+declare function compileTextExcerpt(options?: TextExcerptOptions): (text: string) => string;
+/** Select a regex match/capture and truncate without splitting a grapheme cluster. */
+declare function excerptText(text: string, options?: TextExcerptOptions): string;
+/**
+* Source position tracking for Wikidot markup.
+*
+* Every token produced by the parser can carry a {@link Position} that maps it
+* back to its original location in the source text. This is used for error
+* reporting, source-map generation, and editor integration.
+*
+* Both {@link Point} and {@link Position} follow the
+* [unist Position](https://github.com/syntax-tree/unist#position) convention:
+* lines and columns are **1-based**, offsets are **0-based**.
+*
+* @module
+*/
+/**
+* A single point in the source text.
+*
+* Represents one end (start or end) of a {@link Position} range.
+* Line and column are 1-based to match text-editor conventions;
+* offset is 0-based for direct use with `String.prototype.slice()`.
+*
+* @group Source Position
+*/
+interface Point {
+	/** Line number in the source text (1-based: the first line is line 1) */
+	line: number;
+	/** Column number within the line (1-based: the first character is column 1) */
+	column: number;
+	/** Character offset from the beginning of the source string (0-based) */
+	offset: number;
+}
+/**
+* A contiguous range in the source text, defined by a start and end {@link Point}.
+*
+* The range is inclusive of `start` and exclusive of `end` — i.e., the
+* character at `end.offset` is **not** part of the range.
+*
+* @group Source Position
+*/
+interface Position {
+	/** The first character of the range */
+	start: Point;
+	/** One past the last character of the range */
+	end: Point;
+}
+/**
+* Create a {@link Point} value.
+*
+* @param line - 1-based line number
+* @param column - 1-based column number
+* @param offset - 0-based character offset
+* @returns A frozen {@link Point} object
+*
+* @group Source Position
+*/
+declare function createPoint(line: number, column: number, offset: number): Point;
+/**
+* Create a {@link Position} range from two {@link Point}s.
+*
+* @param start - Beginning of the range (inclusive)
+* @param end - End of the range (exclusive)
+* @returns A {@link Position} spanning `start..end`
+*
+* @group Source Position
+*/
+declare function createPosition(start: Point, end: Point): Position;
 /**
 * Severity level of a diagnostic.
 *
@@ -1454,4 +1565,4 @@ interface WikitextPageContext {
 * @group Core
 */
 type Version = "wikidot";
-export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isTruthy, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, formatExprValue, evaluateExpression, createSettings, createPosition, createPoint, container, buildInfo, bold, WikitextSettings, WikitextPageFile, WikitextPageContext, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, STYLE_SLOT_PREFIX, STYLE_ANCHOR_PREFIX, Position, Point, ParseResult, PagerData, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FootnoteBlockData, FloatAlignment, ExprResult, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DiagnosticSeverity, Diagnostic, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, CssLengthUnit, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, CSS_LENGTH_UNITS, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };
+export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isTruthy, isStringContainerType, isParagraphSafe, isPageButtonAction, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, formatExprValue, extractReadableText, extractFirstParagraph, excerptText, evaluateExpression, createSettings, createPosition, createPoint, countCharacters, container, compileTextExcerpt, buildInfo, bold, WikitextSettings, WikitextPageFile, WikitextPageContext, WikitextMode, Version, VariableMap, UserData, TocEntry, TextExcerptOptions, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, SocialData, STYLE_SLOT_PREFIX, STYLE_ANCHOR_PREFIX, ReadableTextOptions, RatingVote, RatingState, RatingRef, RatingAggregate, RateModuleData, Position, Point, ParseResult, PagerData, PageRef, PageButtonData, PageButtonAction, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FootnoteBlockData, FloatAlignment, ExprResult, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DiagnosticSeverity, Diagnostic, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, CustomRateModuleData, CssLengthUnit, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, CSS_LENGTH_UNITS, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };