@wdprlib/ast 4.3.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -5,71 +5,6 @@ declare const buildInfo: Readonly<{
5
5
  dirty: boolean | null;
6
6
  }>;
7
7
  /**
8
- * Source position tracking for Wikidot markup.
9
- *
10
- * Every token produced by the parser can carry a {@link Position} that maps it
11
- * back to its original location in the source text. This is used for error
12
- * reporting, source-map generation, and editor integration.
13
- *
14
- * Both {@link Point} and {@link Position} follow the
15
- * [unist Position](https://github.com/syntax-tree/unist#position) convention:
16
- * lines and columns are **1-based**, offsets are **0-based**.
17
- *
18
- * @module
19
- */
20
- /**
21
- * A single point in the source text.
22
- *
23
- * Represents one end (start or end) of a {@link Position} range.
24
- * Line and column are 1-based to match text-editor conventions;
25
- * offset is 0-based for direct use with `String.prototype.slice()`.
26
- *
27
- * @group Source Position
28
- */
29
- interface Point {
30
- /** Line number in the source text (1-based: the first line is line 1) */
31
- line: number;
32
- /** Column number within the line (1-based: the first character is column 1) */
33
- column: number;
34
- /** Character offset from the beginning of the source string (0-based) */
35
- offset: number;
36
- }
37
- /**
38
- * A contiguous range in the source text, defined by a start and end {@link Point}.
39
- *
40
- * The range is inclusive of `start` and exclusive of `end` — i.e., the
41
- * character at `end.offset` is **not** part of the range.
42
- *
43
- * @group Source Position
44
- */
45
- interface Position {
46
- /** The first character of the range */
47
- start: Point;
48
- /** One past the last character of the range */
49
- end: Point;
50
- }
51
- /**
52
- * Create a {@link Point} value.
53
- *
54
- * @param line - 1-based line number
55
- * @param column - 1-based column number
56
- * @param offset - 0-based character offset
57
- * @returns A frozen {@link Point} object
58
- *
59
- * @group Source Position
60
- */
61
- declare function createPoint(line: number, column: number, offset: number): Point;
62
- /**
63
- * Create a {@link Position} range from two {@link Point}s.
64
- *
65
- * @param start - Beginning of the range (inclusive)
66
- * @param end - End of the range (exclusive)
67
- * @returns A {@link Position} spanning `start..end`
68
- *
69
- * @group Source Position
70
- */
71
- declare function createPosition(start: Point, end: Point): Position;
72
- /**
73
8
  * Shared CSS value definitions used across parser and renderer.
74
9
  *
75
10
  * @module
@@ -93,6 +28,54 @@ declare const CSS_LENGTH_UNITS: readonly ["cqmax", "cqmin", "cqw", "cqh", "cqi",
93
28
  * @group CSS
94
29
  */
95
30
  type CssLengthUnit = (typeof CSS_LENGTH_UNITS)[number];
31
+ /** A rating always belongs to the host's displayed page. */
32
+ type RatingRef = {
33
+ kind: "main";
34
+ } | {
35
+ kind: "custom";
36
+ axisKey: string;
37
+ };
38
+ /** Zero is a neutral vote, not a cancellation. */
39
+ type RatingVote = -1 | 0 | 1;
40
+ /** Aggregates and the treatment of neutral votes are computed by the host. */
41
+ interface RatingAggregate {
42
+ points: number;
43
+ votes: number;
44
+ percent: number;
45
+ }
46
+ /** An authorized, registered rating supplied by the host for the current viewer. */
47
+ interface RatingState {
48
+ ref: RatingRef;
49
+ label: string;
50
+ /** Plain-text vote labels, e.g. { 1: "+", 0: "φ", [-1]: "-" }. Omitted entries use + / Ø / –. */
51
+ voteLabels?: Readonly<Partial<Record<RatingVote, string>>>;
52
+ /** Host policy: e.g. [1, -1], [1], [-1], or [1, 0, -1]. */
53
+ allowedVotes: readonly RatingVote[];
54
+ /** False keeps a visible, read-only widget. Omit the state to hide it entirely. */
55
+ canVote: boolean;
56
+ /** Independent of permission to cast a vote. */
57
+ canCancel: boolean;
58
+ /** Null means no vote; zero is a saved neutral vote. */
59
+ currentVote: RatingVote | null;
60
+ /** Null hides all aggregate values without preventing voting. */
61
+ aggregate: RatingAggregate | null;
62
+ }
63
+ /** `[[module Rate]]` accepts no attributes. A null reference marks an invalid declaration. */
64
+ interface RateModuleData {
65
+ module: "rate";
66
+ ref: Extract<RatingRef, {
67
+ kind: "main";
68
+ }> | null;
69
+ state?: RatingState;
70
+ }
71
+ /** `[[module CustomRate key="theme"]]` accepts only key; it never registers or changes policy. */
72
+ interface CustomRateModuleData {
73
+ module: "custom-rate";
74
+ ref: Extract<RatingRef, {
75
+ kind: "custom";
76
+ }> | null;
77
+ state?: RatingState;
78
+ }
96
79
  /**
97
80
  * Key-value map of HTML attributes.
98
81
  * Populated from the Wikidot `_ class="foo" style="color:red"` attribute syntax.
@@ -498,10 +481,7 @@ type Module = {
498
481
  "show-root": boolean;
499
482
  /** Max depth, or null for unlimited */
500
483
  depth: number | null;
501
- } | {
502
- /** `[[module Rate]]` — page rating widget */
503
- module: "rate";
504
- } | {
484
+ } | RateModuleData | CustomRateModuleData | {
505
485
  /** `[[module TagCloud]]` — weighted cloud of page tags */
506
486
  module: "tag-cloud";
507
487
  /** Numeric part of the font size for the lightest-weighted tag */
@@ -542,6 +522,7 @@ type Module = {
542
522
  "created-at"?: string;
543
523
  "updated-at"?: string;
544
524
  rating?: string;
525
+ "rating-axis"?: string;
545
526
  votes?: string;
546
527
  name?: string;
547
528
  fullname?: string;
@@ -1186,6 +1167,112 @@ declare function isContainerTypeParagraphSafe(type: ContainerType): boolean;
1186
1167
  declare function isParagraphSafe(element: Element): boolean;
1187
1168
  /** Whether a standalone button names a supported page action. */
1188
1169
  declare function isPageButtonAction(action: string): action is PageButtonAction;
1170
+ interface ReadableTextOptions {
1171
+ /** Exclude a subtree, for example an ACS/license container identified by the host. */
1172
+ exclude?: (element: Element) => boolean;
1173
+ /** Match host-rendered labels or supply text for date/math leaves. Undefined uses the default. */
1174
+ resolveText?: (element: Extract<Element, {
1175
+ element: "link" | "user" | "date" | "math" | "math-inline";
1176
+ }>) => string | undefined;
1177
+ }
1178
+ /** Count graphemes, including whitespace, in the supplied readable text. */
1179
+ declare function countCharacters(text: string): number;
1180
+ /**
1181
+ * Extract semantic text from a resolved document, without executing HTML, CSS or JS.
1182
+ * Paragraph boundaries become blank lines; other whitespace is normalized. Tabs and
1183
+ * collapsibles include all panels. Footnotes are appended once, without reference UI.
1184
+ * Math/date leaves require resolveText; source TeX and timestamps are not prose.
1185
+ */
1186
+ declare function extractReadableText(ast: SyntaxTree, options?: ReadableTextOptions): string;
1187
+ /** Extract the first nonempty paragraph, excluding headings and appended footnotes. */
1188
+ declare function extractFirstParagraph(ast: SyntaxTree, options?: ReadableTextOptions): string;
1189
+ interface TextExcerptOptions {
1190
+ /** RE2 pattern, without / delimiters. Omit to truncate the entire text. */
1191
+ pattern?: string;
1192
+ /** Supported flags: i (case insensitive), m (line anchors), s (dot includes newline). */
1193
+ flags?: string;
1194
+ /** Capture number or name. Defaults to 0, the complete match. */
1195
+ group?: number | string;
1196
+ /** One-based, non-overlapping match number. Defaults to 1; maximum 10,000. */
1197
+ match?: number;
1198
+ /** Grapheme limit, default 200. Invalid, negative, or zero lengths return empty text. */
1199
+ maxLength?: number;
1200
+ }
1201
+ /**
1202
+ * Compile once and reuse across pages. Invalid options, unsupported RE2 syntax, missing
1203
+ * matches/groups and exceeded limits return empty text. Regex inputs are limited to
1204
+ * 4,096 pattern code units and 1,000,000 text code units. The compiled program is limited
1205
+ * to 4,096 instructions; searches share a conservative 16,000,000-unit work budget
1206
+ * based on program size, capture count and remaining input length. No native RegExp fallback.
1207
+ */
1208
+ declare function compileTextExcerpt(options?: TextExcerptOptions): (text: string) => string;
1209
+ /** Select a regex match/capture and truncate without splitting a grapheme cluster. */
1210
+ declare function excerptText(text: string, options?: TextExcerptOptions): string;
1211
+ /**
1212
+ * Source position tracking for Wikidot markup.
1213
+ *
1214
+ * Every token produced by the parser can carry a {@link Position} that maps it
1215
+ * back to its original location in the source text. This is used for error
1216
+ * reporting, source-map generation, and editor integration.
1217
+ *
1218
+ * Both {@link Point} and {@link Position} follow the
1219
+ * [unist Position](https://github.com/syntax-tree/unist#position) convention:
1220
+ * lines and columns are **1-based**, offsets are **0-based**.
1221
+ *
1222
+ * @module
1223
+ */
1224
+ /**
1225
+ * A single point in the source text.
1226
+ *
1227
+ * Represents one end (start or end) of a {@link Position} range.
1228
+ * Line and column are 1-based to match text-editor conventions;
1229
+ * offset is 0-based for direct use with `String.prototype.slice()`.
1230
+ *
1231
+ * @group Source Position
1232
+ */
1233
+ interface Point {
1234
+ /** Line number in the source text (1-based: the first line is line 1) */
1235
+ line: number;
1236
+ /** Column number within the line (1-based: the first character is column 1) */
1237
+ column: number;
1238
+ /** Character offset from the beginning of the source string (0-based) */
1239
+ offset: number;
1240
+ }
1241
+ /**
1242
+ * A contiguous range in the source text, defined by a start and end {@link Point}.
1243
+ *
1244
+ * The range is inclusive of `start` and exclusive of `end` — i.e., the
1245
+ * character at `end.offset` is **not** part of the range.
1246
+ *
1247
+ * @group Source Position
1248
+ */
1249
+ interface Position {
1250
+ /** The first character of the range */
1251
+ start: Point;
1252
+ /** One past the last character of the range */
1253
+ end: Point;
1254
+ }
1255
+ /**
1256
+ * Create a {@link Point} value.
1257
+ *
1258
+ * @param line - 1-based line number
1259
+ * @param column - 1-based column number
1260
+ * @param offset - 0-based character offset
1261
+ * @returns A frozen {@link Point} object
1262
+ *
1263
+ * @group Source Position
1264
+ */
1265
+ declare function createPoint(line: number, column: number, offset: number): Point;
1266
+ /**
1267
+ * Create a {@link Position} range from two {@link Point}s.
1268
+ *
1269
+ * @param start - Beginning of the range (inclusive)
1270
+ * @param end - End of the range (exclusive)
1271
+ * @returns A {@link Position} spanning `start..end`
1272
+ *
1273
+ * @group Source Position
1274
+ */
1275
+ declare function createPosition(start: Point, end: Point): Position;
1189
1276
  /**
1190
1277
  * Severity level of a diagnostic.
1191
1278
  *
@@ -1478,4 +1565,4 @@ interface WikitextPageContext {
1478
1565
  * @group Core
1479
1566
  */
1480
1567
  type Version = "wikidot";
1481
- export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isTruthy, isStringContainerType, isParagraphSafe, isPageButtonAction, 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, SocialData, STYLE_SLOT_PREFIX, STYLE_ANCHOR_PREFIX, 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, CssLengthUnit, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, CSS_LENGTH_UNITS, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };
1568
+ 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 CHANGED
@@ -5,71 +5,6 @@ declare const buildInfo: Readonly<{
5
5
  dirty: boolean | null;
6
6
  }>;
7
7
  /**
8
- * Source position tracking for Wikidot markup.
9
- *
10
- * Every token produced by the parser can carry a {@link Position} that maps it
11
- * back to its original location in the source text. This is used for error
12
- * reporting, source-map generation, and editor integration.
13
- *
14
- * Both {@link Point} and {@link Position} follow the
15
- * [unist Position](https://github.com/syntax-tree/unist#position) convention:
16
- * lines and columns are **1-based**, offsets are **0-based**.
17
- *
18
- * @module
19
- */
20
- /**
21
- * A single point in the source text.
22
- *
23
- * Represents one end (start or end) of a {@link Position} range.
24
- * Line and column are 1-based to match text-editor conventions;
25
- * offset is 0-based for direct use with `String.prototype.slice()`.
26
- *
27
- * @group Source Position
28
- */
29
- interface Point {
30
- /** Line number in the source text (1-based: the first line is line 1) */
31
- line: number;
32
- /** Column number within the line (1-based: the first character is column 1) */
33
- column: number;
34
- /** Character offset from the beginning of the source string (0-based) */
35
- offset: number;
36
- }
37
- /**
38
- * A contiguous range in the source text, defined by a start and end {@link Point}.
39
- *
40
- * The range is inclusive of `start` and exclusive of `end` — i.e., the
41
- * character at `end.offset` is **not** part of the range.
42
- *
43
- * @group Source Position
44
- */
45
- interface Position {
46
- /** The first character of the range */
47
- start: Point;
48
- /** One past the last character of the range */
49
- end: Point;
50
- }
51
- /**
52
- * Create a {@link Point} value.
53
- *
54
- * @param line - 1-based line number
55
- * @param column - 1-based column number
56
- * @param offset - 0-based character offset
57
- * @returns A frozen {@link Point} object
58
- *
59
- * @group Source Position
60
- */
61
- declare function createPoint(line: number, column: number, offset: number): Point;
62
- /**
63
- * Create a {@link Position} range from two {@link Point}s.
64
- *
65
- * @param start - Beginning of the range (inclusive)
66
- * @param end - End of the range (exclusive)
67
- * @returns A {@link Position} spanning `start..end`
68
- *
69
- * @group Source Position
70
- */
71
- declare function createPosition(start: Point, end: Point): Position;
72
- /**
73
8
  * Shared CSS value definitions used across parser and renderer.
74
9
  *
75
10
  * @module
@@ -93,6 +28,54 @@ declare const CSS_LENGTH_UNITS: readonly ["cqmax", "cqmin", "cqw", "cqh", "cqi",
93
28
  * @group CSS
94
29
  */
95
30
  type CssLengthUnit = (typeof CSS_LENGTH_UNITS)[number];
31
+ /** A rating always belongs to the host's displayed page. */
32
+ type RatingRef = {
33
+ kind: "main";
34
+ } | {
35
+ kind: "custom";
36
+ axisKey: string;
37
+ };
38
+ /** Zero is a neutral vote, not a cancellation. */
39
+ type RatingVote = -1 | 0 | 1;
40
+ /** Aggregates and the treatment of neutral votes are computed by the host. */
41
+ interface RatingAggregate {
42
+ points: number;
43
+ votes: number;
44
+ percent: number;
45
+ }
46
+ /** An authorized, registered rating supplied by the host for the current viewer. */
47
+ interface RatingState {
48
+ ref: RatingRef;
49
+ label: string;
50
+ /** Plain-text vote labels, e.g. { 1: "+", 0: "φ", [-1]: "-" }. Omitted entries use + / Ø / –. */
51
+ voteLabels?: Readonly<Partial<Record<RatingVote, string>>>;
52
+ /** Host policy: e.g. [1, -1], [1], [-1], or [1, 0, -1]. */
53
+ allowedVotes: readonly RatingVote[];
54
+ /** False keeps a visible, read-only widget. Omit the state to hide it entirely. */
55
+ canVote: boolean;
56
+ /** Independent of permission to cast a vote. */
57
+ canCancel: boolean;
58
+ /** Null means no vote; zero is a saved neutral vote. */
59
+ currentVote: RatingVote | null;
60
+ /** Null hides all aggregate values without preventing voting. */
61
+ aggregate: RatingAggregate | null;
62
+ }
63
+ /** `[[module Rate]]` accepts no attributes. A null reference marks an invalid declaration. */
64
+ interface RateModuleData {
65
+ module: "rate";
66
+ ref: Extract<RatingRef, {
67
+ kind: "main";
68
+ }> | null;
69
+ state?: RatingState;
70
+ }
71
+ /** `[[module CustomRate key="theme"]]` accepts only key; it never registers or changes policy. */
72
+ interface CustomRateModuleData {
73
+ module: "custom-rate";
74
+ ref: Extract<RatingRef, {
75
+ kind: "custom";
76
+ }> | null;
77
+ state?: RatingState;
78
+ }
96
79
  /**
97
80
  * Key-value map of HTML attributes.
98
81
  * Populated from the Wikidot `_ class="foo" style="color:red"` attribute syntax.
@@ -498,10 +481,7 @@ type Module = {
498
481
  "show-root": boolean;
499
482
  /** Max depth, or null for unlimited */
500
483
  depth: number | null;
501
- } | {
502
- /** `[[module Rate]]` — page rating widget */
503
- module: "rate";
504
- } | {
484
+ } | RateModuleData | CustomRateModuleData | {
505
485
  /** `[[module TagCloud]]` — weighted cloud of page tags */
506
486
  module: "tag-cloud";
507
487
  /** Numeric part of the font size for the lightest-weighted tag */
@@ -542,6 +522,7 @@ type Module = {
542
522
  "created-at"?: string;
543
523
  "updated-at"?: string;
544
524
  rating?: string;
525
+ "rating-axis"?: string;
545
526
  votes?: string;
546
527
  name?: string;
547
528
  fullname?: string;
@@ -1186,6 +1167,112 @@ declare function isContainerTypeParagraphSafe(type: ContainerType): boolean;
1186
1167
  declare function isParagraphSafe(element: Element): boolean;
1187
1168
  /** Whether a standalone button names a supported page action. */
1188
1169
  declare function isPageButtonAction(action: string): action is PageButtonAction;
1170
+ interface ReadableTextOptions {
1171
+ /** Exclude a subtree, for example an ACS/license container identified by the host. */
1172
+ exclude?: (element: Element) => boolean;
1173
+ /** Match host-rendered labels or supply text for date/math leaves. Undefined uses the default. */
1174
+ resolveText?: (element: Extract<Element, {
1175
+ element: "link" | "user" | "date" | "math" | "math-inline";
1176
+ }>) => string | undefined;
1177
+ }
1178
+ /** Count graphemes, including whitespace, in the supplied readable text. */
1179
+ declare function countCharacters(text: string): number;
1180
+ /**
1181
+ * Extract semantic text from a resolved document, without executing HTML, CSS or JS.
1182
+ * Paragraph boundaries become blank lines; other whitespace is normalized. Tabs and
1183
+ * collapsibles include all panels. Footnotes are appended once, without reference UI.
1184
+ * Math/date leaves require resolveText; source TeX and timestamps are not prose.
1185
+ */
1186
+ declare function extractReadableText(ast: SyntaxTree, options?: ReadableTextOptions): string;
1187
+ /** Extract the first nonempty paragraph, excluding headings and appended footnotes. */
1188
+ declare function extractFirstParagraph(ast: SyntaxTree, options?: ReadableTextOptions): string;
1189
+ interface TextExcerptOptions {
1190
+ /** RE2 pattern, without / delimiters. Omit to truncate the entire text. */
1191
+ pattern?: string;
1192
+ /** Supported flags: i (case insensitive), m (line anchors), s (dot includes newline). */
1193
+ flags?: string;
1194
+ /** Capture number or name. Defaults to 0, the complete match. */
1195
+ group?: number | string;
1196
+ /** One-based, non-overlapping match number. Defaults to 1; maximum 10,000. */
1197
+ match?: number;
1198
+ /** Grapheme limit, default 200. Invalid, negative, or zero lengths return empty text. */
1199
+ maxLength?: number;
1200
+ }
1201
+ /**
1202
+ * Compile once and reuse across pages. Invalid options, unsupported RE2 syntax, missing
1203
+ * matches/groups and exceeded limits return empty text. Regex inputs are limited to
1204
+ * 4,096 pattern code units and 1,000,000 text code units. The compiled program is limited
1205
+ * to 4,096 instructions; searches share a conservative 16,000,000-unit work budget
1206
+ * based on program size, capture count and remaining input length. No native RegExp fallback.
1207
+ */
1208
+ declare function compileTextExcerpt(options?: TextExcerptOptions): (text: string) => string;
1209
+ /** Select a regex match/capture and truncate without splitting a grapheme cluster. */
1210
+ declare function excerptText(text: string, options?: TextExcerptOptions): string;
1211
+ /**
1212
+ * Source position tracking for Wikidot markup.
1213
+ *
1214
+ * Every token produced by the parser can carry a {@link Position} that maps it
1215
+ * back to its original location in the source text. This is used for error
1216
+ * reporting, source-map generation, and editor integration.
1217
+ *
1218
+ * Both {@link Point} and {@link Position} follow the
1219
+ * [unist Position](https://github.com/syntax-tree/unist#position) convention:
1220
+ * lines and columns are **1-based**, offsets are **0-based**.
1221
+ *
1222
+ * @module
1223
+ */
1224
+ /**
1225
+ * A single point in the source text.
1226
+ *
1227
+ * Represents one end (start or end) of a {@link Position} range.
1228
+ * Line and column are 1-based to match text-editor conventions;
1229
+ * offset is 0-based for direct use with `String.prototype.slice()`.
1230
+ *
1231
+ * @group Source Position
1232
+ */
1233
+ interface Point {
1234
+ /** Line number in the source text (1-based: the first line is line 1) */
1235
+ line: number;
1236
+ /** Column number within the line (1-based: the first character is column 1) */
1237
+ column: number;
1238
+ /** Character offset from the beginning of the source string (0-based) */
1239
+ offset: number;
1240
+ }
1241
+ /**
1242
+ * A contiguous range in the source text, defined by a start and end {@link Point}.
1243
+ *
1244
+ * The range is inclusive of `start` and exclusive of `end` — i.e., the
1245
+ * character at `end.offset` is **not** part of the range.
1246
+ *
1247
+ * @group Source Position
1248
+ */
1249
+ interface Position {
1250
+ /** The first character of the range */
1251
+ start: Point;
1252
+ /** One past the last character of the range */
1253
+ end: Point;
1254
+ }
1255
+ /**
1256
+ * Create a {@link Point} value.
1257
+ *
1258
+ * @param line - 1-based line number
1259
+ * @param column - 1-based column number
1260
+ * @param offset - 0-based character offset
1261
+ * @returns A frozen {@link Point} object
1262
+ *
1263
+ * @group Source Position
1264
+ */
1265
+ declare function createPoint(line: number, column: number, offset: number): Point;
1266
+ /**
1267
+ * Create a {@link Position} range from two {@link Point}s.
1268
+ *
1269
+ * @param start - Beginning of the range (inclusive)
1270
+ * @param end - End of the range (exclusive)
1271
+ * @returns A {@link Position} spanning `start..end`
1272
+ *
1273
+ * @group Source Position
1274
+ */
1275
+ declare function createPosition(start: Point, end: Point): Position;
1189
1276
  /**
1190
1277
  * Severity level of a diagnostic.
1191
1278
  *
@@ -1478,4 +1565,4 @@ interface WikitextPageContext {
1478
1565
  * @group Core
1479
1566
  */
1480
1567
  type Version = "wikidot";
1481
- export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isTruthy, isStringContainerType, isParagraphSafe, isPageButtonAction, 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, SocialData, STYLE_SLOT_PREFIX, STYLE_ANCHOR_PREFIX, 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, CssLengthUnit, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, CSS_LENGTH_UNITS, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };
1568
+ 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 };