@wdprlib/parser 3.2.0 → 4.1.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Position as Position2, Point, Version as Version2, Element as Element6, SyntaxTree as SyntaxTree3, ContainerType, ContainerData, AttributeMap, VariableMap, Alignment, LinkType, LinkLocation, LinkLabel, PageRef as PageRef2, ImageSource, FloatAlignment, ListType, ListItem, ListData, CodeBlockData as CodeBlockData2, TabData, TableCell, TableRow, TableData, DefinitionListItem, Module as Module4, CollapsibleData, ClearFloat, AnchorTarget, HeaderType, AlignType, HeadingLevel, Heading, DateItem, Embed, TocEntry as TocEntry2, Diagnostic as Diagnostic2, DiagnosticSeverity, ParseResult as ParseResult2 } from "@wdprlib/ast";
+import { Position as Position2, Point, Version as Version2, Element as Element7, SyntaxTree as SyntaxTree3, ContainerType, ContainerData, AttributeMap, VariableMap, Alignment, LinkType, LinkLocation, LinkLabel, PageRef as PageRef3, ImageSource, FloatAlignment, ListType, ListItem, ListData, CodeBlockData as CodeBlockData2, TabData, TableCell, TableRow, TableData, DefinitionListItem, Module as Module4, CollapsibleData, ClearFloat, AnchorTarget, HeaderType, AlignType, HeadingLevel, Heading, DateItem, Embed, TocEntry as TocEntry2, Diagnostic as Diagnostic2, DiagnosticSeverity, ParseResult as ParseResult3 } from "@wdprlib/ast";
 import { createPoint, createPosition, text, container, paragraph, bold, italics, heading, lineBreak, horizontalRule, link, list, listItemElements, listItemSubList } from "@wdprlib/ast";
 import { WikitextMode, WikitextSettings as WikitextSettings4 } from "@wdprlib/ast";
 import { createSettings, DEFAULT_SETTINGS } from "@wdprlib/ast";
@@ -62,6 +62,12 @@ interface LexerOptions {
 	* when source-map information is not needed.
 	*/
 	trackPositions?: boolean;
+	/**
+	* Coalesce ordinary text outside `[[...]]` openers into larger TEXT tokens.
+	* This keeps block names and attributes tokenized normally while reducing
+	* token volume for large documents.
+	*/
+	compactTextRuns?: boolean;
 }
 /**
 * Converts a Wikidot markup source string into a flat array of {@link Token}s.
@@ -80,6 +86,7 @@ declare class Lexer {
 	private state;
 	private options;
 	private splitBlockClosePositions;
+	private lastNonWhitespaceType;
 	/**
 	* Nesting depth of block-opener context (between `[[` / `[[/` and the
 	* matching `]]`). Used to scope `QUOTED_STRING` recognition so that
@@ -111,10 +118,6 @@ declare class Lexer {
 	*/
 	private findInvalidAnchorNameEnd;
 	/**
-	* Check if source matches pattern at current position
-	*/
-	private match;
-	/**
 	* Advance position by n characters
 	*/
 	private advance;
@@ -126,14 +129,12 @@ declare class Lexer {
 	* Add token
 	*/
 	private addToken;
+	private emitTokenAction;
+	private emitTokenActions;
 	/**
 	* Scan a single token
 	*/
 	private scanToken;
-	/**
-	* Check if character is alphanumeric (for identifier tokens)
-	*/
-	private isAlphanumeric;
 }
 /**
 * Tokenise a Wikidot markup source string in one call.
@@ -147,7 +148,8 @@ declare class Lexer {
 * @group Lexer
 */
 declare function tokenize(source: string, options?: LexerOptions): Token[];
-import { WikitextSettings, ParseResult } from "@wdprlib/ast";
+import { ParseResult as ParseResult2 } from "@wdprlib/ast";
+import { WikitextSettings } from "@wdprlib/ast";
 /**
 * Configuration for the {@link Parser} and the {@link parse} function.
 *
@@ -171,41 +173,26 @@ interface ParserOptions {
 	settings?: WikitextSettings;
 	/**
 	* Page tags consulted when expanding `[[iftags]]` directives that are
-	* embedded inside another block's opener — e.g.
-	* `[[div_ class="x" [[iftags +foo]]style="..."[[/iftags]]]]`. Such
-	* iftags must be collapsed at text level *before* tokenization;
-	* otherwise the outer opener loses its well-formed structure and the
-	* whole `[[div_ ... ]]` line is emitted as raw text.
+	* embedded inside another block's opener.
 	*
 	* Values:
-	* - omitted / `undefined`: no preprocess pass. Existing behaviour;
-	*   opener-embedded iftags will still break the surrounding opener.
-	* - `null`: opener-embedded iftags only, evaluated as if the page has
-	*   no tags (lossy fallback that keeps tokenization working when real
-	*   tags are unknown). Block-level iftags remain in the AST for
-	*   `resolveModules` to evaluate later via `getPageTags`.
-	* - `string[]`: every iftags block is evaluated against the given
-	*   tags eagerly; no `if-tags` nodes survive in the AST.
+	* - omitted / `undefined`: no preprocess pass.
+	* - `null`: opener-embedded iftags only, evaluated as if the page has no tags.
+	* - `string[]`: every iftags block is evaluated against the given tags eagerly.
 	*/
 	pageTags?: string[] | null;
 }
+import { ParseResult } from "@wdprlib/ast";
 /**
 * Converts a token stream into a Wikidot {@link SyntaxTree}.
 *
-* The parser consumes tokens produced by the `Lexer` and emits a
-* tree of {@link Element} nodes. Block-level rules are tried in priority
-* order; when none match, the fallback paragraph rule collects inline
-* tokens until the next blank line.
-*
-* After the main parse pass, two post-processing steps run:
+* The parser consumes tokens produced by the `Lexer` and emits a tree of
+* {@link Element} nodes. Block-level rules are tried in priority order; when
+* none match, the fallback paragraph rule collects inline tokens until the
+* next blank line.
 *
-* 1. **Span-strip merging** — `[[span_]]` elements that set
-*    `_paragraphStrip` are merged with adjacent paragraphs.
-* 2. **Internal-flag cleanup** — all `_`-prefixed bookkeeping fields
-*    are removed from the final AST.
-*
-* For most use-cases the standalone {@link parse} function is simpler
-* than constructing a `Parser` directly.
+* For most use-cases the standalone {@link parse} function is simpler than
+* constructing a `Parser` directly.
 *
 * @group Parser
 */
@@ -219,26 +206,10 @@ declare class Parser {
 	* @since 2.0.0
 	*/
 	parse(): ParseResult;
-	/**
-	* Check if at end of tokens
-	*/
 	private isAtEnd;
-	/**
-	* Get current token
-	*/
 	private currentToken;
-	/**
-	* Create EOF token
-	*/
 	private eofToken;
-	/**
-	* Skip whitespace tokens
-	*/
 	private skipWhitespace;
-	/**
-	* Parse block element(s)
-	* Returns an array because some rules (like list) may return multiple elements
-	*/
 	private parseBlock;
 }
 /**
@@ -253,8 +224,8 @@ declare class Parser {
 *
 * @since 2.0.0
 */
-declare function parse(source: string, options?: ParserOptions): ParseResult;
-import { Element as Element2 } from "@wdprlib/ast";
+declare function parse(source: string, options?: ParserOptions): ParseResult2;
+import { Element as Element3 } from "@wdprlib/ast";
 /**
 * Parser function type for re-parsing substituted template output as wikitext.
 *
@@ -266,9 +237,62 @@ import { Element as Element2 } from "@wdprlib/ast";
 * @returns Object containing the parsed elements
 */
 type ParseFunction = (input: string) => {
-	elements: Element2[];
+	elements: Element3[];
 };
 /**
+* ListPages query parameters for page selection.
+*
+* @security All string fields contain untrusted user input from wikitext.
+* When using these values in database queries:
+* - NEVER interpolate directly into SQL/NoSQL query strings.
+* - ALWAYS use parameterized queries or prepared statements.
+* - For ORDER BY clauses, use a whitelist of allowed column names.
+*/
+interface ListPagesQuery {
+	/** Page type selector */
+	pagetype?: "normal" | "hidden" | "*";
+	/** Category selector. @untrusted User input - use parameterized queries. */
+	category?: string;
+	/** Tag selector, e.g. "+fruit -admin". @untrusted User input. */
+	tags?: string;
+	/** Parent page selector. @untrusted User input. */
+	parent?: string;
+	/** Link target selector. @untrusted User input. */
+	linkTo?: string;
+	/** Created date selector. @untrusted User input. */
+	createdAt?: string;
+	/** Updated date selector. @untrusted User input. */
+	updatedAt?: string;
+	/** Author selector. @untrusted User input. */
+	createdBy?: string;
+	/** Rating selector. @untrusted User input. */
+	rating?: string;
+	/** Votes selector. @untrusted User input. */
+	votes?: string;
+	/** Page name selector. @untrusted User input. */
+	name?: string;
+	/** Full page name selector (category:name). @untrusted User input. */
+	fullname?: string;
+	/** Range selector relative to current page */
+	range?: "." | "before" | "after" | "others";
+	/** Data form field selectors. @untrusted Both keys and values are user input. */
+	dataFormFields?: Record<string, string>;
+	/** Ordering specification. @untrusted Use whitelist validation for ORDER BY. */
+	order?: string;
+	/** Pagination offset */
+	offset?: number;
+	/** Maximum number of results */
+	limit?: number;
+	/** Results per page */
+	perPage?: number;
+	/** Reverse order */
+	reverse?: boolean;
+}
+/**
+* All supported ListPages template variables.
+*/
+type ListPagesVariable = "created_at" | "created_by" | "created_by_unix" | "created_by_id" | "created_by_linked" | "updated_at" | "updated_by" | "updated_by_unix" | "updated_by_id" | "updated_by_linked" | "commented_at" | "commented_by" | "commented_by_unix" | "commented_by_id" | "commented_by_linked" | "name" | "category" | "fullname" | "title" | "title_linked" | "link" | "parent_name" | "parent_category" | "parent_fullname" | "parent_title" | "parent_title_linked" | "content" | "content_n" | "preview" | "preview_n" | "summary" | "first_paragraph" | "tags" | "tags_linked" | "_tags" | "_tags_linked" | "form_data" | "form_raw" | "form_label" | "form_hint" | "children" | "comments" | "size" | "rating" | "rating_votes" | "rating_percent" | "revisions" | "index" | "total" | "limit" | "total_or_limit" | "site_title" | "site_name" | "site_domain";
+/**
 *
 * Type definitions for the ListUsers module.
 *
@@ -353,126 +377,7 @@ interface ListUsersVariableContext {
 */
 type ListUsersCompiledTemplate = (ctx: ListUsersVariableContext) => string;
 /**
-*
-* Type definitions for the ListPages module system.
-*
-* This file defines the complete type vocabulary for the ListPages lifecycle:
-*
-* - **Query types**: Raw and normalized representations of ListPages filter/sort parameters
-* - **Variable types**: The `%%variable%%` names supported in ListPages templates
-* - **Data requirement types**: What the parser tells the application it needs to fetch
-* - **External data types**: What the application provides back (page data, user info, site context)
-* - **Template types**: Compiled template function signatures and their execution context
-* - **Normalized query types**: Structured representations of parsed query parameters
-*
-* Security note: Several fields contain untrusted user input from wikitext.
-* See `ListPagesQuery` documentation for safe usage guidelines.
-*
-* @module
-*/
-/**
-* ListPages query parameters for page selection
-*
-* @security All string fields contain **untrusted user input** from wikitext.
-* When using these values in database queries:
-* - **NEVER** interpolate directly into SQL/NoSQL query strings
-* - **ALWAYS** use parameterized queries or prepared statements
-* - For ORDER BY clauses, use a whitelist of allowed column names
-*
-* @example Safe usage with SQL
-* ```typescript
-* // GOOD: Parameterized query
-* db.query("SELECT * FROM pages WHERE category = ?", [query.category]);
-*
-* // BAD: String interpolation (SQL injection vulnerable!)
-* db.query(`SELECT * FROM pages WHERE category = '${query.category}'`);
-* ```
-*/
-interface ListPagesQuery {
-	/** Page type selector */
-	pagetype?: "normal" | "hidden" | "*";
-	/**
-	* Category selector
-	* @untrusted User input - use parameterized queries
-	*/
-	category?: string;
-	/**
-	* Tag selector (e.g., "+fruit -admin")
-	* @untrusted User input - use parameterized queries
-	*/
-	tags?: string;
-	/**
-	* Parent page selector
-	* @untrusted User input - use parameterized queries
-	*/
-	parent?: string;
-	/**
-	* Link target selector
-	* @untrusted User input - use parameterized queries
-	*/
-	linkTo?: string;
-	/**
-	* Created date selector
-	* @untrusted User input - use parameterized queries
-	*/
-	createdAt?: string;
-	/**
-	* Updated date selector
-	* @untrusted User input - use parameterized queries
-	*/
-	updatedAt?: string;
-	/**
-	* Author selector
-	* @untrusted User input - use parameterized queries
-	*/
-	createdBy?: string;
-	/**
-	* Rating selector
-	* @untrusted User input - use parameterized queries
-	*/
-	rating?: string;
-	/**
-	* Votes selector
-	* @untrusted User input - use parameterized queries
-	*/
-	votes?: string;
-	/**
-	* Page name selector
-	* @untrusted User input - use parameterized queries
-	*/
-	name?: string;
-	/**
-	* Full page name selector (category:name)
-	* @untrusted User input - use parameterized queries
-	*/
-	fullname?: string;
-	/** Range selector relative to current page */
-	range?: "." | "before" | "after" | "others";
-	/**
-	* Data form field selectors
-	* @untrusted Both keys and values are user input
-	*/
-	dataFormFields?: Record<string, string>;
-	/**
-	* Ordering specification
-	* @untrusted User input - use whitelist validation for ORDER BY
-	*/
-	order?: string;
-	/** Pagination offset */
-	offset?: number;
-	/** Maximum number of results */
-	limit?: number;
-	/** Results per page */
-	perPage?: number;
-	/** Reverse order */
-	reverse?: boolean;
-}
-/**
-* All supported ListPages template variables
-*/
-type ListPagesVariable = "created_at" | "created_by" | "created_by_unix" | "created_by_id" | "created_by_linked" | "updated_at" | "updated_by" | "updated_by_unix" | "updated_by_id" | "updated_by_linked" | "commented_at" | "commented_by" | "commented_by_unix" | "commented_by_id" | "commented_by_linked" | "name" | "category" | "fullname" | "title" | "title_linked" | "link" | "parent_name" | "parent_category" | "parent_fullname" | "parent_title" | "parent_title_linked" | "content" | "content_n" | "preview" | "preview_n" | "summary" | "first_paragraph" | "tags" | "tags_linked" | "_tags" | "_tags_linked" | "form_data" | "form_raw" | "form_label" | "form_hint" | "children" | "comments" | "size" | "rating" | "rating_votes" | "rating_percent" | "revisions" | "index" | "total" | "limit" | "total_or_limit" | "site_title" | "site_name" | "site_domain";
-/**
-* Data requirement for a single ListPages module
+* Data requirement for a single ListPages module.
 */
 interface ListPagesDataRequirement {
 	/** Unique identifier for this module instance */
@@ -485,33 +390,32 @@ interface ListPagesDataRequirement {
 	contentSectionIndices?: number[];
 	/** Lengths needed for preview(n) */
 	previewLengths?: number[];
-	/** Field names needed for form_data{field} etc */
+	/** Field names needed for form_data{field} etc. */
 	formFields?: string[];
 	/** Prefix for tags_linked|prefix */
 	tagsLinkPrefix?: string;
 	/** Prefix for _tags_linked|prefix */
 	hiddenTagsLinkPrefix?: string;
 	/**
-	* URL attribute prefix for multiple ListPages modules
-	* When set, URL parameters are prefixed (e.g., "page2" -> "/page2_limit/1")
+	* URL attribute prefix for multiple ListPages modules.
+	* When set, URL parameters are prefixed, e.g. "page2" -> "/page2_limit/1".
 	*/
 	urlAttrPrefix?: string;
 	/**
-	* Raw attribute values before URL resolution
-	* Contains original string values that may include "@URL" or "@URL|default" format
-	* External applications should use these to resolve URL parameters
+	* Raw attribute values before URL resolution.
+	* Contains original string values that may include "@URL" or "@URL|default".
 	*/
 	rawAttributes: Record<string, string>;
 }
 /**
-* All data requirements from parsing
+* All data requirements from parsing.
 */
 interface DataRequirements {
 	listPages: ListPagesDataRequirement[];
 	listUsers: ListUsersDataRequirement[];
 }
 /**
-* User information
+* User information.
 */
 interface UserInfo {
 	id: number;
@@ -519,7 +423,7 @@ interface UserInfo {
 	unixName: string;
 }
 /**
-* Page data provided by external source
+* Page data provided by an external source.
 */
 interface PageData {
 	name: string;
@@ -552,7 +456,7 @@ interface PageData {
 	revisions: number;
 }
 /**
-* Site context information
+* Site context information.
 */
 interface SiteContext {
 	title: string;
@@ -560,7 +464,7 @@ interface SiteContext {
 	domain: string;
 }
 /**
-* External data for a single ListPages module
+* External data for a single ListPages module.
 */
 interface ListPagesExternalData {
 	pages: PageData[];
@@ -568,73 +472,48 @@ interface ListPagesExternalData {
 	site: SiteContext;
 }
 /**
-* Callback to fetch data for a ListPages module
-*
-* Called by resolveModules for each ListPages module in the AST.
-* Receives a normalized query with all `@URL` parameters resolved.
-* Return null/undefined to skip the module (outputs nothing).
-*
-* @param query - Normalized query with structured types (tags, category, order, etc.)
-* @param requirement - Original data requirement (for accessing id, neededVariables, etc.)
-*/
-type ListPagesDataFetcher = (query: NormalizedListPagesQuery, requirement: ListPagesDataRequirement) => ListPagesExternalData | null | undefined | Promise<ListPagesExternalData | null | undefined>;
-/**
-* Context passed to compiled template
-*/
-interface VariableContext {
-	page: PageData;
-	index: number;
-	total: number;
-	limit?: number;
-	site: SiteContext;
-}
-/**
-* Compiled template function
-*/
-type CompiledTemplate = (ctx: VariableContext) => string;
-/**
-* Normalized tags selector
+* Normalized tags selector.
 */
 interface NormalizedTags {
-	/** AND conditions - pages must have ALL of these tags (+tag) */
+	/** AND conditions - pages must have all of these tags (+tag). */
 	all: string[];
-	/** OR conditions - pages must have ANY of these tags (no prefix) */
+	/** OR conditions - pages must have any of these tags (no prefix). */
 	any: string[];
-	/** NOT conditions - pages must NOT have these tags (-tag) */
+	/** NOT conditions - pages must not have these tags (-tag). */
 	none: string[];
-	/** Special selector */
+	/** Special selector. */
 	special: "same-visible" | "same-all" | "none" | null;
 }
 /**
-* Normalized category selector
+* Normalized category selector.
 */
 interface NormalizedCategory {
-	/** Categories to include */
+	/** Categories to include. */
 	include: string[];
-	/** Categories to exclude (-category) */
+	/** Categories to exclude (-category). */
 	exclude: string[];
-	/** Select all categories (*) */
+	/** Select all categories (*). */
 	all: boolean;
-	/** Select current category (.) */
+	/** Select current category (.). */
 	current: boolean;
 }
 /**
-* Order field options
+* Order field options.
 */
 type OrderField = "created_at" | "updated_at" | "title" | "fullname" | "rating" | "votes" | "revisions" | "comments" | "size" | "random";
 /**
-* Order direction
+* Order direction.
 */
 type OrderDirection = "asc" | "desc";
 /**
-* Normalized order specification
+* Normalized order specification.
 */
 interface NormalizedOrder {
 	field: OrderField;
 	direction: OrderDirection;
 }
 /**
-* Normalized parent selector
+* Normalized parent selector.
 */
 type NormalizedParent = {
 	type: "none";
@@ -649,11 +528,11 @@ type NormalizedParent = {
 	name: string;
 };
 /**
-* Date comparison operators
+* Date comparison operators.
 */
 type DateComparisonOp = "=" | "<" | ">" | "<=" | ">=" | "<>";
 /**
-* Normalized date selector
+* Normalized date selector.
 */
 type NormalizedDateSelector = {
 	type: "year";
@@ -672,24 +551,21 @@ type NormalizedDateSelector = {
 	count: number;
 };
 /**
-* Numeric comparison operators
+* Numeric comparison operators.
 */
 type NumericComparisonOp = "=" | "<" | ">" | "<=" | ">=";
 /**
-* Normalized numeric selector (for rating/votes)
+* Normalized numeric selector for rating/votes.
 */
 interface NormalizedNumericSelector {
 	op: NumericComparisonOp;
 	value: number;
 }
 /**
-* Fully normalized ListPages query
+* Fully normalized ListPages query.
 *
-* All string fields are parsed and structured into type-safe objects.
-* Use `normalizeQuery()` to convert from `ListPagesQuery`.
-*
-* Note: This is structural normalization, not full validation.
-* Invalid inputs are either rejected (return undefined) or ignored.
+* All string fields are parsed into structured selector objects. Use
+* `normalizeQuery()` to convert from `ListPagesQuery`.
 */
 interface NormalizedListPagesQuery {
 	pagetype?: "normal" | "hidden" | "*";
@@ -713,6 +589,28 @@ interface NormalizedListPagesQuery {
 	reverse?: boolean;
 }
 /**
+* Callback to fetch data for a ListPages module.
+*
+* Called by resolveModules for each ListPages module in the AST. Receives a
+* normalized query with all `@URL` parameters resolved. Return null/undefined
+* to skip the module.
+*/
+type ListPagesDataFetcher = (query: NormalizedListPagesQuery, requirement: ListPagesDataRequirement) => ListPagesExternalData | null | undefined | Promise<ListPagesExternalData | null | undefined>;
+/**
+* Context passed to a compiled ListPages template.
+*/
+interface VariableContext {
+	page: PageData;
+	index: number;
+	total: number;
+	limit?: number;
+	site: SiteContext;
+}
+/**
+* Compiled template function.
+*/
+type CompiledTemplate = (ctx: VariableContext) => string;
+/**
 * Callback to retrieve the current page's tags during the resolve phase.
 *
 * Called when evaluating `[[iftags]]` conditions. The application must provide
@@ -721,6 +619,107 @@ interface NormalizedListPagesQuery {
 * @returns Array of tag names for the current page
 */
 type IfTagsResolver = () => string[];
+import { PageRef as PageRef2, WikitextSettings as WikitextSettings3 } from "@wdprlib/ast";
+interface IncludeAssignment {
+	key: string;
+	value: string;
+}
+/**
+* Callback to fetch page content for include resolution.
+* Returns the wikitext source of the page, or null if the page does not exist.
+*
+* @security The fetcher is called with user-provided page references.
+* Implementations should validate and sanitize page references before
+* using them in database queries or file system access.
+*/
+type IncludeFetcher = (pageRef: PageRef2) => string | null;
+/**
+* Async callback to fetch page content for include resolution.
+* Returns a promise of the wikitext source, or null if the page does not exist.
+*
+* @security The fetcher is called with user-provided page references.
+* Implementations should validate and sanitize page references before
+* using them in database queries or file system access.
+*/
+type AsyncIncludeFetcher = (pageRef: PageRef2) => Promise<string | null>;
+/**
+* Options for resolveIncludes / resolveIncludesAsync.
+*/
+interface ResolveIncludesOptions {
+	/**
+	* Maximum number of expansion iterations (default: 10).
+	*
+	* Each iteration replaces all `[[include]]` directives in the current
+	* source with fetched content. Iteration stops when the source is
+	* unchanged or this limit is reached.
+	*/
+	maxIterations?: number;
+	/** Wikitext settings. If enablePageSyntax is false, includes are not expanded. */
+	settings?: WikitextSettings3;
+}
+/**
+* A single include directive found in raw source text.
+*
+* This represents the directive as it existed during the include expansion
+* phase. It does not imply that the target exists, and it does not include
+* nested dependencies introduced by the target source.
+*/
+interface IncludeReference {
+	/** Target page reference parsed from the directive. */
+	location: PageRef2;
+	/** Variable assignments parsed from the directive, preserving source order. */
+	assignments: IncludeAssignment[];
+	/** Index of the opening `[[`. */
+	start: number;
+	/** Index just past the closing `]]`. */
+	end: number;
+	/** Text between `[[include ` and the closing `]]`. */
+	inner: string;
+}
+/**
+* Include dependency observed during iterative expansion.
+*
+* Unlike `IncludeReference`, this is collected after a fetchable include layer
+* has actually been expanded. If an included page introduces another include,
+* that nested directive appears as a later `IncludeDependency` with a higher
+* `iteration`.
+*/
+interface IncludeDependency extends IncludeReference {
+	/** Zero-based expansion iteration where this directive was observed. */
+	iteration: number;
+}
+/**
+* Trace data for one include expansion iteration.
+*
+* `directives` is the scan result before replacements for that iteration.
+* `changed` is false for stable self-includes where replacing the directive
+* produces the same source again; the resolver stops at that point.
+*/
+interface IncludeIterationTrace {
+	/** Zero-based expansion iteration. */
+	iteration: number;
+	/** Include directives found in the source for this iteration. */
+	directives: IncludeReference[];
+	/** Whether replacing the directives changed the source. */
+	changed: boolean;
+}
+/**
+* Result returned by trace-enabled include expansion.
+*
+* The `source` field is intended to be byte-for-byte equivalent to
+* `resolveIncludes(source, fetcher, options)` for the same inputs. The rest of
+* the object is diagnostic data for dependency collection and cache planning.
+*/
+interface ResolveIncludesTraceResult {
+	/** Final expanded source. */
+	source: string;
+	/** Include dependencies observed across all expansion iterations. */
+	dependencies: IncludeDependency[];
+	/** Per-iteration include scan and change information. */
+	iterations: IncludeIterationTrace[];
+	/** True when expansion stopped with directives still present after hitting the iteration cap. */
+	reachedMaxIterations: boolean;
+}
 /**
 * Callback bag for supplying external data during module resolution.
 *
@@ -752,6 +751,15 @@ interface DataProvider {
 	*/
 	fetchListUsers?: ListUsersDataFetcher;
 	/**
+	* Fetch raw wikitext for `[[include]]` directives that are created during
+	* module secondary transformations such as ListPages/ListUsers item rendering.
+	*
+	* Top-level include expansion still uses `resolveIncludes()` directly before
+	* parsing. This callback is only for module-rendered wikitext that needs its
+	* own include pass before being parsed again.
+	*/
+	fetchInclude?: IncludeFetcher;
+	/**
 	* Return the current page's tags for `[[iftags]]` evaluation.
 	*
 	* If provided, `[[iftags]]` blocks are evaluated and either kept or
@@ -803,70 +811,27 @@ declare function extractDataRequirements(ast: SyntaxTree): ExtractionResult;
 */
 declare function compileTemplate(template: string): CompiledTemplate;
 /**
-* Parse tags string into structured format
-*
-* Syntax:
-* - `+tag`: AND condition (must have this tag)
-* - `-tag`: NOT condition (must not have this tag)
-* - `tag`: OR condition (any of these tags)
-* - `=`: same visible tags as current page
-* - `==`: exact same tags as current page
-* - `-`: pages with no tags
+* Parse tags string into structured format.
 */
 declare function parseTags(value: string): NormalizedTags;
 /**
-* Parse category string into structured format
-*
-* Syntax:
-* - `*`: all categories
-* - `.`: current category
-* - `-category`: exclude category
-* - `category`: include category
-* - Multiple categories separated by comma, semicolon, or whitespace
+* Parse category string into structured format.
 */
 declare function parseCategory(value: string): NormalizedCategory;
 /**
-* Parse order string into structured format
-*
-* Supports both formats:
-* - camelCase: `dateCreatedDesc`, `titleAsc`, `ratingDesc`
-* - Space-separated: `created_at desc`, `title asc`
-*
-* Default: { field: "created_at", direction: "desc" }
+* Parse order string into structured format.
 */
 declare function parseOrder(value: string): NormalizedOrder;
 /**
-* Parse parent string into structured format
-*
-* Syntax:
-* - `-`: orphan pages (no parent)
-* - `=`: sibling pages (same parent as current)
-* - `-=`: pages with different parent
-* - `.`: children of current page
-* - `page-name`: children of specific page
-*
-* Returns undefined for empty/whitespace-only input.
+* Parse parent string into structured format.
 */
 declare function parseParent(value: string): NormalizedParent | undefined;
 /**
-* Parse date selector string into structured format
-*
-* Syntax:
-* - `yyyy`: year only
-* - `yyyy.mm`: year and month
-* - `>=yyyy.mm.dd`: comparison with date
-* - `last 7 days`: relative date
+* Parse date selector string into structured format.
 */
 declare function parseDateSelector(value: string): NormalizedDateSelector | undefined;
 /**
-* Parse numeric selector string into structured format
-*
-* Syntax:
-* - `5`: equals 5
-* - `>=10`: greater than or equal to 10
-* - `<0`: less than 0
-*
-* Returns undefined for non-numeric or infinite values.
+* Parse numeric selector string into structured format.
 */
 declare function parseNumericSelector(value: string): NormalizedNumericSelector | undefined;
 /**
@@ -897,71 +862,49 @@ declare function normalizeQuery(query: ListPagesQuery): NormalizedListPagesQuery
 *          unmatched iftags removed entirely.
 */
 declare function preprocessIftags(source: string, pageTags: string[] | null): string;
-import { PageRef, WikitextSettings as WikitextSettings3 } from "@wdprlib/ast";
-/**
-* Callback to fetch page content for include resolution.
-* Returns the wikitext source of the page, or null if the page does not exist.
-*
-* @security The fetcher is called with user-provided page references.
-* Implementations should validate and sanitize page references before
-* using them in database queries or file system access.
-*/
-type IncludeFetcher = (pageRef: PageRef) => string | null;
-/**
-* Async callback to fetch page content for include resolution.
-* Returns a promise of the wikitext source, or null if the page does not exist.
-*
-* @security The fetcher is called with user-provided page references.
-* Implementations should validate and sanitize page references before
-* using them in database queries or file system access.
-*/
-type AsyncIncludeFetcher = (pageRef: PageRef) => Promise<string | null>;
-/**
-* Options for resolveIncludes / resolveIncludesAsync
-*/
-interface ResolveIncludesOptions {
-	/**
-	* Maximum number of expansion iterations (default: 10).
-	*
-	* Each iteration replaces all `[[include]]` directives in the current
-	* source with fetched content. Iteration stops when the source is
-	* unchanged or this limit is reached.
-	*/
-	maxIterations?: number;
-	/** Wikitext settings. If enablePageSyntax is false, includes are not expanded. */
-	settings?: WikitextSettings3;
-}
 /**
 * Expand all [[include]] directives in the source text.
 *
 * Uses Wikidot-compatible iterative expansion: each iteration replaces
-* all include directives in the current source with fetched (and
-* variable-substituted) content. Iteration continues until no further
+* all include directives in the current source with fetched and
+* variable-substituted content. Iteration continues until no further
 * changes occur or `maxIterations` is reached.
-*
-* @example
-* ```ts
-* const expanded = resolveIncludes(source, fetcher);
-* const ast = parse(expanded);
-* ```
 */
 declare function resolveIncludes(source: string, fetcher: IncludeFetcher, options?: ResolveIncludesOptions): string;
 /**
+* Expand all [[include]] directives and return dependency/iteration trace data.
+*
+* This follows the same sync expansion behavior as {@link resolveIncludes};
+* the additional trace data is intended for application-level dependency
+* graphs, cache invalidation, and diagnostics.
+*/
+declare function resolveIncludesWithTrace(source: string, fetcher: IncludeFetcher, options?: ResolveIncludesOptions): ResolveIncludesTraceResult;
+/**
 * Async version of {@link resolveIncludes}.
 *
 * Expand all [[include]] directives using an async fetcher, allowing
 * page content to be loaded from async sources such as databases.
-*
-* @example
-* ```ts
-* const expanded = await resolveIncludesAsync(source, async (ref) => {
-*   return await db.getPageContent(ref.page);
-* });
-* const ast = parse(expanded);
-* ```
 */
 declare function resolveIncludesAsync(source: string, fetcher: AsyncIncludeFetcher, options?: ResolveIncludesOptions): Promise<string>;
 /**
+* Extract include directives from raw source without fetching or expanding them.
+*
+* This uses the same scanner and directive parser as `resolveIncludes`, so it
+* reports only directives that the include expansion pass would recognize.
+*
+* This is a source-phase API. It intentionally does not evaluate later syntax
+* such as comments, expressions, or iftags. Wikidot expands includes before
+* those phases, so an include inside a later comment block is still reported,
+* while a token that only becomes `[[include ...]]` after comment/expression/
+* iftags processing is not reported.
+*
+* The result is not a complete transitive dependency graph. Nested includes
+* only become visible after fetching and expanding the current layer; use
+* `resolveIncludesWithTrace` when the caller needs observed dependency edges
+* across iterative expansion.
+*/
+declare function extractIncludeReferences(source: string, options?: ResolveIncludesOptions): IncludeReference[];
+/**
 * Compile a ListUsers template string into an executable function.
 *
 * The template is split into alternating static strings and dynamic getter
@@ -981,7 +924,7 @@ declare function compileListUsersTemplate(template: string): ListUsersCompiledTe
 * @returns Deduplicated array of referenced variable names
 */
 declare function extractListUsersVariables(template: string): ListUsersVariable[];
-import { Element as Element5, Module as Module3 } from "@wdprlib/ast";
+import { Element as Element6, Module as Module3 } from "@wdprlib/ast";
 /**
 * Narrowed type for the list-users variant of the Module discriminated union.
 */
@@ -1008,9 +951,22 @@ declare function isListUsersModule(module: Module3): module is ListUsersModuleDa
 * @param parse - Parser function for re-parsing the substituted template as wikitext
 * @returns Array of AST elements produced by parsing the rendered template
 */
-declare function resolveListUsers(_module: ListUsersModuleData, data: ListUsersExternalData, compiledTemplate: ListUsersCompiledTemplate, parse: ParseFunction): Element5[];
+declare function resolveListUsers(_module: ListUsersModuleData, data: ListUsersExternalData, compiledTemplate: ListUsersCompiledTemplate, parse: ParseFunction): Element6[];
 import { SyntaxTree as SyntaxTree2 } from "@wdprlib/ast";
 /**
+* Transform module-generated wikitext before it is parsed back into AST nodes.
+*
+* Applications can use this hook to inject include resolution, parse caches, or
+* diagnostics for ListPages/ListUsers secondary transformations.
+*
+* This hook receives the string after module variables such as `%%title%%` have
+* already been substituted. Returning a different string changes what is parsed
+* for that module item. When this hook is supplied it replaces the built-in
+* secondary include pass, so callers that still need Wikidot-style secondary
+* includes must call `resolveIncludes()` or equivalent logic from the hook.
+*/
+type ModuleSourceTransform = (source: string) => string;
+/**
 * Configuration for {@link resolveModules}.
 *
 * Callers must supply pre-extracted requirements and pre-compiled
@@ -1043,6 +999,26 @@ interface ResolveOptions {
 	* with the corresponding values from this path.
 	*/
 	urlPath?: string;
+	/**
+	* Maximum include expansion iterations for secondary transformations inside
+	* modules such as ListPages/ListUsers. Defaults to Wikidot's observed
+	* secondary transformation limit.
+	*/
+	includeMaxIterations?: number;
+	/**
+	* Transform module-generated wikitext before re-parsing it.
+	*
+	* When omitted, `resolveModules()` preserves the existing default: if
+	* `dataProvider.fetchInclude` is present, secondary `[[include]]` expansion
+	* is performed with `includeMaxIterations`; otherwise the source is parsed
+	* unchanged. When supplied, this hook owns the whole transformation.
+	*
+	* This is the extension point for application-level parse/include caches. The
+	* parser package does not persist cache entries itself because cache keys and
+	* invalidation depend on site/page revisions, tags, URL parameters, and user
+	* state outside wdpr.
+	*/
+	transformModuleSource?: ModuleSourceTransform;
 }
 /**
 * Resolve all modules in the AST
@@ -1060,4 +1036,4 @@ interface ResolveOptions {
 */
 declare function resolveModules(ast: SyntaxTree2, dataProvider: DataProvider, options: ResolveOptions): Promise<SyntaxTree2>;
 import { STYLE_SLOT_PREFIX } from "@wdprlib/ast";
-export { tokenize, text, resolveModules, resolveListUsers, resolveIncludesAsync, resolveIncludes, preprocessIftags, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractDataRequirements, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, WikitextSettings4 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree3 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseResult2 as ParseResult, ParseFunction, PageRef2 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeFetcher, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element6 as Element, DiagnosticSeverity, Diagnostic2 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };
+export { tokenize, text, resolveModules, resolveListUsers, resolveIncludesWithTrace, resolveIncludesAsync, resolveIncludes, preprocessIftags, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractIncludeReferences, extractDataRequirements, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, WikitextSettings4 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree3 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesTraceResult, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseResult3 as ParseResult, ParseFunction, PageRef3 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, ModuleSourceTransform, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeReference, IncludeIterationTrace, IncludeFetcher, IncludeDependency, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element7 as Element, DiagnosticSeverity, Diagnostic2 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };