@wdprlib/parser 5.4.0 → 6.0.0

package/dist/index.d.cts

@@ -4,6 +4,7 @@ declare const buildInfo: Readonly<{
 	sha: string | null;
 	dirty: boolean | null;
 }>;
+import { RatingRef as RatingRef3, RatingVote, RatingAggregate as RatingAggregate2, RatingState as RatingState3 } from "@wdprlib/ast";
 import { Position as Position2, Point, Version as Version2, Element as Element8, SyntaxTree as SyntaxTree5, ContainerType, ContainerData, AttributeMap, VariableMap, Alignment, LinkType, LinkLocation, LinkLabel, PageRef as PageRef7, ImageSource, FloatAlignment, ListType, ListItem, ListData, CodeBlockData as CodeBlockData2, TabData, TableCell, TableRow, TableData, DefinitionListItem, Module as Module5, CollapsibleData, ClearFloat, AnchorTarget, HeaderType, AlignType, HeadingLevel, Heading, DateItem, Embed, TocEntry as TocEntry2, GallerySize, GalleryOrder, GalleryItem, GalleryContent, GalleryData, Diagnostic as Diagnostic4, DiagnosticSeverity, ParseResult as ParseResult4 } 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 WikitextSettings5 } from "@wdprlib/ast";
@@ -236,7 +237,7 @@ declare class Parser {
 */
 declare function parse(source: string, options?: ParserOptions): ParseResult2;
 import { WikitextPageContext as WikitextPageContext2 } from "@wdprlib/ast";
-import { Diagnostic, PageRef as PageRef5, SyntaxTree, WikitextPageContext, WikitextSettings as WikitextSettings3 } from "@wdprlib/ast";
+import { Diagnostic, PageRef as PageRef5, SyntaxTree, WikitextPageContext, WikitextSettings as WikitextSettings3, RatingRef, RatingState, ReadableTextOptions } from "@wdprlib/ast";
 import { PageRef as PageRef4, WikitextSettings as WikitextSettings2 } from "@wdprlib/ast";
 interface IncludeAssignment {
 	key: string;
@@ -412,6 +413,8 @@ interface ListPagesQuery {
 	createdBy?: string;
 	/** Rating selector. @untrusted User input. */
 	rating?: string;
+	/** Exact registered custom key for rating/votes filters and order; omitted means main. */
+	ratingAxis?: string;
 	/** Votes selector. @untrusted User input. */
 	votes?: string;
 	/** Page name selector. @untrusted User input. */
@@ -436,7 +439,7 @@ interface ListPagesQuery {
 /**
 * 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 ListPagesVariable = "metadata" | "customrate" | "customrate_votes" | "customrate_percent" | "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" | "excerpt" | "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.
@@ -614,6 +617,12 @@ interface ListPagesDataRequirement {
 	previewLengths?: number[];
 	/** Field names needed for form_data{field} etc. */
 	formFields?: string[];
+	/** Exact metadata keys used by display templates. Also validate query.order on the host. */
+	metadataKeys?: string[];
+	/** Exact custom rating keys needed for display, independent of query.ratingAxis. */
+	customRateKeys?: string[];
+	/** Supply PageData.readableText and firstParagraph for previews, excerpts, and summaries. */
+	needsReadableText?: boolean;
 	/** Prefix for tags_linked|prefix */
 	tagsLinkPrefix?: string;
 	/** Prefix for _tags_linked|prefix */
@@ -637,6 +646,21 @@ interface DataRequirements {
 	listUsers: ListUsersDataRequirement[];
 	tagCloud: TagCloudDataRequirement[];
 }
+import { RatingAggregate } from "@wdprlib/ast";
+/** Values for host-registered metadata keys. Missing entries remain unavailable. */
+type PageMetadataValue = {
+	type: "text";
+	value: string;
+} | {
+	type: "number";
+	value: number;
+} | {
+	type: "date";
+	value: Date;
+} | {
+	type: "user";
+	value: UserInfo;
+};
 /**
 * User information.
 */
@@ -649,6 +673,18 @@ interface UserInfo {
 * Page data provided by an external source.
 */
 interface PageData {
+	/**
+	* `%%metadata{key}%%`: only registered, readable entries; keys are case-sensitive.
+	* Values are literal text. Date values accept strftime; user format is name, |id or |unix.
+	* Tag change date/editor may be host-defined keys; WDPR reserves no such keys.
+	*/
+	metadata?: Readonly<Record<string, PageMetadataValue | null>>;
+	/**
+	* `%%customrate{key}%%`, `%%customrate_votes{key}%%`, `%%customrate_percent{key}%%`.
+	* Supply readable aggregates for requirement.customRateKeys, just as formFields selects
+	* form data. Missing keys expand to empty text; a supplied zero remains zero.
+	*/
+	customRates?: Readonly<Record<string, RatingAggregate | null>>;
 	name: string;
 	category: string;
 	fullname: string;
@@ -664,6 +700,19 @@ interface PageData {
 	parentFullname?: string;
 	parentTitle?: string;
 	content?: string;
+	/**
+	* Text extracted from this page's resolved AST for preview and
+	* `%%excerpt{pattern="..." group="1" match="2" max="200"}%%`.
+	* Values stay literal; raw content is never a fallback.
+	* The host owns extraction policy, dependency invalidation and recursion limits.
+	*/
+	readableText?: string;
+	/**
+	* First nonempty paragraph from extractFirstParagraph, for summary and first_paragraph.
+	* Uses the same extraction policy as readableText. Empty when no readable paragraph
+	* exists; undefined when unavailable. Headings and appended footnotes are excluded.
+	*/
+	firstParagraph?: string;
 	tags: string[];
 	hiddenTags: string[];
 	formData?: Record<string, string>;
@@ -672,7 +721,8 @@ interface PageData {
 	formHint?: Record<string, string>;
 	children: number;
 	comments: number;
-	size: number;
+	/** Materialized readable character count, computed with countCharacters. */
+	size?: number;
 	rating: number;
 	ratingVotes: number;
 	ratingPercent?: number;
@@ -738,18 +788,25 @@ interface NormalizedCategory {
 /**
 * Order field options.
 */
-type OrderField = "created_at" | "updated_at" | "title" | "fullname" | "rating" | "votes" | "revisions" | "comments" | "size" | "random";
+type OrderField = "created_at" | "updated_at" | "commented_at" | "metadata" | "title" | "fullname" | "rating" | "votes" | "revisions" | "comments" | "size" | "random";
 /**
 * Order direction.
 */
 type OrderDirection = "asc" | "desc";
 /**
 * Normalized order specification.
+* Providers validate metadata registration, readability and sortability without falling back
+* to another field. Sort before pagination with a stable page ID tie-breaker. For commented_at,
+* put pages without comments last and use the same visible, non-deleted comments as the count.
 */
-interface NormalizedOrder {
-	field: OrderField;
+type NormalizedOrder = {
+	field: Exclude<OrderField, "metadata">;
 	direction: OrderDirection;
-}
+} | {
+	field: "metadata";
+	key: string;
+	direction: OrderDirection;
+};
 /**
 * Normalized parent selector.
 */
@@ -815,6 +872,12 @@ interface NormalizedListPagesQuery {
 	updatedAt?: NormalizedDateSelector;
 	createdBy?: string;
 	rating?: NormalizedNumericSelector;
+	/**
+	* `rating-axis` selects the custom aggregate for rating/votes filters and order; omission
+	* selects main. Verify registration and read access before filtering, counting or sorting.
+	* Unknown keys must not fall back to main. Display variables select their own keys.
+	*/
+	ratingAxis?: string;
 	votes?: NormalizedNumericSelector;
 	name?: string;
 	fullname?: string;
@@ -853,6 +916,14 @@ interface ProcessWikitextCallbackContext<TPage extends WikitextPageContext> {
 	settings: WikitextSettings3;
 }
 interface ProcessWikitextDataProvider<TPage extends WikitextPageContext> {
+	/**
+	* Read only authorized, registered ratings in context.page, including declarations
+	* from its includes. Keys match exactly. Omit no-rate and inaccessible references.
+	* Main category policy and custom policies are independent. Votes belong to page + ref.
+	* ListPages/ListUsers output cannot declare ratings, including its nested includes.
+	* The host owns registration, aggregation and invalidation when included declarations change.
+	*/
+	fetchRatings?: (refs: readonly RatingRef[], context: ProcessWikitextCallbackContext<TPage>) => Promise<readonly RatingState[]>;
 	fetchInclude?: (pageRef: PageRef5, context: ProcessWikitextCallbackContext<TPage>) => Promise<string | null>;
 	fetchListPages?: (query: NormalizedListPagesQuery, requirement: ListPagesDataRequirement, context: ProcessWikitextCallbackContext<TPage>) => Promise<ListPagesExternalData | null | undefined>;
 	fetchListUsers?: (requirement: ListUsersDataRequirement, context: ProcessWikitextCallbackContext<TPage>) => Promise<ListUsersExternalData | null | undefined>;
@@ -863,9 +934,14 @@ interface ProcessWikitextOptions<TPage extends WikitextPageContext> {
 	settings?: WikitextSettings3;
 	dataProvider?: ProcessWikitextDataProvider<TPage>;
 	includeMaxIterations?: number;
+	readableText?: ReadableTextOptions;
 }
 interface ProcessedWikitextDocument<TPage extends WikitextPageContext = WikitextPageContext> {
 	ast: SyntaxTree;
+	readableText: string;
+	/** First nonempty body paragraph, excluding headings and appended footnotes. */
+	firstParagraph: string;
+	characterCount: number;
 	page: TPage;
 	settings: WikitextSettings3;
 	diagnostics: Diagnostic[];
@@ -885,6 +961,13 @@ import { ParseResult as ParseResult3, SyntaxTree as SyntaxTree2 } from "@wdprlib
 */
 type ModuleParseResult = SyntaxTree2 | ParseResult3;
 type ParseFunction = (input: string) => ModuleParseResult;
+import { RatingRef as RatingRef2, RatingState as RatingState2 } from "@wdprlib/ast";
+/**
+* Read authorized ratings for the displayed page. Omit unknown, disabled, or
+* inaccessible references. The host owns registration, category policies,
+* access checks, aggregates, and persistence; rendering must never create data.
+*/
+type RatingsFetcher = (refs: readonly RatingRef2[]) => Promise<readonly RatingState2[]>;
 /**
 * Callback to retrieve the current page's tags during the resolve phase.
 *
@@ -905,6 +988,8 @@ type IfTagsResolver = () => string[];
 * @group Module Resolution
 */
 interface DataProvider {
+	/** Read registered ratings for the displayed page; omitted references stay hidden. */
+	fetchRatings?: RatingsFetcher;
 	/**
 	* Fetch page data for `[[module ListPages]]` expansion.
 	*
@@ -1217,4 +1302,4 @@ interface ResolveOptions {
 */
 declare function resolveModules(ast: SyntaxTree4, dataProvider: DataProvider, options: ResolveOptions): Promise<SyntaxTree4>;
 import { STYLE_SLOT_PREFIX } from "@wdprlib/ast";
-export { tokenize, text, resolveTagCloud, resolveModules, resolveListUsers, resolveIncludesWithTrace, resolveIncludesAsyncWithTrace, resolveIncludesAsync, resolveIncludes, processWikitext, preprocessIftags, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, matchesListPagesSelectors, listItemSubList, listItemElements, list, link, lineBreak, italics, isTagCloudModule, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractIncludeReferences, extractDataRequirements, definePageData, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, buildInfo, bold, WikitextSettings5 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TagCloudTagData, TagCloudModuleData, TagCloudExternalData, TagCloudDataRequirement, TagCloudDataFetcher, TableRow, TableData, TableCell, TabData, SyntaxTree5 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesTraceResult, ResolveIncludesOptions, ProcessedWikitextDocument, ProcessWikitextOptions, ProcessWikitextDataProvider, ProcessWikitextCallbackContext, Position2 as Position, Point, ParserOptions, Parser, ParseResult4 as ParseResult, ParseFunction, PageRef7 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, ModuleSourceTransform, ModuleParseResult, Module5 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, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FloatAlignment, ExtractionResult, Embed, Element8 as Element, DiagnosticSeverity, Diagnostic4 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };
+export { tokenize, text, resolveTagCloud, resolveModules, resolveListUsers, resolveIncludesWithTrace, resolveIncludesAsyncWithTrace, resolveIncludesAsync, resolveIncludes, processWikitext, preprocessIftags, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, matchesListPagesSelectors, listItemSubList, listItemElements, list, link, lineBreak, italics, isTagCloudModule, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractIncludeReferences, extractDataRequirements, definePageData, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, buildInfo, bold, WikitextSettings5 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TagCloudTagData, TagCloudModuleData, TagCloudExternalData, TagCloudDataRequirement, TagCloudDataFetcher, TableRow, TableData, TableCell, TabData, SyntaxTree5 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesTraceResult, ResolveIncludesOptions, RatingsFetcher, RatingVote, RatingState3 as RatingState, RatingRef3 as RatingRef, RatingAggregate2 as RatingAggregate, ProcessedWikitextDocument, ProcessWikitextOptions, ProcessWikitextDataProvider, ProcessWikitextCallbackContext, Position2 as Position, Point, ParserOptions, Parser, ParseResult4 as ParseResult, ParseFunction, PageRef7 as PageRef, PageMetadataValue, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, ModuleSourceTransform, ModuleParseResult, Module5 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, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FloatAlignment, ExtractionResult, Embed, Element8 as Element, DiagnosticSeverity, Diagnostic4 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ declare const buildInfo: Readonly<{
 	sha: string | null;
 	dirty: boolean | null;
 }>;
+import { RatingRef as RatingRef3, RatingVote, RatingAggregate as RatingAggregate2, RatingState as RatingState3 } from "@wdprlib/ast";
 import { Position as Position2, Point, Version as Version2, Element as Element8, SyntaxTree as SyntaxTree5, ContainerType, ContainerData, AttributeMap, VariableMap, Alignment, LinkType, LinkLocation, LinkLabel, PageRef as PageRef7, ImageSource, FloatAlignment, ListType, ListItem, ListData, CodeBlockData as CodeBlockData2, TabData, TableCell, TableRow, TableData, DefinitionListItem, Module as Module5, CollapsibleData, ClearFloat, AnchorTarget, HeaderType, AlignType, HeadingLevel, Heading, DateItem, Embed, TocEntry as TocEntry2, GallerySize, GalleryOrder, GalleryItem, GalleryContent, GalleryData, Diagnostic as Diagnostic4, DiagnosticSeverity, ParseResult as ParseResult4 } 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 WikitextSettings5 } from "@wdprlib/ast";
@@ -236,7 +237,7 @@ declare class Parser {
 */
 declare function parse(source: string, options?: ParserOptions): ParseResult2;
 import { WikitextPageContext as WikitextPageContext2 } from "@wdprlib/ast";
-import { Diagnostic, PageRef as PageRef5, SyntaxTree, WikitextPageContext, WikitextSettings as WikitextSettings3 } from "@wdprlib/ast";
+import { Diagnostic, PageRef as PageRef5, SyntaxTree, WikitextPageContext, WikitextSettings as WikitextSettings3, RatingRef, RatingState, ReadableTextOptions } from "@wdprlib/ast";
 import { PageRef as PageRef4, WikitextSettings as WikitextSettings2 } from "@wdprlib/ast";
 interface IncludeAssignment {
 	key: string;
@@ -412,6 +413,8 @@ interface ListPagesQuery {
 	createdBy?: string;
 	/** Rating selector. @untrusted User input. */
 	rating?: string;
+	/** Exact registered custom key for rating/votes filters and order; omitted means main. */
+	ratingAxis?: string;
 	/** Votes selector. @untrusted User input. */
 	votes?: string;
 	/** Page name selector. @untrusted User input. */
@@ -436,7 +439,7 @@ interface ListPagesQuery {
 /**
 * 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 ListPagesVariable = "metadata" | "customrate" | "customrate_votes" | "customrate_percent" | "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" | "excerpt" | "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.
@@ -614,6 +617,12 @@ interface ListPagesDataRequirement {
 	previewLengths?: number[];
 	/** Field names needed for form_data{field} etc. */
 	formFields?: string[];
+	/** Exact metadata keys used by display templates. Also validate query.order on the host. */
+	metadataKeys?: string[];
+	/** Exact custom rating keys needed for display, independent of query.ratingAxis. */
+	customRateKeys?: string[];
+	/** Supply PageData.readableText and firstParagraph for previews, excerpts, and summaries. */
+	needsReadableText?: boolean;
 	/** Prefix for tags_linked|prefix */
 	tagsLinkPrefix?: string;
 	/** Prefix for _tags_linked|prefix */
@@ -637,6 +646,21 @@ interface DataRequirements {
 	listUsers: ListUsersDataRequirement[];
 	tagCloud: TagCloudDataRequirement[];
 }
+import { RatingAggregate } from "@wdprlib/ast";
+/** Values for host-registered metadata keys. Missing entries remain unavailable. */
+type PageMetadataValue = {
+	type: "text";
+	value: string;
+} | {
+	type: "number";
+	value: number;
+} | {
+	type: "date";
+	value: Date;
+} | {
+	type: "user";
+	value: UserInfo;
+};
 /**
 * User information.
 */
@@ -649,6 +673,18 @@ interface UserInfo {
 * Page data provided by an external source.
 */
 interface PageData {
+	/**
+	* `%%metadata{key}%%`: only registered, readable entries; keys are case-sensitive.
+	* Values are literal text. Date values accept strftime; user format is name, |id or |unix.
+	* Tag change date/editor may be host-defined keys; WDPR reserves no such keys.
+	*/
+	metadata?: Readonly<Record<string, PageMetadataValue | null>>;
+	/**
+	* `%%customrate{key}%%`, `%%customrate_votes{key}%%`, `%%customrate_percent{key}%%`.
+	* Supply readable aggregates for requirement.customRateKeys, just as formFields selects
+	* form data. Missing keys expand to empty text; a supplied zero remains zero.
+	*/
+	customRates?: Readonly<Record<string, RatingAggregate | null>>;
 	name: string;
 	category: string;
 	fullname: string;
@@ -664,6 +700,19 @@ interface PageData {
 	parentFullname?: string;
 	parentTitle?: string;
 	content?: string;
+	/**
+	* Text extracted from this page's resolved AST for preview and
+	* `%%excerpt{pattern="..." group="1" match="2" max="200"}%%`.
+	* Values stay literal; raw content is never a fallback.
+	* The host owns extraction policy, dependency invalidation and recursion limits.
+	*/
+	readableText?: string;
+	/**
+	* First nonempty paragraph from extractFirstParagraph, for summary and first_paragraph.
+	* Uses the same extraction policy as readableText. Empty when no readable paragraph
+	* exists; undefined when unavailable. Headings and appended footnotes are excluded.
+	*/
+	firstParagraph?: string;
 	tags: string[];
 	hiddenTags: string[];
 	formData?: Record<string, string>;
@@ -672,7 +721,8 @@ interface PageData {
 	formHint?: Record<string, string>;
 	children: number;
 	comments: number;
-	size: number;
+	/** Materialized readable character count, computed with countCharacters. */
+	size?: number;
 	rating: number;
 	ratingVotes: number;
 	ratingPercent?: number;
@@ -738,18 +788,25 @@ interface NormalizedCategory {
 /**
 * Order field options.
 */
-type OrderField = "created_at" | "updated_at" | "title" | "fullname" | "rating" | "votes" | "revisions" | "comments" | "size" | "random";
+type OrderField = "created_at" | "updated_at" | "commented_at" | "metadata" | "title" | "fullname" | "rating" | "votes" | "revisions" | "comments" | "size" | "random";
 /**
 * Order direction.
 */
 type OrderDirection = "asc" | "desc";
 /**
 * Normalized order specification.
+* Providers validate metadata registration, readability and sortability without falling back
+* to another field. Sort before pagination with a stable page ID tie-breaker. For commented_at,
+* put pages without comments last and use the same visible, non-deleted comments as the count.
 */
-interface NormalizedOrder {
-	field: OrderField;
+type NormalizedOrder = {
+	field: Exclude<OrderField, "metadata">;
 	direction: OrderDirection;
-}
+} | {
+	field: "metadata";
+	key: string;
+	direction: OrderDirection;
+};
 /**
 * Normalized parent selector.
 */
@@ -815,6 +872,12 @@ interface NormalizedListPagesQuery {
 	updatedAt?: NormalizedDateSelector;
 	createdBy?: string;
 	rating?: NormalizedNumericSelector;
+	/**
+	* `rating-axis` selects the custom aggregate for rating/votes filters and order; omission
+	* selects main. Verify registration and read access before filtering, counting or sorting.
+	* Unknown keys must not fall back to main. Display variables select their own keys.
+	*/
+	ratingAxis?: string;
 	votes?: NormalizedNumericSelector;
 	name?: string;
 	fullname?: string;
@@ -853,6 +916,14 @@ interface ProcessWikitextCallbackContext<TPage extends WikitextPageContext> {
 	settings: WikitextSettings3;
 }
 interface ProcessWikitextDataProvider<TPage extends WikitextPageContext> {
+	/**
+	* Read only authorized, registered ratings in context.page, including declarations
+	* from its includes. Keys match exactly. Omit no-rate and inaccessible references.
+	* Main category policy and custom policies are independent. Votes belong to page + ref.
+	* ListPages/ListUsers output cannot declare ratings, including its nested includes.
+	* The host owns registration, aggregation and invalidation when included declarations change.
+	*/
+	fetchRatings?: (refs: readonly RatingRef[], context: ProcessWikitextCallbackContext<TPage>) => Promise<readonly RatingState[]>;
 	fetchInclude?: (pageRef: PageRef5, context: ProcessWikitextCallbackContext<TPage>) => Promise<string | null>;
 	fetchListPages?: (query: NormalizedListPagesQuery, requirement: ListPagesDataRequirement, context: ProcessWikitextCallbackContext<TPage>) => Promise<ListPagesExternalData | null | undefined>;
 	fetchListUsers?: (requirement: ListUsersDataRequirement, context: ProcessWikitextCallbackContext<TPage>) => Promise<ListUsersExternalData | null | undefined>;
@@ -863,9 +934,14 @@ interface ProcessWikitextOptions<TPage extends WikitextPageContext> {
 	settings?: WikitextSettings3;
 	dataProvider?: ProcessWikitextDataProvider<TPage>;
 	includeMaxIterations?: number;
+	readableText?: ReadableTextOptions;
 }
 interface ProcessedWikitextDocument<TPage extends WikitextPageContext = WikitextPageContext> {
 	ast: SyntaxTree;
+	readableText: string;
+	/** First nonempty body paragraph, excluding headings and appended footnotes. */
+	firstParagraph: string;
+	characterCount: number;
 	page: TPage;
 	settings: WikitextSettings3;
 	diagnostics: Diagnostic[];
@@ -885,6 +961,13 @@ import { ParseResult as ParseResult3, SyntaxTree as SyntaxTree2 } from "@wdprlib
 */
 type ModuleParseResult = SyntaxTree2 | ParseResult3;
 type ParseFunction = (input: string) => ModuleParseResult;
+import { RatingRef as RatingRef2, RatingState as RatingState2 } from "@wdprlib/ast";
+/**
+* Read authorized ratings for the displayed page. Omit unknown, disabled, or
+* inaccessible references. The host owns registration, category policies,
+* access checks, aggregates, and persistence; rendering must never create data.
+*/
+type RatingsFetcher = (refs: readonly RatingRef2[]) => Promise<readonly RatingState2[]>;
 /**
 * Callback to retrieve the current page's tags during the resolve phase.
 *
@@ -905,6 +988,8 @@ type IfTagsResolver = () => string[];
 * @group Module Resolution
 */
 interface DataProvider {
+	/** Read registered ratings for the displayed page; omitted references stay hidden. */
+	fetchRatings?: RatingsFetcher;
 	/**
 	* Fetch page data for `[[module ListPages]]` expansion.
 	*
@@ -1217,4 +1302,4 @@ interface ResolveOptions {
 */
 declare function resolveModules(ast: SyntaxTree4, dataProvider: DataProvider, options: ResolveOptions): Promise<SyntaxTree4>;
 import { STYLE_SLOT_PREFIX } from "@wdprlib/ast";
-export { tokenize, text, resolveTagCloud, resolveModules, resolveListUsers, resolveIncludesWithTrace, resolveIncludesAsyncWithTrace, resolveIncludesAsync, resolveIncludes, processWikitext, preprocessIftags, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, matchesListPagesSelectors, listItemSubList, listItemElements, list, link, lineBreak, italics, isTagCloudModule, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractIncludeReferences, extractDataRequirements, definePageData, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, buildInfo, bold, WikitextSettings5 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TagCloudTagData, TagCloudModuleData, TagCloudExternalData, TagCloudDataRequirement, TagCloudDataFetcher, TableRow, TableData, TableCell, TabData, SyntaxTree5 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesTraceResult, ResolveIncludesOptions, ProcessedWikitextDocument, ProcessWikitextOptions, ProcessWikitextDataProvider, ProcessWikitextCallbackContext, Position2 as Position, Point, ParserOptions, Parser, ParseResult4 as ParseResult, ParseFunction, PageRef7 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, ModuleSourceTransform, ModuleParseResult, Module5 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, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FloatAlignment, ExtractionResult, Embed, Element8 as Element, DiagnosticSeverity, Diagnostic4 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };
+export { tokenize, text, resolveTagCloud, resolveModules, resolveListUsers, resolveIncludesWithTrace, resolveIncludesAsyncWithTrace, resolveIncludesAsync, resolveIncludes, processWikitext, preprocessIftags, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, matchesListPagesSelectors, listItemSubList, listItemElements, list, link, lineBreak, italics, isTagCloudModule, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractIncludeReferences, extractDataRequirements, definePageData, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, buildInfo, bold, WikitextSettings5 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TagCloudTagData, TagCloudModuleData, TagCloudExternalData, TagCloudDataRequirement, TagCloudDataFetcher, TableRow, TableData, TableCell, TabData, SyntaxTree5 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesTraceResult, ResolveIncludesOptions, RatingsFetcher, RatingVote, RatingState3 as RatingState, RatingRef3 as RatingRef, RatingAggregate2 as RatingAggregate, ProcessedWikitextDocument, ProcessWikitextOptions, ProcessWikitextDataProvider, ProcessWikitextCallbackContext, Position2 as Position, Point, ParserOptions, Parser, ParseResult4 as ParseResult, ParseFunction, PageRef7 as PageRef, PageMetadataValue, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, ModuleSourceTransform, ModuleParseResult, Module5 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, GallerySize, GalleryOrder, GalleryItem, GalleryData, GalleryContent, FloatAlignment, ExtractionResult, Embed, Element8 as Element, DiagnosticSeverity, Diagnostic4 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };