@wdprlib/parser 1.1.0 → 1.1.1

package/dist/index.cjs

@@ -6003,10 +6003,8 @@ var newlineLineBreakRule = {
     }
     const nextMeaningfulToken = ctx.tokens[ctx.pos + lookAhead];
     let isValidBlock = isBlockStartToken(nextMeaningfulToken?.type);
-    if (isValidBlock && (nextMeaningfulToken?.type === "LIST_BULLET" || nextMeaningfulToken?.type === "LIST_NUMBER")) {
-      if (!nextMeaningfulToken.lineStart) {
-        isValidBlock = false;
-      }
+    if (isValidBlock && !nextMeaningfulToken?.lineStart) {
+      isValidBlock = false;
     }
     if (isValidBlock && nextMeaningfulToken?.type === "HEADING_MARKER") {
       const markerLen = nextMeaningfulToken.value.length;
@@ -7753,6 +7751,7 @@ var bibciteRule = {
       return { success: false };
     }
     let label = "";
+    let foundClose = false;
     while (pos < ctx.tokens.length) {
       const t = ctx.tokens[pos];
       if (!t)
@@ -7761,6 +7760,7 @@ var bibciteRule = {
         const nextT = ctx.tokens[pos + 1];
         if (nextT?.type === "TEXT" && nextT.value === ")") {
           consumed += 2;
+          foundClose = true;
           break;
         }
       }
@@ -7771,6 +7771,9 @@ var bibciteRule = {
       pos++;
       consumed++;
     }
+    if (!foundClose) {
+      return { success: false };
+    }
     label = label.trim();
     if (!label) {
       return { success: false };
@@ -9627,16 +9630,31 @@ function resolveIncludes(source, fetcher, options) {
   };
   return expandText(source, cachedFetcher, 0, maxDepth, []);
 }
-var INCLUDE_PATTERN = /\[\[include\s+([\s\S]*?)\]\]/gi;
+var INCLUDE_PATTERN = /\[\[include\s([^\]]*(?:\](?!\])[^\]]*)*)\]\]/gi;
 function parseIncludeDirective(inner) {
   const normalized = inner.replace(/\n/g, " ");
   const parts = normalized.split("|");
-  const target = parts[0].trim();
-  const variables = {};
+  const firstSegment = parts[0].trim();
+  const spaceIndex = firstSegment.indexOf(" ");
+  let target;
+  const varSegments = [];
+  if (spaceIndex !== -1) {
+    target = firstSegment.slice(0, spaceIndex);
+    const rest = firstSegment.slice(spaceIndex + 1).trim();
+    if (rest) {
+      varSegments.push(rest);
+    }
+  } else {
+    target = firstSegment;
+  }
   for (let i = 1;i < parts.length; i++) {
     const segment = parts[i].trim();
-    if (!segment)
-      continue;
+    if (segment) {
+      varSegments.push(segment);
+    }
+  }
+  const variables = {};
+  for (const segment of varSegments) {
     const eqIndex = segment.indexOf("=");
     if (eqIndex !== -1) {
       const key = segment.slice(0, eqIndex).trim();

package/dist/index.d.cts

@@ -4,32 +4,77 @@ import { WikitextMode, WikitextSettings as WikitextSettings4 } from "@wdprlib/as
 import { createSettings, DEFAULT_SETTINGS } from "@wdprlib/ast";
 import { Position } from "@wdprlib/ast";
 /**
-* Token types for Wikidot markup
+* Every distinct lexeme the Wikidot lexer can produce.
+*
+* Each value corresponds to a fixed character sequence (or class of
+* sequences) in Wikidot markup. The inline comments show the literal
+* text that produces each token type.
+*
+* @group Lexer
 */
 type TokenType = "EOF" | "TEXT" | "IDENTIFIER" | "NEWLINE" | "WHITESPACE" | "BLOCK_OPEN" | "BLOCK_CLOSE" | "BLOCK_END_OPEN" | "BOLD_MARKER" | "ITALIC_MARKER" | "UNDERLINE_MARKER" | "STRIKE_MARKER" | "SUPER_MARKER" | "SUB_MARKER" | "MONO_MARKER" | "MONO_CLOSE" | "HEADING_MARKER" | "HR_MARKER" | "LIST_BULLET" | "LIST_NUMBER" | "BLOCKQUOTE_MARKER" | "TABLE_MARKER" | "TABLE_HEADER" | "TABLE_LEFT" | "TABLE_CENTER" | "TABLE_RIGHT" | "CODE_OPEN" | "CODE_CLOSE" | "LINK_OPEN" | "LINK_CLOSE" | "BRACKET_OPEN" | "BRACKET_CLOSE" | "BRACKET_ANCHOR" | "BRACKET_STAR" | "PIPE" | "EQUALS" | "COLON" | "SLASH" | "STAR" | "HASH" | "AT" | "AMPERSAND" | "BACKSLASH" | "QUOTED_STRING" | "RAW_OPEN" | "RAW_CLOSE" | "RAW_BLOCK_OPEN" | "RAW_BLOCK_CLOSE" | "COLOR_MARKER" | "UNDERSCORE" | "BACKSLASH_BREAK" | "COMMENT_OPEN" | "COMMENT_CLOSE" | "CLEAR_FLOAT" | "CLEAR_FLOAT_LEFT" | "CLEAR_FLOAT_RIGHT" | "LEFT_DOUBLE_ANGLE" | "RIGHT_DOUBLE_ANGLE";
 /**
-* Token
+* A single lexical token produced by the `Lexer`.
+*
+* Tokens are the input to the parser stage. Each token carries its
+* literal text (`value`), source location (`position`), and a flag
+* indicating whether it appeared at the beginning of a line — which
+* matters because several Wikidot constructs (headings, lists,
+* blockquotes, horizontal rules) are only valid at line start.
+*
+* @group Lexer
 */
 interface Token {
+	/** The lexeme category */
 	type: TokenType;
+	/** The literal source text that produced this token */
 	value: string;
+	/** Start/end location in the original source string */
 	position: Position;
-	/** Whether this token appears at the start of a line */
+	/**
+	* `true` when this token is the first non-whitespace token on its
+	* line. Block-level rules (headings, lists, blockquotes) check this
+	* flag before attempting to match.
+	*/
 	lineStart: boolean;
 }
 /**
-* Create a token
+* Construct a {@link Token} value.
+*
+* @param type - The lexeme category
+* @param value - Literal source text
+* @param position - Source location range
+* @param lineStart - Whether the token starts a new line
+* @returns A new token object
+*
+* @group Lexer
 */
 declare function createToken(type: TokenType, value: string, position: Position, lineStart?: boolean): Token;
 /**
-* Lexer options
+* Configuration for the {@link Lexer}.
+*
+* @group Lexer
 */
 interface LexerOptions {
-	/** Track position information */
+	/**
+	* When `true` (default), every token carries accurate line/column/offset
+	* data. Set to `false` to skip position tracking for faster tokenisation
+	* when source-map information is not needed.
+	*/
 	trackPositions?: boolean;
 }
 /**
-* Wikidot markup lexer
+* Converts a Wikidot markup source string into a flat array of {@link Token}s.
+*
+* The lexer is single-pass and greedy: it tries the longest-matching
+* multi-character pattern first (e.g. `[[[` before `[[`, `**` before `*`).
+* Context-sensitive constructs (line-start headings, blockquote markers)
+* are disambiguated via the `lineStart` state flag.
+*
+* For convenience, use the standalone {@link tokenize} function instead
+* of constructing a `Lexer` directly.
+*
+* @group Lexer
 */
 declare class Lexer {
 	private state;
@@ -78,23 +123,59 @@ declare class Lexer {
 	private isAlphanumeric;
 }
 /**
-* Tokenize source string
+* Tokenise a Wikidot markup source string in one call.
+*
+* Shorthand for `new Lexer(source, options).tokenize()`.
+*
+* @param source - Raw Wikidot markup
+* @param options - Optional lexer configuration
+* @returns A flat array of tokens, ending with an `EOF` token
+*
+* @group Lexer
 */
 declare function tokenize(source: string, options?: LexerOptions): Token[];
 import { SyntaxTree, WikitextSettings } from "@wdprlib/ast";
 /**
-* Parser options
+* Configuration for the {@link Parser} and the {@link parse} function.
+*
+* All fields are optional; sensible defaults are applied when omitted.
+*
+* @group Parser
 */
 interface ParserOptions {
-	/** Wikidot version */
+	/** Markup dialect. Currently only `"wikidot"` is supported. */
 	version?: "wikidot";
-	/** Track position information */
+	/**
+	* Propagate source-position data into every AST node.
+	* Defaults to `true`. Set to `false` for smaller output when positions
+	* are not needed.
+	*/
 	trackPositions?: boolean;
-	/** Wikitext settings controlling syntax availability */
+	/**
+	* Context-dependent feature flags (page vs. forum-post, etc.).
+	* Defaults to {@link DEFAULT_SETTINGS} (full page mode).
+	*/
 	settings?: WikitextSettings;
 }
 /**
-* Wikidot markup parser
+* 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:
+*
+* 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.
+*
+* @group Parser
 */
 declare class Parser {
 	private ctx;
@@ -131,58 +212,119 @@ declare class Parser {
 declare function parse(source: string, options?: ParserOptions): SyntaxTree;
 import { Element as Element2 } from "@wdprlib/ast";
 /**
-* Parser function type for re-parsing substituted templates
-* Used by ListPages and ListUsers modules
+* Parser function type for re-parsing substituted template output as wikitext.
+*
+* Used by ListPages and ListUsers modules during the resolution phase. After
+* template variables are substituted with actual data, the resulting string
+* needs to be parsed as wikitext to produce AST elements.
+*
+* @param input - Wikitext string to parse
+* @returns Object containing the parsed elements
 */
 type ParseFunction = (input: string) => {
 	elements: Element2[];
 };
 /**
-* ListUsers module types
+*
+* Type definitions for the ListUsers module.
+*
+* The `[[module ListUsers users="."]]` block displays information about site
+* members. Currently, only `users="."` (the logged-in user) is supported.
+* The template body can reference three variables: `%%number%%`, `%%title%%`,
+* and `%%name%%`.
+*
+* @module
 */
 /**
-* Supported template variables
+* Supported template variables for ListUsers.
+*
+* - `number` - The user's numeric ID
+* - `title` - The user's display title/nickname
+* - `name` - The user's account name
 */
 type ListUsersVariable = "number" | "title" | "name";
 /**
-* User data provided by external source
+* User data that must be provided by the external data source.
+*
+* Each field corresponds to a template variable of the same name.
 */
 interface ListUsersUserData {
+	/** The user's numeric ID, rendered by `%%number%%` */
 	number: number;
+	/** The user's display title, rendered by `%%title%%` */
 	title: string;
+	/** The user's account name, rendered by `%%name%%` */
 	name: string;
 }
 /**
-* Data requirement for a single ListUsers module
+* Data requirement for a single ListUsers module instance.
+*
+* Produced by the extraction phase and consumed by the application to
+* determine what data to fetch.
 */
 interface ListUsersDataRequirement {
+	/** Unique identifier for this module instance (sequential, 0-based) */
 	id: number;
+	/** The `users` attribute value (currently only `"."` is supported) */
 	users: string;
+	/** Template variables that need data from the external source */
 	neededVariables: ListUsersVariable[];
 }
 /**
-* External data for a single ListUsers module
-* Note: ListUsers returns only the logged-in user
+* External data provided by the application for a single ListUsers module.
+*
+* Currently ListUsers only returns information about the logged-in user.
+* Return null/undefined from the fetcher to indicate no user is logged in.
 */
 interface ListUsersExternalData {
+	/** Data for the logged-in user */
 	user: ListUsersUserData;
 }
 /**
-* Callback to fetch data for a ListUsers module
+* Callback to fetch user data for a ListUsers module.
+*
+* Called during the resolution phase for each ListUsers module in the AST.
+* Return null/undefined to skip the module (outputs nothing, e.g., when
+* no user is logged in).
+*
+* @param requirement - The data requirement describing what data is needed
+* @returns User data, null/undefined to skip, or a Promise of the same
 */
 type ListUsersDataFetcher = (requirement: ListUsersDataRequirement) => ListUsersExternalData | null | undefined | Promise<ListUsersExternalData | null | undefined>;
 /**
-* Context passed to compiled template
+* Context passed to a compiled ListUsers template function during rendering.
 */
 interface ListUsersVariableContext {
+	/** The user whose data is being rendered */
 	user: ListUsersUserData;
 }
 /**
-* Compiled template function
+* A compiled ListUsers template function.
+*
+* Accepts a variable context and returns the rendered wikitext string
+* with all `%%variable%%` placeholders substituted.
+*
+* @param ctx - The variable context containing user data
+* @returns Rendered wikitext string
 */
 type ListUsersCompiledTemplate = (ctx: ListUsersVariableContext) => string;
 /**
-* ListPages module types
+*
+* 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
@@ -385,7 +527,7 @@ interface ListPagesExternalData {
 * 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.
+* 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.)
@@ -527,47 +669,60 @@ interface NormalizedListPagesQuery {
 	reverse?: boolean;
 }
 /**
-* Callback to get current page's tags
+* Callback to retrieve the current page's tags during the resolve phase.
 *
-* Called during resolve phase to evaluate [[iftags]] conditions.
+* Called when evaluating `[[iftags]]` conditions. The application must provide
+* this callback with access to the current page's tag list.
 *
 * @returns Array of tag names for the current page
 */
 type IfTagsResolver = () => string[];
 /**
-* Data provider interface for resolving modules that require external data
+* Callback bag for supplying external data during module resolution.
 *
-* All callbacks are optional - if not provided, the corresponding
-* module/syntax will be output as-is in the AST without resolution.
+* Pass an instance to `resolveModules()`. Every callback is optional:
+* when a callback is missing the corresponding module node is kept as-is
+* in the output AST — useful when you only need to resolve a subset of
+* modules (e.g. only `[[iftags]]` on the client side).
 *
-* Note: Include resolution is handled separately via resolveIncludes().
+* @group Module Resolution
 */
 interface DataProvider {
 	/**
-	* Fetch data for ListPages module
-	* Called during resolve phase with query parameters
+	* Fetch page data for `[[module ListPages]]` expansion.
 	*
-	* @security `req.query` / `req.rawAttributes` are **untrusted user input** from wikitext.
-	* When building database queries:
-	* - **NEVER** interpolate them into SQL strings
-	* - **ALWAYS** use parameterized queries / prepared statements
-	* - For `order` (ORDER BY), use a whitelist of allowed column names
+	* Called once per ListPages instance in the AST with the normalised
+	* query parameters extracted from the module's wikitext attributes.
+	*
+	* @security The query fields originate from **untrusted user input**.
+	* When building database queries from the returned requirement:
+	* - **Never** interpolate `req.query` / `req.rawAttributes` into SQL
+	* - **Always** use parameterised queries or prepared statements
+	* - For `order` (ORDER BY), validate against a whitelist of column names
 	*/
 	fetchListPages?: ListPagesDataFetcher;
 	/**
-	* Fetch data for ListUsers module
-	* Called during resolve phase with user query parameters
+	* Fetch user data for `[[module ListUsers]]` expansion.
+	*
+	* Called once per ListUsers instance with the parsed query parameters.
 	*/
 	fetchListUsers?: ListUsersDataFetcher;
 	/**
-	* Get current page's tags for iftags evaluation
-	* Called during resolve phase to evaluate [[iftags]] conditions
+	* Return the current page's tags for `[[iftags]]` evaluation.
+	*
+	* If provided, `[[iftags]]` blocks are evaluated and either kept or
+	* discarded based on whether the page's tags satisfy the condition.
+	* If omitted, `[[iftags]]` blocks pass through unresolved.
 	*/
 	getPageTags?: IfTagsResolver;
 }
 import { SyntaxTree as SyntaxTree2 } from "@wdprlib/ast";
 /**
-* Result of extraction including compiled templates
+* Complete result of extracting data requirements from an AST.
+*
+* Contains everything needed to fetch external data and then resolve modules:
+* the data requirements tell the application what to fetch, and the pre-compiled
+* templates are used during the resolution phase to efficiently render results.
 */
 interface ExtractionResult {
 	/** Data requirements for external fetching */
@@ -578,11 +733,29 @@ interface ExtractionResult {
 	compiledListUsersTemplates: Map<number, ListUsersCompiledTemplate>;
 }
 /**
-* Extract data requirements from a parsed AST
+* Extract all data requirements from a parsed AST.
+*
+* Walks the entire AST to find ListPages and ListUsers module elements,
+* analyzes their templates to determine which variables are used, builds
+* query objects from their attributes, and pre-compiles their templates.
+*
+* Each module is assigned a sequential ID (separate counters for ListPages
+* and ListUsers) that is used to correlate requirements with fetched data
+* and compiled templates during the resolution phase.
+*
+* @param ast - The parsed syntax tree to analyze
+* @returns Extraction result containing requirements and compiled templates
 */
 declare function extractDataRequirements(ast: SyntaxTree2): ExtractionResult;
 /**
-* Compile a template string into an executable function
+* Compile a ListPages template string into an executable function.
+*
+* The template is split into alternating static strings and dynamic getter
+* functions. The returned function concatenates these parts with the getter
+* functions evaluated against the provided variable context.
+*
+* @param template - The template string containing `%%variable%%` placeholders
+* @returns A compiled function that accepts a `VariableContext` and returns the rendered string
 */
 declare function compileTemplate(template: string): CompiledTemplate;
 /**
@@ -694,49 +867,85 @@ interface ResolveIncludesOptions {
 */
 declare function resolveIncludes(source: string, fetcher: IncludeFetcher, options?: ResolveIncludesOptions): string;
 /**
-* Compile a template string into an executable function
+* Compile a ListUsers template string into an executable function.
+*
+* The template is split into alternating static strings and dynamic getter
+* functions. The returned function concatenates these parts for each call.
+*
+* @param template - The template string containing `%%variable%%` placeholders
+* @returns A compiled function that accepts a `ListUsersVariableContext` and returns rendered text
 */
 declare function compileListUsersTemplate(template: string): ListUsersCompiledTemplate;
 /**
-* Extract needed variables from a template string
+* Extract the set of template variables referenced in a ListUsers template string.
+*
+* Scans for `%%variable%%` patterns and returns only those that match known
+* ListUsers variables. Unknown variables are silently ignored.
+*
+* @param template - The template string from the module body
+* @returns Deduplicated array of referenced variable names
 */
 declare function extractListUsersVariables(template: string): ListUsersVariable[];
 import { Element as Element5, Module as Module3 } from "@wdprlib/ast";
 /**
-* ListUsers module data type
+* Narrowed type for the list-users variant of the Module discriminated union.
 */
 type ListUsersModuleData = Extract<Module3, {
 	module: "list-users";
 }>;
 /**
-* Type guard for list-users module
+* Type guard to check if a Module is a list-users module.
+*
+* @param module - A Module discriminated union value
+* @returns true if the module is a list-users module
 */
 declare function isListUsersModule(module: Module3): module is ListUsersModuleData;
 /**
-* Resolve a single ListUsers module
-* Note: ListUsers returns only the logged-in user
+* Resolve a single ListUsers module by substituting fetched user data into
+* the pre-compiled template and re-parsing the result as wikitext.
+*
+* Currently ListUsers only renders the logged-in user (no iteration over
+* multiple users), so the template is executed exactly once.
+*
+* @param _module - The list-users module data from the AST (unused, reserved for future use)
+* @param data - External user data fetched by the application
+* @param compiledTemplate - Pre-compiled template function from the extraction phase
+* @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[];
 import { SyntaxTree as SyntaxTree3 } from "@wdprlib/ast";
 /**
-* Options for resolving modules
+* Configuration for {@link resolveModules}.
+*
+* Callers must supply pre-extracted requirements and pre-compiled
+* templates (obtained from `extractDataRequirements()` and
+* `compileTemplate()` / `compileListUsersTemplate()`).
+*
+* @group Module Resolution
 */
 interface ResolveOptions {
-	/** Parser function for re-parsing templates */
+	/** Parser function used to re-parse expanded template markup into AST nodes */
 	parse: ParseFunction;
-	/** Pre-compiled templates for ListPages */
+	/** Pre-compiled ListPages body templates, keyed by requirement ID */
 	compiledListPagesTemplates: Map<number, CompiledTemplate>;
-	/** Pre-compiled templates for ListUsers */
+	/** Pre-compiled ListUsers body templates, keyed by requirement ID */
 	compiledListUsersTemplates?: Map<number, ListUsersCompiledTemplate>;
-	/** Data requirements grouped by module type */
+	/**
+	* Data requirements grouped by module type.
+	* Obtained from `extractDataRequirements()`.
+	*/
 	requirements: {
 		listPages?: ListPagesDataRequirement[];
 		listUsers?: ListUsersDataRequirement[];
 	};
 	/**
-	* URL path for @URL parameter resolution (HPC support)
-	* Format: "/page-name/param/value/param/value"
-	* Example: "/scp-001/offset/10/page2_limit/5"
+	* URL path for `@URL` parameter resolution (HPC / pagination support).
+	*
+	* Wikidot encodes pagination state in the URL path as key/value pairs
+	* after the page name, e.g. `"/scp-001/offset/10/page2_limit/5"`.
+	* When provided, `@URL` references in ListPages queries are replaced
+	* with the corresponding values from this path.
 	*/
 	urlPath?: string;
 }

package/dist/index.d.ts

@@ -4,32 +4,77 @@ import { WikitextMode, WikitextSettings as WikitextSettings4 } from "@wdprlib/as
 import { createSettings, DEFAULT_SETTINGS } from "@wdprlib/ast";
 import { Position } from "@wdprlib/ast";
 /**
-* Token types for Wikidot markup
+* Every distinct lexeme the Wikidot lexer can produce.
+*
+* Each value corresponds to a fixed character sequence (or class of
+* sequences) in Wikidot markup. The inline comments show the literal
+* text that produces each token type.
+*
+* @group Lexer
 */
 type TokenType = "EOF" | "TEXT" | "IDENTIFIER" | "NEWLINE" | "WHITESPACE" | "BLOCK_OPEN" | "BLOCK_CLOSE" | "BLOCK_END_OPEN" | "BOLD_MARKER" | "ITALIC_MARKER" | "UNDERLINE_MARKER" | "STRIKE_MARKER" | "SUPER_MARKER" | "SUB_MARKER" | "MONO_MARKER" | "MONO_CLOSE" | "HEADING_MARKER" | "HR_MARKER" | "LIST_BULLET" | "LIST_NUMBER" | "BLOCKQUOTE_MARKER" | "TABLE_MARKER" | "TABLE_HEADER" | "TABLE_LEFT" | "TABLE_CENTER" | "TABLE_RIGHT" | "CODE_OPEN" | "CODE_CLOSE" | "LINK_OPEN" | "LINK_CLOSE" | "BRACKET_OPEN" | "BRACKET_CLOSE" | "BRACKET_ANCHOR" | "BRACKET_STAR" | "PIPE" | "EQUALS" | "COLON" | "SLASH" | "STAR" | "HASH" | "AT" | "AMPERSAND" | "BACKSLASH" | "QUOTED_STRING" | "RAW_OPEN" | "RAW_CLOSE" | "RAW_BLOCK_OPEN" | "RAW_BLOCK_CLOSE" | "COLOR_MARKER" | "UNDERSCORE" | "BACKSLASH_BREAK" | "COMMENT_OPEN" | "COMMENT_CLOSE" | "CLEAR_FLOAT" | "CLEAR_FLOAT_LEFT" | "CLEAR_FLOAT_RIGHT" | "LEFT_DOUBLE_ANGLE" | "RIGHT_DOUBLE_ANGLE";
 /**
-* Token
+* A single lexical token produced by the `Lexer`.
+*
+* Tokens are the input to the parser stage. Each token carries its
+* literal text (`value`), source location (`position`), and a flag
+* indicating whether it appeared at the beginning of a line — which
+* matters because several Wikidot constructs (headings, lists,
+* blockquotes, horizontal rules) are only valid at line start.
+*
+* @group Lexer
 */
 interface Token {
+	/** The lexeme category */
 	type: TokenType;
+	/** The literal source text that produced this token */
 	value: string;
+	/** Start/end location in the original source string */
 	position: Position;
-	/** Whether this token appears at the start of a line */
+	/**
+	* `true` when this token is the first non-whitespace token on its
+	* line. Block-level rules (headings, lists, blockquotes) check this
+	* flag before attempting to match.
+	*/
 	lineStart: boolean;
 }
 /**
-* Create a token
+* Construct a {@link Token} value.
+*
+* @param type - The lexeme category
+* @param value - Literal source text
+* @param position - Source location range
+* @param lineStart - Whether the token starts a new line
+* @returns A new token object
+*
+* @group Lexer
 */
 declare function createToken(type: TokenType, value: string, position: Position, lineStart?: boolean): Token;
 /**
-* Lexer options
+* Configuration for the {@link Lexer}.
+*
+* @group Lexer
 */
 interface LexerOptions {
-	/** Track position information */
+	/**
+	* When `true` (default), every token carries accurate line/column/offset
+	* data. Set to `false` to skip position tracking for faster tokenisation
+	* when source-map information is not needed.
+	*/
 	trackPositions?: boolean;
 }
 /**
-* Wikidot markup lexer
+* Converts a Wikidot markup source string into a flat array of {@link Token}s.
+*
+* The lexer is single-pass and greedy: it tries the longest-matching
+* multi-character pattern first (e.g. `[[[` before `[[`, `**` before `*`).
+* Context-sensitive constructs (line-start headings, blockquote markers)
+* are disambiguated via the `lineStart` state flag.
+*
+* For convenience, use the standalone {@link tokenize} function instead
+* of constructing a `Lexer` directly.
+*
+* @group Lexer
 */
 declare class Lexer {
 	private state;
@@ -78,23 +123,59 @@ declare class Lexer {
 	private isAlphanumeric;
 }
 /**
-* Tokenize source string
+* Tokenise a Wikidot markup source string in one call.
+*
+* Shorthand for `new Lexer(source, options).tokenize()`.
+*
+* @param source - Raw Wikidot markup
+* @param options - Optional lexer configuration
+* @returns A flat array of tokens, ending with an `EOF` token
+*
+* @group Lexer
 */
 declare function tokenize(source: string, options?: LexerOptions): Token[];
 import { SyntaxTree, WikitextSettings } from "@wdprlib/ast";
 /**
-* Parser options
+* Configuration for the {@link Parser} and the {@link parse} function.
+*
+* All fields are optional; sensible defaults are applied when omitted.
+*
+* @group Parser
 */
 interface ParserOptions {
-	/** Wikidot version */
+	/** Markup dialect. Currently only `"wikidot"` is supported. */
 	version?: "wikidot";
-	/** Track position information */
+	/**
+	* Propagate source-position data into every AST node.
+	* Defaults to `true`. Set to `false` for smaller output when positions
+	* are not needed.
+	*/
 	trackPositions?: boolean;
-	/** Wikitext settings controlling syntax availability */
+	/**
+	* Context-dependent feature flags (page vs. forum-post, etc.).
+	* Defaults to {@link DEFAULT_SETTINGS} (full page mode).
+	*/
 	settings?: WikitextSettings;
 }
 /**
-* Wikidot markup parser
+* 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:
+*
+* 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.
+*
+* @group Parser
 */
 declare class Parser {
 	private ctx;
@@ -131,58 +212,119 @@ declare class Parser {
 declare function parse(source: string, options?: ParserOptions): SyntaxTree;
 import { Element as Element2 } from "@wdprlib/ast";
 /**
-* Parser function type for re-parsing substituted templates
-* Used by ListPages and ListUsers modules
+* Parser function type for re-parsing substituted template output as wikitext.
+*
+* Used by ListPages and ListUsers modules during the resolution phase. After
+* template variables are substituted with actual data, the resulting string
+* needs to be parsed as wikitext to produce AST elements.
+*
+* @param input - Wikitext string to parse
+* @returns Object containing the parsed elements
 */
 type ParseFunction = (input: string) => {
 	elements: Element2[];
 };
 /**
-* ListUsers module types
+*
+* Type definitions for the ListUsers module.
+*
+* The `[[module ListUsers users="."]]` block displays information about site
+* members. Currently, only `users="."` (the logged-in user) is supported.
+* The template body can reference three variables: `%%number%%`, `%%title%%`,
+* and `%%name%%`.
+*
+* @module
 */
 /**
-* Supported template variables
+* Supported template variables for ListUsers.
+*
+* - `number` - The user's numeric ID
+* - `title` - The user's display title/nickname
+* - `name` - The user's account name
 */
 type ListUsersVariable = "number" | "title" | "name";
 /**
-* User data provided by external source
+* User data that must be provided by the external data source.
+*
+* Each field corresponds to a template variable of the same name.
 */
 interface ListUsersUserData {
+	/** The user's numeric ID, rendered by `%%number%%` */
 	number: number;
+	/** The user's display title, rendered by `%%title%%` */
 	title: string;
+	/** The user's account name, rendered by `%%name%%` */
 	name: string;
 }
 /**
-* Data requirement for a single ListUsers module
+* Data requirement for a single ListUsers module instance.
+*
+* Produced by the extraction phase and consumed by the application to
+* determine what data to fetch.
 */
 interface ListUsersDataRequirement {
+	/** Unique identifier for this module instance (sequential, 0-based) */
 	id: number;
+	/** The `users` attribute value (currently only `"."` is supported) */
 	users: string;
+	/** Template variables that need data from the external source */
 	neededVariables: ListUsersVariable[];
 }
 /**
-* External data for a single ListUsers module
-* Note: ListUsers returns only the logged-in user
+* External data provided by the application for a single ListUsers module.
+*
+* Currently ListUsers only returns information about the logged-in user.
+* Return null/undefined from the fetcher to indicate no user is logged in.
 */
 interface ListUsersExternalData {
+	/** Data for the logged-in user */
 	user: ListUsersUserData;
 }
 /**
-* Callback to fetch data for a ListUsers module
+* Callback to fetch user data for a ListUsers module.
+*
+* Called during the resolution phase for each ListUsers module in the AST.
+* Return null/undefined to skip the module (outputs nothing, e.g., when
+* no user is logged in).
+*
+* @param requirement - The data requirement describing what data is needed
+* @returns User data, null/undefined to skip, or a Promise of the same
 */
 type ListUsersDataFetcher = (requirement: ListUsersDataRequirement) => ListUsersExternalData | null | undefined | Promise<ListUsersExternalData | null | undefined>;
 /**
-* Context passed to compiled template
+* Context passed to a compiled ListUsers template function during rendering.
 */
 interface ListUsersVariableContext {
+	/** The user whose data is being rendered */
 	user: ListUsersUserData;
 }
 /**
-* Compiled template function
+* A compiled ListUsers template function.
+*
+* Accepts a variable context and returns the rendered wikitext string
+* with all `%%variable%%` placeholders substituted.
+*
+* @param ctx - The variable context containing user data
+* @returns Rendered wikitext string
 */
 type ListUsersCompiledTemplate = (ctx: ListUsersVariableContext) => string;
 /**
-* ListPages module types
+*
+* 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
@@ -385,7 +527,7 @@ interface ListPagesExternalData {
 * 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.
+* 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.)
@@ -527,47 +669,60 @@ interface NormalizedListPagesQuery {
 	reverse?: boolean;
 }
 /**
-* Callback to get current page's tags
+* Callback to retrieve the current page's tags during the resolve phase.
 *
-* Called during resolve phase to evaluate [[iftags]] conditions.
+* Called when evaluating `[[iftags]]` conditions. The application must provide
+* this callback with access to the current page's tag list.
 *
 * @returns Array of tag names for the current page
 */
 type IfTagsResolver = () => string[];
 /**
-* Data provider interface for resolving modules that require external data
+* Callback bag for supplying external data during module resolution.
 *
-* All callbacks are optional - if not provided, the corresponding
-* module/syntax will be output as-is in the AST without resolution.
+* Pass an instance to `resolveModules()`. Every callback is optional:
+* when a callback is missing the corresponding module node is kept as-is
+* in the output AST — useful when you only need to resolve a subset of
+* modules (e.g. only `[[iftags]]` on the client side).
 *
-* Note: Include resolution is handled separately via resolveIncludes().
+* @group Module Resolution
 */
 interface DataProvider {
 	/**
-	* Fetch data for ListPages module
-	* Called during resolve phase with query parameters
+	* Fetch page data for `[[module ListPages]]` expansion.
 	*
-	* @security `req.query` / `req.rawAttributes` are **untrusted user input** from wikitext.
-	* When building database queries:
-	* - **NEVER** interpolate them into SQL strings
-	* - **ALWAYS** use parameterized queries / prepared statements
-	* - For `order` (ORDER BY), use a whitelist of allowed column names
+	* Called once per ListPages instance in the AST with the normalised
+	* query parameters extracted from the module's wikitext attributes.
+	*
+	* @security The query fields originate from **untrusted user input**.
+	* When building database queries from the returned requirement:
+	* - **Never** interpolate `req.query` / `req.rawAttributes` into SQL
+	* - **Always** use parameterised queries or prepared statements
+	* - For `order` (ORDER BY), validate against a whitelist of column names
 	*/
 	fetchListPages?: ListPagesDataFetcher;
 	/**
-	* Fetch data for ListUsers module
-	* Called during resolve phase with user query parameters
+	* Fetch user data for `[[module ListUsers]]` expansion.
+	*
+	* Called once per ListUsers instance with the parsed query parameters.
 	*/
 	fetchListUsers?: ListUsersDataFetcher;
 	/**
-	* Get current page's tags for iftags evaluation
-	* Called during resolve phase to evaluate [[iftags]] conditions
+	* Return the current page's tags for `[[iftags]]` evaluation.
+	*
+	* If provided, `[[iftags]]` blocks are evaluated and either kept or
+	* discarded based on whether the page's tags satisfy the condition.
+	* If omitted, `[[iftags]]` blocks pass through unresolved.
 	*/
 	getPageTags?: IfTagsResolver;
 }
 import { SyntaxTree as SyntaxTree2 } from "@wdprlib/ast";
 /**
-* Result of extraction including compiled templates
+* Complete result of extracting data requirements from an AST.
+*
+* Contains everything needed to fetch external data and then resolve modules:
+* the data requirements tell the application what to fetch, and the pre-compiled
+* templates are used during the resolution phase to efficiently render results.
 */
 interface ExtractionResult {
 	/** Data requirements for external fetching */
@@ -578,11 +733,29 @@ interface ExtractionResult {
 	compiledListUsersTemplates: Map<number, ListUsersCompiledTemplate>;
 }
 /**
-* Extract data requirements from a parsed AST
+* Extract all data requirements from a parsed AST.
+*
+* Walks the entire AST to find ListPages and ListUsers module elements,
+* analyzes their templates to determine which variables are used, builds
+* query objects from their attributes, and pre-compiles their templates.
+*
+* Each module is assigned a sequential ID (separate counters for ListPages
+* and ListUsers) that is used to correlate requirements with fetched data
+* and compiled templates during the resolution phase.
+*
+* @param ast - The parsed syntax tree to analyze
+* @returns Extraction result containing requirements and compiled templates
 */
 declare function extractDataRequirements(ast: SyntaxTree2): ExtractionResult;
 /**
-* Compile a template string into an executable function
+* Compile a ListPages template string into an executable function.
+*
+* The template is split into alternating static strings and dynamic getter
+* functions. The returned function concatenates these parts with the getter
+* functions evaluated against the provided variable context.
+*
+* @param template - The template string containing `%%variable%%` placeholders
+* @returns A compiled function that accepts a `VariableContext` and returns the rendered string
 */
 declare function compileTemplate(template: string): CompiledTemplate;
 /**
@@ -694,49 +867,85 @@ interface ResolveIncludesOptions {
 */
 declare function resolveIncludes(source: string, fetcher: IncludeFetcher, options?: ResolveIncludesOptions): string;
 /**
-* Compile a template string into an executable function
+* Compile a ListUsers template string into an executable function.
+*
+* The template is split into alternating static strings and dynamic getter
+* functions. The returned function concatenates these parts for each call.
+*
+* @param template - The template string containing `%%variable%%` placeholders
+* @returns A compiled function that accepts a `ListUsersVariableContext` and returns rendered text
 */
 declare function compileListUsersTemplate(template: string): ListUsersCompiledTemplate;
 /**
-* Extract needed variables from a template string
+* Extract the set of template variables referenced in a ListUsers template string.
+*
+* Scans for `%%variable%%` patterns and returns only those that match known
+* ListUsers variables. Unknown variables are silently ignored.
+*
+* @param template - The template string from the module body
+* @returns Deduplicated array of referenced variable names
 */
 declare function extractListUsersVariables(template: string): ListUsersVariable[];
 import { Element as Element5, Module as Module3 } from "@wdprlib/ast";
 /**
-* ListUsers module data type
+* Narrowed type for the list-users variant of the Module discriminated union.
 */
 type ListUsersModuleData = Extract<Module3, {
 	module: "list-users";
 }>;
 /**
-* Type guard for list-users module
+* Type guard to check if a Module is a list-users module.
+*
+* @param module - A Module discriminated union value
+* @returns true if the module is a list-users module
 */
 declare function isListUsersModule(module: Module3): module is ListUsersModuleData;
 /**
-* Resolve a single ListUsers module
-* Note: ListUsers returns only the logged-in user
+* Resolve a single ListUsers module by substituting fetched user data into
+* the pre-compiled template and re-parsing the result as wikitext.
+*
+* Currently ListUsers only renders the logged-in user (no iteration over
+* multiple users), so the template is executed exactly once.
+*
+* @param _module - The list-users module data from the AST (unused, reserved for future use)
+* @param data - External user data fetched by the application
+* @param compiledTemplate - Pre-compiled template function from the extraction phase
+* @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[];
 import { SyntaxTree as SyntaxTree3 } from "@wdprlib/ast";
 /**
-* Options for resolving modules
+* Configuration for {@link resolveModules}.
+*
+* Callers must supply pre-extracted requirements and pre-compiled
+* templates (obtained from `extractDataRequirements()` and
+* `compileTemplate()` / `compileListUsersTemplate()`).
+*
+* @group Module Resolution
 */
 interface ResolveOptions {
-	/** Parser function for re-parsing templates */
+	/** Parser function used to re-parse expanded template markup into AST nodes */
 	parse: ParseFunction;
-	/** Pre-compiled templates for ListPages */
+	/** Pre-compiled ListPages body templates, keyed by requirement ID */
 	compiledListPagesTemplates: Map<number, CompiledTemplate>;
-	/** Pre-compiled templates for ListUsers */
+	/** Pre-compiled ListUsers body templates, keyed by requirement ID */
 	compiledListUsersTemplates?: Map<number, ListUsersCompiledTemplate>;
-	/** Data requirements grouped by module type */
+	/**
+	* Data requirements grouped by module type.
+	* Obtained from `extractDataRequirements()`.
+	*/
 	requirements: {
 		listPages?: ListPagesDataRequirement[];
 		listUsers?: ListUsersDataRequirement[];
 	};
 	/**
-	* URL path for @URL parameter resolution (HPC support)
-	* Format: "/page-name/param/value/param/value"
-	* Example: "/scp-001/offset/10/page2_limit/5"
+	* URL path for `@URL` parameter resolution (HPC / pagination support).
+	*
+	* Wikidot encodes pagination state in the URL path as key/value pairs
+	* after the page name, e.g. `"/scp-001/offset/10/page2_limit/5"`.
+	* When provided, `@URL` references in ListPages queries are replaced
+	* with the corresponding values from this path.
 	*/
 	urlPath?: string;
 }

package/dist/index.js

@@ -5949,10 +5949,8 @@ var newlineLineBreakRule = {
     }
     const nextMeaningfulToken = ctx.tokens[ctx.pos + lookAhead];
     let isValidBlock = isBlockStartToken(nextMeaningfulToken?.type);
-    if (isValidBlock && (nextMeaningfulToken?.type === "LIST_BULLET" || nextMeaningfulToken?.type === "LIST_NUMBER")) {
-      if (!nextMeaningfulToken.lineStart) {
-        isValidBlock = false;
-      }
+    if (isValidBlock && !nextMeaningfulToken?.lineStart) {
+      isValidBlock = false;
     }
     if (isValidBlock && nextMeaningfulToken?.type === "HEADING_MARKER") {
       const markerLen = nextMeaningfulToken.value.length;
@@ -7699,6 +7697,7 @@ var bibciteRule = {
       return { success: false };
     }
     let label = "";
+    let foundClose = false;
     while (pos < ctx.tokens.length) {
       const t = ctx.tokens[pos];
       if (!t)
@@ -7707,6 +7706,7 @@ var bibciteRule = {
         const nextT = ctx.tokens[pos + 1];
         if (nextT?.type === "TEXT" && nextT.value === ")") {
           consumed += 2;
+          foundClose = true;
           break;
         }
       }
@@ -7717,6 +7717,9 @@ var bibciteRule = {
       pos++;
       consumed++;
     }
+    if (!foundClose) {
+      return { success: false };
+    }
     label = label.trim();
     if (!label) {
       return { success: false };
@@ -9573,16 +9576,31 @@ function resolveIncludes(source, fetcher, options) {
   };
   return expandText(source, cachedFetcher, 0, maxDepth, []);
 }
-var INCLUDE_PATTERN = /\[\[include\s+([\s\S]*?)\]\]/gi;
+var INCLUDE_PATTERN = /\[\[include\s([^\]]*(?:\](?!\])[^\]]*)*)\]\]/gi;
 function parseIncludeDirective(inner) {
   const normalized = inner.replace(/\n/g, " ");
   const parts = normalized.split("|");
-  const target = parts[0].trim();
-  const variables = {};
+  const firstSegment = parts[0].trim();
+  const spaceIndex = firstSegment.indexOf(" ");
+  let target;
+  const varSegments = [];
+  if (spaceIndex !== -1) {
+    target = firstSegment.slice(0, spaceIndex);
+    const rest = firstSegment.slice(spaceIndex + 1).trim();
+    if (rest) {
+      varSegments.push(rest);
+    }
+  } else {
+    target = firstSegment;
+  }
   for (let i = 1;i < parts.length; i++) {
     const segment = parts[i].trim();
-    if (!segment)
-      continue;
+    if (segment) {
+      varSegments.push(segment);
+    }
+  }
+  const variables = {};
+  for (const segment of varSegments) {
     const eqIndex = segment.indexOf("=");
     if (eqIndex !== -1) {
       const key = segment.slice(0, eqIndex).trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdprlib/parser",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Parser for Wikidot markup",
   "keywords": [
     "ast",