@wdprlib/parser 5.2.0 → 5.3.0

package/dist/index.cjs

@@ -82,8 +82,8 @@ module.exports = __toCommonJS(exports_src);
 
 // packages/parser/src/build-info.generated.ts
 var buildInfo = Object.freeze({
-  version: "5.2.0",
-  sha: "cc290b0d882de3ed9ea33ec060ddfc8a7b9da59a",
+  version: "5.3.0",
+  sha: "b71b84c705e05717f5ea12fd89684a91b669dbff",
   dirty: false
 });
 
@@ -6253,9 +6253,9 @@ function renderListPagesItems(module2, data, compiledTemplate, parse) {
       continue;
     const ctx = {
       page,
-      index: i + 1,
+      index: (data.pagination?.offset ?? 0) + i + 1,
       total: data.totalCount,
-      limit: module2.limit,
+      limit: data.pagination ? data.pagination.limit : module2.limit,
       site: data.site
     };
     const itemAst = getModuleParseAst(parse(compiledTemplate(ctx)));
@@ -6275,9 +6275,46 @@ function renderListPagesItems(module2, data, compiledTemplate, parse) {
   return items;
 }
 
+// packages/parser/src/parser/rules/block/module/listpages/resolution/pager.ts
+function createListPagesPager(data) {
+  const pagination = data.pagination;
+  if (!pagination || pagination.totalPages <= 1)
+    return [];
+  const { currentPage, totalPages, urlPath, parameter } = pagination;
+  const pages = new Set([1, totalPages]);
+  for (let page = Math.max(1, currentPage - 2);page <= Math.min(totalPages, currentPage + 2); page++) {
+    pages.add(page);
+  }
+  return [
+    {
+      element: "pager",
+      data: {
+        currentPage,
+        totalPages,
+        pages: [...pages].sort((a, b) => a - b).map((page) => ({
+          page,
+          href: pageUrl(urlPath, parameter, page)
+        }))
+      }
+    }
+  ];
+}
+function pageUrl(urlPath, parameter, page) {
+  const suffixStart = urlPath.search(/[?#]/);
+  const path = suffixStart === -1 ? urlPath : urlPath.slice(0, suffixStart);
+  const suffix = suffixStart === -1 ? "" : urlPath.slice(suffixStart);
+  const parts = path.split("/");
+  const result = parts.slice(0, 2);
+  for (let index = 2;index < parts.length; index += 2) {
+    if (parts[index] !== parameter)
+      result.push(...parts.slice(index, index + 2));
+  }
+  return `${result.join("/").replace(/\/$/, "")}/${parameter}/${page}${suffix}`;
+}
+
 // packages/parser/src/parser/rules/block/module/listpages/resolution/wrapper.ts
-function wrapListPagesResult(module2, items, parse) {
-  if (items.length === 0) {
+function wrapListPagesResult(module2, items, parse, data) {
+  if (items.length === 0 && (!data || data.pages.length === 0)) {
     return [];
   }
   const result = [];
@@ -6290,6 +6327,8 @@ function wrapListPagesResult(module2, items, parse) {
     const appendAst = getModuleParseAst(parse(module2["append-line"]));
     result.push(...appendAst.elements);
   }
+  if (data)
+    result.push(...createListPagesPager(data));
   if (module2.wrapper) {
     return [
       {
@@ -6311,7 +6350,7 @@ function isListPagesModule2(module2) {
 }
 function resolveListPages(module2, data, compiledTemplate, parse) {
   const items = renderListPagesItems(module2, data, compiledTemplate, parse);
-  return wrapListPagesResult(module2, items, parse);
+  return wrapListPagesResult(module2, items, parse, data);
 }
 // packages/parser/src/parser/rules/block/module/listpages/types/external-data.ts
 function definePageData(input) {
@@ -6408,10 +6447,10 @@ var URL_RESOLVABLE_FIELDS = [
 ];
 
 // packages/parser/src/parser/rules/block/module/listpages/url-resolution/params.ts
-function parseUrlParams(url) {
+function parseUrlParams(url, hasPageName = false) {
   const params = new Map;
-  const parts = url.split("/").filter(Boolean);
-  const pairStart = isUrlParameter(parts[0]) ? 0 : 1;
+  const parts = url.split(/[?#]/, 1)[0].split("/").filter(Boolean);
+  const pairStart = !hasPageName && isUrlParameter(parts[0]) ? 0 : 1;
   for (let i = pairStart;i < parts.length - 1; i += 2) {
     const key = parts[i];
     const value = parts[i + 1];
@@ -7509,18 +7548,66 @@ function resolveListUsers(_module, data, compiledTemplate, parse) {
   return itemAst.elements;
 }
 // packages/parser/src/parser/rules/block/module/resolution/data-maps.ts
-async function buildListPagesDataMap(dataProvider, requirements, urlPath) {
+async function buildListPagesDataMap(dataProvider, requirements, urlPath, paginationState = { nextUnprefixed: 1 }) {
   const dataMap = new Map;
-  const urlParams = parseUrlParams(urlPath ?? "");
+  const urlParams = parseUrlParams(urlPath ?? "", true);
   for (const req of requirements) {
     const normalizedQuery = resolveAndNormalizeQuery(req, urlParams);
-    const data = await dataProvider.fetchListPages?.(normalizedQuery, req);
+    if (!urlPath || !urlPath.startsWith("/") || urlPath.startsWith("//")) {
+      const data2 = await dataProvider.fetchListPages?.(normalizedQuery, req);
+      if (data2)
+        dataMap.set(req.id, data2);
+      continue;
+    }
+    const ordinal = req.urlAttrPrefix ? 0 : paginationState.nextUnprefixed++;
+    const parameter = req.urlAttrPrefix ? `${encodeURIComponent(req.urlAttrPrefix)}_p` : ordinal === 1 ? "p" : `p${ordinal}`;
+    const perPage = Math.min(250, positiveInteger(normalizedQuery.perPage, 20));
+    const baseOffset = positiveInteger(normalizedQuery.offset, 0);
+    const limit = normalizedQuery.limit !== undefined && normalizedQuery.limit >= 0 ? Math.floor(normalizedQuery.limit) : undefined;
+    const rawPage = urlParams.get(parameter) ?? "1";
+    let currentPage = /^\d+$/.test(rawPage) ? positiveInteger(Number(rawPage), 1) : 1;
+    currentPage = Math.min(currentPage, Math.floor((Number.MAX_SAFE_INTEGER - baseOffset) / perPage) + 1);
+    if (limit !== undefined)
+      currentPage = Math.min(currentPage, Math.max(1, Math.ceil(limit / perPage)));
+    const fetchPage = () => {
+      const relativeOffset = (currentPage - 1) * perPage;
+      return dataProvider.fetchListPages?.({
+        ...normalizedQuery,
+        offset: baseOffset + relativeOffset,
+        limit: Math.min(perPage, limit === undefined ? perPage : Math.max(0, limit - relativeOffset)),
+        perPage
+      }, req);
+    };
+    let data = await fetchPage();
     if (data) {
-      dataMap.set(req.id, data);
+      const count = Math.min(Math.max(0, data.totalCount - baseOffset), limit ?? Infinity);
+      const totalPages = Math.ceil(count / perPage);
+      const lastPage = Math.max(1, totalPages);
+      if (currentPage > lastPage) {
+        currentPage = lastPage;
+        data = await fetchPage();
+      }
+      if (data)
+        dataMap.set(req.id, {
+          ...data,
+          pages: data.pages.slice(0, Math.min(perPage, Math.max(0, count - (currentPage - 1) * perPage))),
+          pagination: {
+            currentPage,
+            perPage,
+            totalPages,
+            offset: baseOffset + (currentPage - 1) * perPage,
+            limit,
+            urlPath,
+            parameter
+          }
+        });
     }
   }
   return dataMap;
 }
+function positiveInteger(value, fallback) {
+  return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
 async function buildListUsersDataMap(dataProvider, requirements) {
   const dataMap = new Map;
   for (const req of requirements) {
@@ -14388,7 +14475,7 @@ async function resolveModulesWithAsyncParse(ast, dataProvider, options) {
   registry.register(ast);
   const parse2 = async (source) => registry.register(await options.parse(source));
   const [listPagesData, listUsersData, tagCloudData] = await Promise.all([
-    buildListPagesDataMap(dataProvider, options.requirements.listPages ?? [], options.urlPath),
+    buildListPagesDataMap(dataProvider, options.requirements.listPages ?? [], options.urlPath, options.paginationState),
     buildListUsersDataMap(dataProvider, options.requirements.listUsers ?? []),
     buildTagCloudDataMap(dataProvider, options.requirements.tagCloud ?? [])
   ]);
@@ -14476,9 +14563,9 @@ async function resolveListPagesAsync(module2, data, template, parse2) {
       continue;
     const variableContext = {
       page,
-      index: i + 1,
+      index: (data.pagination?.offset ?? 0) + i + 1,
       total: data.totalCount,
-      limit: module2.limit,
+      limit: data.pagination ? data.pagination.limit : module2.limit,
       site: data.site
     };
     const parsed = await parse2(template(variableContext));
@@ -14498,6 +14585,7 @@ async function resolveListPagesAsync(module2, data, template, parse2) {
   if (module2["append-line"] && !module2.separate) {
     result.push(...(await parse2(module2["append-line"])).elements);
   }
+  result.push(...createListPagesPager(data));
   return module2.wrapper ? [
     {
       element: "container",
@@ -14598,6 +14686,9 @@ async function processWikitext(source, options) {
   const dataProvider = createModuleDataProvider(options, callbackContext);
   const parseFragment = parseSource2;
   let ast = initial.ast;
+  const paginationState = { nextUnprefixed: 1 };
+  const requestedPath = options.page.urlPath;
+  const urlPath = !requestedPath || /^\/(?:[?#]|$)/.test(requestedPath) ? `/${options.page.fullName}${requestedPath?.slice(1) ?? ""}` : requestedPath;
   for (let pass = 0;pass < DEFAULT_MODULE_MAX_PASSES; pass++) {
     const extraction = extractDataRequirements(ast);
     if (pass > 0 && !hasResolvableRequirements(extraction.requirements, options.dataProvider)) {
@@ -14608,7 +14699,8 @@ async function processWikitext(source, options) {
       compiledListPagesTemplates: extraction.compiledListPagesTemplates,
       compiledListUsersTemplates: extraction.compiledListUsersTemplates,
       requirements: extraction.requirements,
-      urlPath: options.page.urlPath,
+      urlPath,
+      paginationState,
       pageTags: options.page.tags
     });
     ast = resolved.ast;

package/dist/index.d.cts

@@ -691,8 +691,21 @@ interface SiteContext {
 */
 interface ListPagesExternalData {
 	pages: PageData[];
+	/** Matching items before offset and limit; use the same visibility filters as pages. */
 	totalCount: number;
 	site: SiteContext;
+	/** Filled by module resolution when a page URL is available. */
+	pagination?: {
+		currentPage: number;
+		perPage: number;
+		totalPages: number;
+		/** Actual fetch offset, including the module's starting offset. */
+		offset: number;
+		/** Total item limit after URL resolution, not the fetch batch size. */
+		limit?: number;
+		urlPath: string;
+		parameter: string;
+	};
 }
 /**
 * Normalized tags selector.

package/dist/index.d.ts

@@ -691,8 +691,21 @@ interface SiteContext {
 */
 interface ListPagesExternalData {
 	pages: PageData[];
+	/** Matching items before offset and limit; use the same visibility filters as pages. */
 	totalCount: number;
 	site: SiteContext;
+	/** Filled by module resolution when a page URL is available. */
+	pagination?: {
+		currentPage: number;
+		perPage: number;
+		totalPages: number;
+		/** Actual fetch offset, including the module's starting offset. */
+		offset: number;
+		/** Total item limit after URL resolution, not the fetch batch size. */
+		limit?: number;
+		urlPath: string;
+		parameter: string;
+	};
 }
 /**
 * Normalized tags selector.

package/dist/index.js

@@ -1,7 +1,7 @@
 // packages/parser/src/build-info.generated.ts
 var buildInfo = Object.freeze({
-  version: "5.2.0",
-  sha: "cc290b0d882de3ed9ea33ec060ddfc8a7b9da59a",
+  version: "5.3.0",
+  sha: "b71b84c705e05717f5ea12fd89684a91b669dbff",
   dirty: false
 });
 
@@ -6186,9 +6186,9 @@ function renderListPagesItems(module, data, compiledTemplate, parse) {
       continue;
     const ctx = {
       page,
-      index: i + 1,
+      index: (data.pagination?.offset ?? 0) + i + 1,
       total: data.totalCount,
-      limit: module.limit,
+      limit: data.pagination ? data.pagination.limit : module.limit,
       site: data.site
     };
     const itemAst = getModuleParseAst(parse(compiledTemplate(ctx)));
@@ -6208,9 +6208,46 @@ function renderListPagesItems(module, data, compiledTemplate, parse) {
   return items;
 }
 
+// packages/parser/src/parser/rules/block/module/listpages/resolution/pager.ts
+function createListPagesPager(data) {
+  const pagination = data.pagination;
+  if (!pagination || pagination.totalPages <= 1)
+    return [];
+  const { currentPage, totalPages, urlPath, parameter } = pagination;
+  const pages = new Set([1, totalPages]);
+  for (let page = Math.max(1, currentPage - 2);page <= Math.min(totalPages, currentPage + 2); page++) {
+    pages.add(page);
+  }
+  return [
+    {
+      element: "pager",
+      data: {
+        currentPage,
+        totalPages,
+        pages: [...pages].sort((a, b) => a - b).map((page) => ({
+          page,
+          href: pageUrl(urlPath, parameter, page)
+        }))
+      }
+    }
+  ];
+}
+function pageUrl(urlPath, parameter, page) {
+  const suffixStart = urlPath.search(/[?#]/);
+  const path = suffixStart === -1 ? urlPath : urlPath.slice(0, suffixStart);
+  const suffix = suffixStart === -1 ? "" : urlPath.slice(suffixStart);
+  const parts = path.split("/");
+  const result = parts.slice(0, 2);
+  for (let index = 2;index < parts.length; index += 2) {
+    if (parts[index] !== parameter)
+      result.push(...parts.slice(index, index + 2));
+  }
+  return `${result.join("/").replace(/\/$/, "")}/${parameter}/${page}${suffix}`;
+}
+
 // packages/parser/src/parser/rules/block/module/listpages/resolution/wrapper.ts
-function wrapListPagesResult(module, items, parse) {
-  if (items.length === 0) {
+function wrapListPagesResult(module, items, parse, data) {
+  if (items.length === 0 && (!data || data.pages.length === 0)) {
     return [];
   }
   const result = [];
@@ -6223,6 +6260,8 @@ function wrapListPagesResult(module, items, parse) {
     const appendAst = getModuleParseAst(parse(module["append-line"]));
     result.push(...appendAst.elements);
   }
+  if (data)
+    result.push(...createListPagesPager(data));
   if (module.wrapper) {
     return [
       {
@@ -6244,7 +6283,7 @@ function isListPagesModule2(module) {
 }
 function resolveListPages(module, data, compiledTemplate, parse) {
   const items = renderListPagesItems(module, data, compiledTemplate, parse);
-  return wrapListPagesResult(module, items, parse);
+  return wrapListPagesResult(module, items, parse, data);
 }
 // packages/parser/src/parser/rules/block/module/listpages/types/external-data.ts
 function definePageData(input) {
@@ -6341,10 +6380,10 @@ var URL_RESOLVABLE_FIELDS = [
 ];
 
 // packages/parser/src/parser/rules/block/module/listpages/url-resolution/params.ts
-function parseUrlParams(url) {
+function parseUrlParams(url, hasPageName = false) {
   const params = new Map;
-  const parts = url.split("/").filter(Boolean);
-  const pairStart = isUrlParameter(parts[0]) ? 0 : 1;
+  const parts = url.split(/[?#]/, 1)[0].split("/").filter(Boolean);
+  const pairStart = !hasPageName && isUrlParameter(parts[0]) ? 0 : 1;
   for (let i = pairStart;i < parts.length - 1; i += 2) {
     const key = parts[i];
     const value = parts[i + 1];
@@ -7442,18 +7481,66 @@ function resolveListUsers(_module, data, compiledTemplate, parse) {
   return itemAst.elements;
 }
 // packages/parser/src/parser/rules/block/module/resolution/data-maps.ts
-async function buildListPagesDataMap(dataProvider, requirements, urlPath) {
+async function buildListPagesDataMap(dataProvider, requirements, urlPath, paginationState = { nextUnprefixed: 1 }) {
   const dataMap = new Map;
-  const urlParams = parseUrlParams(urlPath ?? "");
+  const urlParams = parseUrlParams(urlPath ?? "", true);
   for (const req of requirements) {
     const normalizedQuery = resolveAndNormalizeQuery(req, urlParams);
-    const data = await dataProvider.fetchListPages?.(normalizedQuery, req);
+    if (!urlPath || !urlPath.startsWith("/") || urlPath.startsWith("//")) {
+      const data2 = await dataProvider.fetchListPages?.(normalizedQuery, req);
+      if (data2)
+        dataMap.set(req.id, data2);
+      continue;
+    }
+    const ordinal = req.urlAttrPrefix ? 0 : paginationState.nextUnprefixed++;
+    const parameter = req.urlAttrPrefix ? `${encodeURIComponent(req.urlAttrPrefix)}_p` : ordinal === 1 ? "p" : `p${ordinal}`;
+    const perPage = Math.min(250, positiveInteger(normalizedQuery.perPage, 20));
+    const baseOffset = positiveInteger(normalizedQuery.offset, 0);
+    const limit = normalizedQuery.limit !== undefined && normalizedQuery.limit >= 0 ? Math.floor(normalizedQuery.limit) : undefined;
+    const rawPage = urlParams.get(parameter) ?? "1";
+    let currentPage = /^\d+$/.test(rawPage) ? positiveInteger(Number(rawPage), 1) : 1;
+    currentPage = Math.min(currentPage, Math.floor((Number.MAX_SAFE_INTEGER - baseOffset) / perPage) + 1);
+    if (limit !== undefined)
+      currentPage = Math.min(currentPage, Math.max(1, Math.ceil(limit / perPage)));
+    const fetchPage = () => {
+      const relativeOffset = (currentPage - 1) * perPage;
+      return dataProvider.fetchListPages?.({
+        ...normalizedQuery,
+        offset: baseOffset + relativeOffset,
+        limit: Math.min(perPage, limit === undefined ? perPage : Math.max(0, limit - relativeOffset)),
+        perPage
+      }, req);
+    };
+    let data = await fetchPage();
     if (data) {
-      dataMap.set(req.id, data);
+      const count = Math.min(Math.max(0, data.totalCount - baseOffset), limit ?? Infinity);
+      const totalPages = Math.ceil(count / perPage);
+      const lastPage = Math.max(1, totalPages);
+      if (currentPage > lastPage) {
+        currentPage = lastPage;
+        data = await fetchPage();
+      }
+      if (data)
+        dataMap.set(req.id, {
+          ...data,
+          pages: data.pages.slice(0, Math.min(perPage, Math.max(0, count - (currentPage - 1) * perPage))),
+          pagination: {
+            currentPage,
+            perPage,
+            totalPages,
+            offset: baseOffset + (currentPage - 1) * perPage,
+            limit,
+            urlPath,
+            parameter
+          }
+        });
     }
   }
   return dataMap;
 }
+function positiveInteger(value, fallback) {
+  return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
 async function buildListUsersDataMap(dataProvider, requirements) {
   const dataMap = new Map;
   for (const req of requirements) {
@@ -14326,7 +14413,7 @@ async function resolveModulesWithAsyncParse(ast, dataProvider, options) {
   registry.register(ast);
   const parse2 = async (source) => registry.register(await options.parse(source));
   const [listPagesData, listUsersData, tagCloudData] = await Promise.all([
-    buildListPagesDataMap(dataProvider, options.requirements.listPages ?? [], options.urlPath),
+    buildListPagesDataMap(dataProvider, options.requirements.listPages ?? [], options.urlPath, options.paginationState),
     buildListUsersDataMap(dataProvider, options.requirements.listUsers ?? []),
     buildTagCloudDataMap(dataProvider, options.requirements.tagCloud ?? [])
   ]);
@@ -14414,9 +14501,9 @@ async function resolveListPagesAsync(module, data, template, parse2) {
       continue;
     const variableContext = {
       page,
-      index: i + 1,
+      index: (data.pagination?.offset ?? 0) + i + 1,
       total: data.totalCount,
-      limit: module.limit,
+      limit: data.pagination ? data.pagination.limit : module.limit,
       site: data.site
     };
     const parsed = await parse2(template(variableContext));
@@ -14436,6 +14523,7 @@ async function resolveListPagesAsync(module, data, template, parse2) {
   if (module["append-line"] && !module.separate) {
     result.push(...(await parse2(module["append-line"])).elements);
   }
+  result.push(...createListPagesPager(data));
   return module.wrapper ? [
     {
       element: "container",
@@ -14536,6 +14624,9 @@ async function processWikitext(source, options) {
   const dataProvider = createModuleDataProvider(options, callbackContext);
   const parseFragment = parseSource2;
   let ast = initial.ast;
+  const paginationState = { nextUnprefixed: 1 };
+  const requestedPath = options.page.urlPath;
+  const urlPath = !requestedPath || /^\/(?:[?#]|$)/.test(requestedPath) ? `/${options.page.fullName}${requestedPath?.slice(1) ?? ""}` : requestedPath;
   for (let pass = 0;pass < DEFAULT_MODULE_MAX_PASSES; pass++) {
     const extraction = extractDataRequirements(ast);
     if (pass > 0 && !hasResolvableRequirements(extraction.requirements, options.dataProvider)) {
@@ -14546,7 +14637,8 @@ async function processWikitext(source, options) {
       compiledListPagesTemplates: extraction.compiledListPagesTemplates,
       compiledListUsersTemplates: extraction.compiledListUsersTemplates,
       requirements: extraction.requirements,
-      urlPath: options.page.urlPath,
+      urlPath,
+      paginationState,
       pageTags: options.page.tags
     });
     ast = resolved.ast;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdprlib/parser",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Parser for Wikidot markup",
   "keywords": [
     "ast",
@@ -44,6 +44,6 @@
   },
   "dependencies": {
     "@braintree/sanitize-url": "^7.1.1",
-    "@wdprlib/ast": "4.1.0"
+    "@wdprlib/ast": "4.2.0"
   }
 }

package/src/build-info.generated.ts

@@ -5,7 +5,7 @@ export const buildInfo: Readonly<{
   sha: string | null;
   dirty: boolean | null;
 }> = Object.freeze({
-  version: "5.2.0",
-  sha: "cc290b0d882de3ed9ea33ec060ddfc8a7b9da59a",
+  version: "5.3.0",
+  sha: "b71b84c705e05717f5ea12fd89684a91b669dbff",
   dirty: false,
 });

package/src/parser/rules/block/module/listpages/resolution/items.ts

@@ -17,9 +17,9 @@ export function renderListPagesItems(
 
     const ctx: VariableContext = {
       page,
-      index: i + 1,
+      index: (data.pagination?.offset ?? 0) + i + 1,
       total: data.totalCount,
-      limit: module.limit,
+      limit: data.pagination ? data.pagination.limit : module.limit,
       site: data.site,
     };
 

package/src/parser/rules/block/module/listpages/resolution/pager.ts

@@ -0,0 +1,43 @@
+import type { Element } from "@wdprlib/ast";
+import type { ListPagesExternalData } from "../types";
+
+export function createListPagesPager(data: ListPagesExternalData): Element[] {
+  const pagination = data.pagination;
+  if (!pagination || pagination.totalPages <= 1) return [];
+  const { currentPage, totalPages, urlPath, parameter } = pagination;
+  const pages = new Set([1, totalPages]);
+  for (
+    let page = Math.max(1, currentPage - 2);
+    page <= Math.min(totalPages, currentPage + 2);
+    page++
+  ) {
+    pages.add(page);
+  }
+  return [
+    {
+      element: "pager",
+      data: {
+        currentPage,
+        totalPages,
+        pages: [...pages]
+          .sort((a, b) => a - b)
+          .map((page) => ({
+            page,
+            href: pageUrl(urlPath, parameter, page),
+          })),
+      },
+    },
+  ];
+}
+
+function pageUrl(urlPath: string, parameter: string, page: number): string {
+  const suffixStart = urlPath.search(/[?#]/);
+  const path = suffixStart === -1 ? urlPath : urlPath.slice(0, suffixStart);
+  const suffix = suffixStart === -1 ? "" : urlPath.slice(suffixStart);
+  const parts = path.split("/");
+  const result = parts.slice(0, 2);
+  for (let index = 2; index < parts.length; index += 2) {
+    if (parts[index] !== parameter) result.push(...parts.slice(index, index + 2));
+  }
+  return `${result.join("/").replace(/\/$/, "")}/${parameter}/${page}${suffix}`;
+}

package/src/parser/rules/block/module/listpages/resolution/wrapper.ts

@@ -1,13 +1,16 @@
 import type { Element } from "@wdprlib/ast";
 import { getModuleParseAst, type ParseFunction } from "../../types";
 import type { ListPagesModuleData } from "../resolve";
+import type { ListPagesExternalData } from "../types";
+import { createListPagesPager } from "./pager";
 
 export function wrapListPagesResult(
   module: ListPagesModuleData,
   items: Element[],
   parse: ParseFunction,
+  data?: ListPagesExternalData,
 ): Element[] {
-  if (items.length === 0) {
+  if (items.length === 0 && (!data || data.pages.length === 0)) {
     return [];
   }
 
@@ -25,6 +28,8 @@ export function wrapListPagesResult(
     result.push(...appendAst.elements);
   }
 
+  if (data) result.push(...createListPagesPager(data));
+
   if (module.wrapper) {
     return [
       {

package/src/parser/rules/block/module/listpages/resolve.ts

@@ -56,5 +56,5 @@ export function resolveListPages(
   parse: ParseFunction,
 ): Element[] {
   const items = renderListPagesItems(module, data, compiledTemplate, parse);
-  return wrapListPagesResult(module, items, parse);
+  return wrapListPagesResult(module, items, parse, data);
 }

package/src/parser/rules/block/module/listpages/types/external-data.ts

@@ -94,6 +94,19 @@ export interface SiteContext {
  */
 export interface ListPagesExternalData {
   pages: PageData[];
+  /** Matching items before offset and limit; use the same visibility filters as pages. */
   totalCount: number;
   site: SiteContext;
+  /** Filled by module resolution when a page URL is available. */
+  pagination?: {
+    currentPage: number;
+    perPage: number;
+    totalPages: number;
+    /** Actual fetch offset, including the module's starting offset. */
+    offset: number;
+    /** Total item limit after URL resolution, not the fetch batch size. */
+    limit?: number;
+    urlPath: string;
+    parameter: string;
+  };
 }

package/src/parser/rules/block/module/listpages/url-resolution/params.ts

@@ -2,12 +2,13 @@ import { URL_RESOLVABLE_FIELDS } from "./fields";
 
 /**
  * Parse URL path parameters like /offset/1/page2_limit/1.
- * Returns a map of parameter name -> value.
+ * Returns a map of parameter name -> value. Set hasPageName for a full page path;
+ * otherwise the legacy parameter-only-path heuristic is used.
  */
-export function parseUrlParams(url: string): Map<string, string> {
+export function parseUrlParams(url: string, hasPageName = false): Map<string, string> {
   const params = new Map<string, string>();
-  const parts = url.split("/").filter(Boolean);
-  const pairStart = isUrlParameter(parts[0]) ? 0 : 1;
+  const parts = url.split(/[?#]/, 1)[0]!.split("/").filter(Boolean);
+  const pairStart = !hasPageName && isUrlParameter(parts[0]) ? 0 : 1;
 
   // Skip the page name (first part), parse key/value pairs.
   for (let i = pairStart; i < parts.length - 1; i += 2) {

package/src/parser/rules/block/module/resolution/data-maps.ts

@@ -4,25 +4,97 @@ import type { ListUsersDataRequirement, ListUsersExternalData } from "../listuse
 import type { TagCloudDataRequirement, TagCloudExternalData } from "../tagcloud/types";
 import { parseUrlParams, resolveAndNormalizeQuery } from "../listpages/url-resolver";
 
+export interface ListPagesPaginationState {
+  nextUnprefixed: number;
+}
+
 export async function buildListPagesDataMap(
   dataProvider: DataProvider,
   requirements: ListPagesDataRequirement[],
   urlPath: string | undefined,
+  paginationState: ListPagesPaginationState = { nextUnprefixed: 1 },
 ): Promise<Map<number, ListPagesExternalData>> {
   const dataMap = new Map<number, ListPagesExternalData>();
-  const urlParams = parseUrlParams(urlPath ?? "");
+  const urlParams = parseUrlParams(urlPath ?? "", true);
 
   for (const req of requirements) {
     const normalizedQuery = resolveAndNormalizeQuery(req, urlParams);
-    const data = await dataProvider.fetchListPages?.(normalizedQuery, req);
+    if (!urlPath || !urlPath.startsWith("/") || urlPath.startsWith("//")) {
+      const data = await dataProvider.fetchListPages?.(normalizedQuery, req);
+      if (data) dataMap.set(req.id, data);
+      continue;
+    }
+    const ordinal = req.urlAttrPrefix ? 0 : paginationState.nextUnprefixed++;
+    const parameter = req.urlAttrPrefix
+      ? `${encodeURIComponent(req.urlAttrPrefix)}_p`
+      : ordinal === 1
+        ? "p"
+        : `p${ordinal}`;
+    const perPage = Math.min(250, positiveInteger(normalizedQuery.perPage, 20));
+    const baseOffset = positiveInteger(normalizedQuery.offset, 0);
+    const limit =
+      normalizedQuery.limit !== undefined && normalizedQuery.limit >= 0
+        ? Math.floor(normalizedQuery.limit)
+        : undefined;
+    const rawPage = urlParams.get(parameter) ?? "1";
+    let currentPage = /^\d+$/.test(rawPage) ? positiveInteger(Number(rawPage), 1) : 1;
+    currentPage = Math.min(
+      currentPage,
+      Math.floor((Number.MAX_SAFE_INTEGER - baseOffset) / perPage) + 1,
+    );
+    if (limit !== undefined)
+      currentPage = Math.min(currentPage, Math.max(1, Math.ceil(limit / perPage)));
+    const fetchPage = () => {
+      const relativeOffset = (currentPage - 1) * perPage;
+      return dataProvider.fetchListPages?.(
+        {
+          ...normalizedQuery,
+          offset: baseOffset + relativeOffset,
+          limit: Math.min(
+            perPage,
+            limit === undefined ? perPage : Math.max(0, limit - relativeOffset),
+          ),
+          perPage,
+        },
+        req,
+      );
+    };
+    let data = await fetchPage();
     if (data) {
-      dataMap.set(req.id, data);
+      const count = Math.min(Math.max(0, data.totalCount - baseOffset), limit ?? Infinity);
+      const totalPages = Math.ceil(count / perPage);
+      const lastPage = Math.max(1, totalPages);
+      if (currentPage > lastPage) {
+        currentPage = lastPage;
+        data = await fetchPage();
+      }
+      if (data)
+        dataMap.set(req.id, {
+          ...data,
+          pages: data.pages.slice(
+            0,
+            Math.min(perPage, Math.max(0, count - (currentPage - 1) * perPage)),
+          ),
+          pagination: {
+            currentPage,
+            perPage,
+            totalPages,
+            offset: baseOffset + (currentPage - 1) * perPage,
+            limit,
+            urlPath,
+            parameter,
+          },
+        });
     }
   }
 
   return dataMap;
 }
 
+function positiveInteger(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
 export async function buildListUsersDataMap(
   dataProvider: DataProvider,
   requirements: ListUsersDataRequirement[],

package/src/parser/rules/block/module/resolution/resolve-async.ts

@@ -26,6 +26,8 @@ import {
 import { buildListPagesDataMap, buildListUsersDataMap, buildTagCloudDataMap } from "./data-maps";
 import { ModuleDocumentRegistry } from "./document";
 import { collectStyles, mergeCollectedStyles } from "./styles";
+import { createListPagesPager } from "../listpages/resolution/pager";
+import type { ListPagesPaginationState } from "./data-maps";
 
 export type AsyncModuleParseFunction = (source: string) => Promise<ModuleParseResult>;
 
@@ -40,6 +42,7 @@ export interface ResolveModulesWithAsyncParseOptions {
   };
   urlPath?: string;
   pageTags: string[];
+  paginationState?: ListPagesPaginationState;
 }
 
 export interface AsyncModuleResolutionResult {
@@ -73,7 +76,12 @@ export async function resolveModulesWithAsyncParse(
     registry.register(await options.parse(source));
 
   const [listPagesData, listUsersData, tagCloudData] = await Promise.all([
-    buildListPagesDataMap(dataProvider, options.requirements.listPages ?? [], options.urlPath),
+    buildListPagesDataMap(
+      dataProvider,
+      options.requirements.listPages ?? [],
+      options.urlPath,
+      options.paginationState,
+    ),
     buildListUsersDataMap(dataProvider, options.requirements.listUsers ?? []),
     buildTagCloudDataMap(dataProvider, options.requirements.tagCloud ?? []),
   ]);
@@ -175,9 +183,9 @@ async function resolveListPagesAsync(
     if (!page) continue;
     const variableContext: VariableContext = {
       page,
-      index: i + 1,
+      index: (data.pagination?.offset ?? 0) + i + 1,
       total: data.totalCount,
-      limit: module.limit,
+      limit: data.pagination ? data.pagination.limit : module.limit,
       site: data.site,
     };
     const parsed = await parse(template(variableContext));
@@ -197,6 +205,7 @@ async function resolveListPagesAsync(
   if (module["append-line"] && !module.separate) {
     result.push(...(await parse(module["append-line"])).elements);
   }
+  result.push(...createListPagesPager(data));
 
   return module.wrapper
     ? [

package/src/pipeline/process.ts

@@ -82,6 +82,12 @@ export async function processWikitext<TPage extends WikitextPageContext>(
   const dataProvider = createModuleDataProvider(options, callbackContext);
   const parseFragment = parseSource;
   let ast = initial.ast;
+  const paginationState = { nextUnprefixed: 1 };
+  const requestedPath = options.page.urlPath;
+  const urlPath =
+    !requestedPath || /^\/(?:[?#]|$)/.test(requestedPath)
+      ? `/${options.page.fullName}${requestedPath?.slice(1) ?? ""}`
+      : requestedPath;
 
   for (let pass = 0; pass < DEFAULT_MODULE_MAX_PASSES; pass++) {
     const extraction = extractDataRequirements(ast);
@@ -94,7 +100,8 @@ export async function processWikitext<TPage extends WikitextPageContext>(
       compiledListPagesTemplates: extraction.compiledListPagesTemplates,
       compiledListUsersTemplates: extraction.compiledListUsersTemplates,
       requirements: extraction.requirements,
-      urlPath: options.page.urlPath,
+      urlPath,
+      paginationState,
       pageTags: options.page.tags,
     });
     ast = resolved.ast;