@caelo-cms/shared 0.11.3 → 0.11.4

package/dist/lists/pagination.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Paginated page lists (#1257, `docs/lists.md` §6 "Pagination"). An
+ * overview page (a guides hub, a category landing page) lists every page
+ * a query matches: its paginated `list` field shows `per_page` entries,
+ * page 1 at the page's own URL and every further page at
+ * `<page path>/page/<n>/`. The static generator and the editor preview
+ * emit those follow-up pages; the module draws its own pager from the
+ * `pagination` system source.
+ *
+ * Decisions (maintainer, #1257):
+ *
+ * - Follow-up URLs are path segments, not `?page=n`: a static host serves
+ *   files, and a query string would serve page 1 for every page.
+ *   `/page/1/` is never emitted — page 1 has exactly one URL.
+ * - Follow-up pages are indexable and self-canonical by default (Google:
+ *   do not canonicalise page 2… to page 1); `follow_ups: "noindex"` keeps
+ *   them out of search (robots noindex, no sitemap entry) per overview.
+ * - Page size defaults to the maximum ({@link LIST_QUERY_MAX_LIMIT}):
+ *   static HTML costs nothing per entry, and fewer follow-up pages mean
+ *   fewer thin pages.
+ * - One paginated list per page: two would need two independent page
+ *   numbers in one URL.
+ */
+import { z } from "zod";
+import type { PageUrlStyle } from "../seo.js";
+/** The URL segment in front of the page number: `/guides/page/2/`. */
+export declare const PAGINATION_SEGMENT = "page";
+/** Who may see follow-up pages in search. */
+export declare const PAGINATION_FOLLOW_UPS: readonly ["index", "noindex"];
+export type PaginationFollowUps = (typeof PAGINATION_FOLLOW_UPS)[number];
+/**
+ * Pagination settings — on a module `list` field (`paginate`, opts the
+ * field in and sets the defaults) and in a placement's value
+ * (`paginate`, overrides them for that overview).
+ */
+export declare const listPaginationSchema: z.ZodObject<{
+    per_page: z.ZodOptional<z.ZodNumber>;
+    follow_ups: z.ZodOptional<z.ZodEnum<{
+        index: "index";
+        noindex: "noindex";
+    }>>;
+}, z.core.$strict>;
+export type ListPaginationSettings = z.infer<typeof listPaginationSchema>;
+/** The settings an overview renders with. */
+export interface EffectivePagination {
+    readonly perPage: number;
+    readonly followUps: PaginationFollowUps;
+}
+/**
+ * The placement value of a paginated field split into its pagination
+ * overrides and the rest (query knobs / `terms`). The rest is what the
+ * source reads; `paginate` never reaches the query parser.
+ */
+export declare function splitPaginationValue(value: unknown): {
+    readonly paginate: unknown;
+    readonly rest: unknown;
+};
+/**
+ * Field settings with the placement's overrides applied; null when the
+ * overrides are malformed (the render reports `list-malformed`).
+ */
+export declare function effectivePagination(field: ListPaginationSettings, overrides: unknown): EffectivePagination | null;
+/** How many pages `total` entries need at `perPage` (at least one). */
+export declare function pageCountOf(total: number, perPage: number): number;
+/**
+ * The public path of page `n` (≥ 2) of the overview at `path`:
+ * `/guides` → `/guides/page/2`, `/` → `/page/2`. No trailing slash: the
+ * target's URL style adds it (`pageHrefForStyle`, `pageOutputPath`).
+ */
+export declare function pagedPath(path: string, n: number): string;
+/**
+ * The URL of page `n` (≥ 2) from the overview's own URL (absolute or a
+ * path, as the link resolver or the public URL builder made it) in the
+ * target's URL style. Query and fragment are dropped: they belong to
+ * page 1's link, not to the page sequence.
+ */
+export declare function pagedUrl(url: string, n: number, style: PageUrlStyle): string;
+/**
+ * Split a requested path into the overview's path and a follow-up page
+ * number: `/guides/page/3/` → `{ basePath: "/guides", page: 3 }`. Null
+ * when the path names no follow-up page (`/page/1` included — page 1 is
+ * only served at the overview's own path).
+ */
+export declare function parsePagedPath(path: string): {
+    basePath: string;
+    page: number;
+} | null;
+/**
+ * The page path a follow-up page of `overviewPath` would collide with:
+ * `pagePath` is `<overview>/page` or below it. A page there would either
+ * shadow a follow-up page or, in the no-extension URL style, need a file
+ * and a directory of the same name.
+ */
+export declare function collidesWithFollowUps(overviewPath: string, pagePath: string): boolean;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/lists/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/lists/pagination.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAI9C,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,+BAAgC,CAAC;AACnE,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;kBAOtB,CAAC;AACZ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAE1E,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB,CAMA;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,sBAAsB,EAC7B,SAAS,EAAE,OAAO,GACjB,mBAAmB,GAAG,IAAI,CAO5B;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAQ5E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOtF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIrF"}

package/dist/lists/pagination.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Paginated page lists (#1257, `docs/lists.md` §6 "Pagination"). An
+ * overview page (a guides hub, a category landing page) lists every page
+ * a query matches: its paginated `list` field shows `per_page` entries,
+ * page 1 at the page's own URL and every further page at
+ * `<page path>/page/<n>/`. The static generator and the editor preview
+ * emit those follow-up pages; the module draws its own pager from the
+ * `pagination` system source.
+ *
+ * Decisions (maintainer, #1257):
+ *
+ * - Follow-up URLs are path segments, not `?page=n`: a static host serves
+ *   files, and a query string would serve page 1 for every page.
+ *   `/page/1/` is never emitted — page 1 has exactly one URL.
+ * - Follow-up pages are indexable and self-canonical by default (Google:
+ *   do not canonicalise page 2… to page 1); `follow_ups: "noindex"` keeps
+ *   them out of search (robots noindex, no sitemap entry) per overview.
+ * - Page size defaults to the maximum ({@link LIST_QUERY_MAX_LIMIT}):
+ *   static HTML costs nothing per entry, and fewer follow-up pages mean
+ *   fewer thin pages.
+ * - One paginated list per page: two would need two independent page
+ *   numbers in one URL.
+ */
+import { z } from "zod";
+import { trimSlashes } from "../url.js";
+import { LIST_QUERY_MAX_LIMIT } from "./list-type.js";
+/** The URL segment in front of the page number: `/guides/page/2/`. */
+export const PAGINATION_SEGMENT = "page";
+/** Who may see follow-up pages in search. */
+export const PAGINATION_FOLLOW_UPS = ["index", "noindex"];
+/**
+ * Pagination settings — on a module `list` field (`paginate`, opts the
+ * field in and sets the defaults) and in a placement's value
+ * (`paginate`, overrides them for that overview).
+ */
+export const listPaginationSchema = z
+    .object({
+    /** Entries per page, 1..50; default 50. */
+    per_page: z.number().int().min(1).max(LIST_QUERY_MAX_LIMIT).optional(),
+    /** Follow-up pages indexable (default) or `noindex` and out of the sitemap. */
+    follow_ups: z.enum(PAGINATION_FOLLOW_UPS).optional(),
+})
+    .strict();
+/**
+ * The placement value of a paginated field split into its pagination
+ * overrides and the rest (query knobs / `terms`). The rest is what the
+ * source reads; `paginate` never reaches the query parser.
+ */
+export function splitPaginationValue(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return { paginate: undefined, rest: value };
+    }
+    const { paginate, ...rest } = value;
+    return { paginate, rest: Object.keys(rest).length > 0 ? rest : undefined };
+}
+/**
+ * Field settings with the placement's overrides applied; null when the
+ * overrides are malformed (the render reports `list-malformed`).
+ */
+export function effectivePagination(field, overrides) {
+    const parsed = listPaginationSchema.safeParse(overrides ?? {});
+    if (!parsed.success)
+        return null;
+    return {
+        perPage: parsed.data.per_page ?? field.per_page ?? LIST_QUERY_MAX_LIMIT,
+        followUps: parsed.data.follow_ups ?? field.follow_ups ?? "index",
+    };
+}
+/** How many pages `total` entries need at `perPage` (at least one). */
+export function pageCountOf(total, perPage) {
+    return Math.max(1, Math.ceil(total / perPage));
+}
+/**
+ * The public path of page `n` (≥ 2) of the overview at `path`:
+ * `/guides` → `/guides/page/2`, `/` → `/page/2`. No trailing slash: the
+ * target's URL style adds it (`pageHrefForStyle`, `pageOutputPath`).
+ */
+export function pagedPath(path, n) {
+    assertFollowUp(n);
+    const trimmed = trimSlashes(path);
+    return `${trimmed.length > 0 ? `/${trimmed}` : ""}/${PAGINATION_SEGMENT}/${n}`;
+}
+/**
+ * The URL of page `n` (≥ 2) from the overview's own URL (absolute or a
+ * path, as the link resolver or the public URL builder made it) in the
+ * target's URL style. Query and fragment are dropped: they belong to
+ * page 1's link, not to the page sequence.
+ */
+export function pagedUrl(url, n, style) {
+    assertFollowUp(n);
+    // Trailing slashes cut by index, not a regex: no backtracking on input.
+    let base = url.split(/[?#]/, 1)[0] ?? url;
+    let end = base.length;
+    while (end > 0 && base.charCodeAt(end - 1) === 47)
+        end -= 1;
+    base = base.slice(0, end);
+    return `${base}/${PAGINATION_SEGMENT}/${n}${style === "directory" ? "/" : ""}`;
+}
+/**
+ * Split a requested path into the overview's path and a follow-up page
+ * number: `/guides/page/3/` → `{ basePath: "/guides", page: 3 }`. Null
+ * when the path names no follow-up page (`/page/1` included — page 1 is
+ * only served at the overview's own path).
+ */
+export function parsePagedPath(path) {
+    const m = /^(.*?)\/page\/([1-9][0-9]{0,5})\/?$/.exec(path);
+    if (!m)
+        return null;
+    const page = Number(m[2]);
+    if (page < 2)
+        return null;
+    const base = trimSlashes(m[1] ?? "");
+    return { basePath: base.length === 0 ? "/" : `/${base}`, page };
+}
+/**
+ * The page path a follow-up page of `overviewPath` would collide with:
+ * `pagePath` is `<overview>/page` or below it. A page there would either
+ * shadow a follow-up page or, in the no-extension URL style, need a file
+ * and a directory of the same name.
+ */
+export function collidesWithFollowUps(overviewPath, pagePath) {
+    const prefix = pagedPrefix(overviewPath);
+    const p = `/${trimSlashes(pagePath)}`;
+    return p === prefix || p.startsWith(`${prefix}/`);
+}
+function pagedPrefix(path) {
+    const trimmed = trimSlashes(path);
+    return `${trimmed.length > 0 ? `/${trimmed}` : ""}/${PAGINATION_SEGMENT}`;
+}
+function assertFollowUp(n) {
+    if (!Number.isInteger(n) || n < 2) {
+        throw new Error(`pagination: follow-up page numbers start at 2 (got ${n}).`);
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/lists/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/lists/pagination.ts"],"names":[],"mappings":"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"}

package/dist/lists/resolve.d.ts

@@ -20,7 +20,9 @@
  * raw.
  */
 import type { LinkResolver } from "../link-refs.js";
+import type { PageUrlStyle } from "../seo.js";
 import { type SourceDef } from "./list-type.js";
+import { type ListPaginationSettings, type PaginationFollowUps } from "./pagination.js";
 import type { ListRenderData, ListRenderDeps, PluginSourceEntry } from "./render-data.js";
 import type { ScopeEntry, ScopeValue } from "./scope.js";
 /** True for a list failure marker — the editor's missing-content surface shows these. */
@@ -33,6 +35,8 @@ export interface ListFieldSpec {
     readonly list?: string;
     readonly source?: SourceDef;
     readonly default?: unknown;
+    /** #1257 — the field lists every match across follow-up pages. */
+    readonly paginate?: ListPaginationSettings;
 }
 /** Result of resolving one list field for one page. */
 export type ListFieldResolution = {
@@ -63,7 +67,64 @@ export interface ListPageOptions {
     readonly linkResolver?: LinkResolver;
     /** Entries of every ACTIVE plugin list source for this page, keyed by source name. */
     readonly pluginSources?: Readonly<Record<string, readonly PluginSourceEntry[]>>;
+    /**
+     * #1257 — the target's URL style, for the pager's links to follow-up
+     * pages. Without it a rendered `pagination` source is
+     * `list-context-unavailable:pagination`.
+     */
+    readonly pageUrlStyle?: PageUrlStyle;
+    /**
+     * #1257 — which page of the paginated list this render is (1 = the
+     * page's own URL; default 1), and — once a first render found it —
+     * how many pages there are, so a pager rendered BEFORE the list knows.
+     */
+    readonly pagination?: {
+        readonly page: number;
+        readonly pageCount?: number;
+    };
+}
+/**
+ * #1257 — the page's paginated list as one render saw it
+ * ({@link ListPageContext.pagination}).
+ */
+export interface ListPaginationState {
+    /** The paginated module field. */
+    readonly field: string;
+    readonly perPage: number;
+    /** Every match of the query. */
+    readonly total: number;
+    readonly pageCount: number;
+    /** The page this render showed. */
+    readonly page: number;
+    readonly followUps: PaginationFollowUps;
+    /** A `pagination` source rendered on this page. */
+    readonly pagerShown: boolean;
+    /**
+     * The pager rendered before the list was resolved, so it did not know
+     * the page count yet: render the page again with
+     * `pagination: { page, pageCount }`.
+     */
+    readonly pagerEarly: boolean;
 }
+/**
+ * #1257 — a list cut at its limit: more pages match than it shows. Never
+ * silent: the Stage result and `preview_list_source` report it.
+ */
+export interface TruncatedList {
+    /** The module field (or source node's field) that rendered the list. */
+    readonly field: string;
+    readonly shown: number;
+    readonly total: number;
+    /** The limit that cut it (the query's `limit`; 50 for term_pages). */
+    readonly limit: number;
+}
+/**
+ * The markers a finished render's pagination asks for: a paginated page
+ * that shows no pager strands every entry after the first page
+ * (`list-pager-missing:<field>`). Exported so the preview and the
+ * generator apply one rule.
+ */
+export declare function paginationMarkers(state: ListPaginationState | null): string[];
 /** The list view of ONE rendering page, handed to the template engine. */
 export interface ListPageContext {
     /** The rendering page, or null for a render outside any page. */
@@ -95,6 +156,10 @@ export interface ListPageContext {
     deps(): ListRenderDeps;
     /** Overlay values this page's render refused (also the render-wide ones). */
     overlayIssues(): readonly ListOverlayIssue[];
+    /** #1257 — the paginated list this render resolved, or null. */
+    pagination(): ListPaginationState | null;
+    /** #1257 — lists this render cut at their limit (not paginated). */
+    truncatedLists(): readonly TruncatedList[];
 }
 /** Render-wide options of {@link createListRenderContext}. */
 export interface ListRenderContextOptions {

package/dist/lists/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/lists/resolve.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/lists/resolve.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAI9C,OAAO,EAQL,KAAK,SAAS,EAEf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAGL,KAAK,sBAAsB,EAE3B,KAAK,mBAAmB,EAIzB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAEV,cAAc,EACd,cAAc,EAEd,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAgB1B,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAezD,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CAC5C;AAED,uDAAuD;AACvD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,sFAAsF;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC,CAAC;IAChF;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9E;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,GAAG,MAAM,EAAE,CAG7E;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,4DAA4D;IAC5D,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,mBAAmB,CAAC;IAC5F,+EAA+E;IAC/E,SAAS,IAAI,UAAU,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,aAAa,IAAI,UAAU,CAAC;IAC5B;;;;;OAKG;IACH,eAAe,IAAI,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5C;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IACvD,2CAA2C;IAC3C,IAAI,IAAI,cAAc,CAAC;IACvB,6EAA6E;IAC7E,aAAa,IAAI,SAAS,gBAAgB,EAAE,CAAC;IAC7C,gEAAgE;IAChE,UAAU,IAAI,mBAAmB,GAAG,IAAI,CAAC;IACzC,oEAAoE;IACpE,cAAc,IAAI,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,8DAA8D;AAC9D,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClE;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,eAAe,CAAC;IACxE,qFAAqF;IACrF,QAAQ,CAAC,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACrD;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,eAAe,EACrB,MAAM,GAAE,UAAwC,GAC/C,mBAAmB,CAErB;AAoJD,2DAA2D;AAC3D,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE,wBAA6B,GAClC,iBAAiB,CAmCnB;AAm/BD,mGAAmG;AACnG,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,CAAC,GAChD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,EAAE,CAsBnD"}

package/dist/lists/resolve.js

@@ -3,6 +3,7 @@ import { parseLinkRef } from "../link-refs.js";
 import { SITE_TEXTS_LIST_TYPE } from "./default-types.js";
 import { TERM_REF_RE, validateFieldValue } from "./fields.js";
 import { effectiveMaxDepth, LIST_QUERY_MAX_LIMIT, pageQuerySchema, } from "./list-type.js";
+import { effectivePagination, listPaginationSchema, pageCountOf, pagedUrl, splitPaginationValue, } from "./pagination.js";
 import { parseListRef } from "./refs.js";
 import { bool, dateValue, EMPTY_LIST, EMPTY_TEXT, fieldValue, linkValue, listValue, mediaValue, positionValue, selectFlag, text, untypedValue, } from "./resolve-values.js";
 /** Prefixes of the list failure markers (`docs/lists.md` §8). */
@@ -13,11 +14,25 @@ const LIST_MARKER_PREFIXES = [
     "list-source-unavailable:",
     "list-malformed:",
     "list-context-unavailable:",
+    // #1257 — a second paginated list on one page; a paginated page without a pager.
+    "list-pagination-conflict:",
+    "list-pager-missing:",
 ];
 /** True for a list failure marker — the editor's missing-content surface shows these. */
 export function isListFailureMarker(marker) {
     return LIST_MARKER_PREFIXES.some((p) => marker.startsWith(p));
 }
+/**
+ * The markers a finished render's pagination asks for: a paginated page
+ * that shows no pager strands every entry after the first page
+ * (`list-pager-missing:<field>`). Exported so the preview and the
+ * generator apply one rule.
+ */
+export function paginationMarkers(state) {
+    if (state === null || state.pageCount <= 1 || state.pagerShown)
+        return [];
+    return [`list-pager-missing:${state.field}`];
+}
 /** Resolve one list field for a page (thin wrapper, `docs/lists.md` §10). */
 export function resolveListField(field, value, page, holder = { contentInstanceId: null }) {
     return page.resolveField(field, value, holder);
@@ -212,6 +227,12 @@ function createPageContext(s, pageId, opts, renderIssues) {
     let depTree = false;
     const depPages = new Set();
     let trail = null;
+    // #1257 — pagination and cut lists of this render.
+    const requestedPage = opts.pagination?.page ?? 1;
+    let paged = null;
+    let pagerShown = false;
+    let pagerEarly = false;
+    const truncated = new Map();
     /** Entries of a page-shaped system source: their pages become deps. */
     const readPages = (pages) => {
         for (const pg of pages)
@@ -559,7 +580,8 @@ function createPageContext(s, pageId, opts, renderIssues) {
         return null;
     };
     const sameVariant = (p) => variant === null || data.pageVariants?.get(p.id)?.variant === variant;
-    const runQuery = (q) => {
+    /** Every page a query matches, in its order (deps recorded). */
+    const queryHits = (q) => {
         const parent = q.parent
             ? (parseLinkRef(q.parent)?.pageId ?? null)
             : null;
@@ -580,7 +602,96 @@ function createPageContext(s, pageId, opts, renderIssues) {
                     ? terms.every((t) => p.terms.includes(t))
                     : terms.some((t) => p.terms.includes(t)))));
         hits.sort(pageOrder(q.order, s.collator));
-        return listValue(pageEntries(hits.slice(0, q.limit)));
+        return hits;
+    };
+    /** The first `limit` hits; a cut is recorded, never silent (#1257). */
+    const cutAt = (hits, limit, field) => {
+        if (hits.length > limit) {
+            const key = `${field}:${limit}:${hits.length}`;
+            if (!truncated.has(key))
+                truncated.set(key, { field, shown: limit, total: hits.length, limit });
+        }
+        return listValue(pageEntries(hits.slice(0, limit)));
+    };
+    const runQuery = (q, field) => cutAt(queryHits(q), q.limit, field);
+    /**
+     * The slice of a paginated list this render shows. One paginated list
+     * per page: a second one (another query or page size) is refused.
+     */
+    const paginate = (field, key, hits, eff) => {
+        const fullKey = JSON.stringify([key, eff.perPage, eff.followUps]);
+        if (paged !== null && paged.key !== fullKey) {
+            return { kind: "failed", marker: `list-pagination-conflict:${field}` };
+        }
+        paged = {
+            key: fullKey,
+            field,
+            perPage: eff.perPage,
+            total: hits.length,
+            pageCount: pageCountOf(hits.length, eff.perPage),
+            followUps: eff.followUps,
+        };
+        const from = (requestedPage - 1) * eff.perPage;
+        return listValue(pageEntries(hits.slice(from, from + eff.perPage)));
+    };
+    /** Hits of the term_pages source for `terms` (deps recorded). */
+    const termPageHits = (terms) => {
+        depTree = true;
+        if (terms.length === 0)
+            return [];
+        const sorted = [...terms].sort();
+        const key = JSON.stringify([null, sorted, null]);
+        if (!depQueries.has(key))
+            depQueries.set(key, { pageType: null, terms: sorted, parent: null });
+        return s.pageList
+            .filter((p) => p.inBuild && sameVariant(p) && p.id !== pageId && terms.some((t) => p.terms.includes(t)))
+            .sort(byTitle);
+    };
+    /**
+     * The `pagination` source: one entry per page of the page's paginated
+     * list (`number`, `link`, `is_current`, `is_prev`, `is_next`); empty
+     * while everything fits on one page.
+     */
+    const pagerEntries = () => {
+        pagerShown = true;
+        const known = opts.pagination?.pageCount ?? paged?.pageCount;
+        if (known === undefined) {
+            // The list renders later on this page: the caller renders again
+            // with the page count (ListPaginationState.pagerEarly).
+            pagerEarly = true;
+            return EMPTY_LIST;
+        }
+        if (known <= 1)
+            return EMPTY_LIST;
+        const self = pageId === null ? null : parseLinkRef(`caelo:page/${pageId}`);
+        const r = self !== null && resolver ? resolver.resolve(self) : null;
+        const style = opts.pageUrlStyle;
+        if (r === null ||
+            style === undefined ||
+            (r.status !== "resolved" && r.status !== "unpublished")) {
+            return { kind: "failed", marker: "list-context-unavailable:pagination" };
+        }
+        const entries = [];
+        for (let n = 1; n <= known; n += 1) {
+            const href = n === 1 ? r.url : pagedUrl(r.url, n, style);
+            const pos = { index: n - 1, count: known, depth: 1 };
+            const values = {
+                number: text(String(n)),
+                link: linkValue({ href }, null),
+                is_current: bool(n === requestedPage),
+                is_prev: bool(n === requestedPage - 1),
+                is_next: bool(n === requestedPage + 1),
+                is_ancestor: bool(false),
+            };
+            entries.push({
+                id: `page-${n}`,
+                itemAttr: null,
+                childrenKey: null,
+                depth: 1,
+                get: (key) => values[key] ?? positionValue(key, pos),
+            });
+        }
+        return listValue(entries);
     };
     const byTitle = (a, b) => s.collator.compare(a.title, b.title) || compareIds(a.id, b.id);
     const systemSource = (name, terms, vocabularyIds, field) => {
@@ -626,22 +737,10 @@ function createPageContext(s, pageId, opts, renderIssues) {
                     depLists.add(id);
                 return termEntries(current.terms.filter((t) => ids === null || ids.has(TERM_REF_RE.exec(t)?.[1] ?? "")), field);
             }
-            case "term_pages": {
-                depTree = true;
-                if (terms.length === 0)
-                    return EMPTY_LIST;
-                const sorted = [...terms].sort();
-                const key = JSON.stringify([null, sorted, null]);
-                if (!depQueries.has(key))
-                    depQueries.set(key, { pageType: null, terms: sorted, parent: null });
-                const hits = s.pageList
-                    .filter((p) => p.inBuild &&
-                    sameVariant(p) &&
-                    p.id !== pageId &&
-                    terms.some((t) => p.terms.includes(t)))
-                    .sort(byTitle);
-                return listValue(pageEntries(hits.slice(0, LIST_QUERY_MAX_LIMIT)));
-            }
+            case "term_pages":
+                return cutAt(termPageHits(terms), LIST_QUERY_MAX_LIMIT, field);
+            case "pagination":
+                return pagerEntries();
         }
     };
     const pluginEntries = (name) => {
@@ -689,7 +788,7 @@ function createPageContext(s, pageId, opts, renderIssues) {
         switch (source.kind) {
             case "query": {
                 const q = mergedQuery(source, item.query, field, `${item.id}.query`);
-                return "marker" in q ? { kind: "failed", marker: q.marker } : runQuery(q);
+                return "marker" in q ? { kind: "failed", marker: q.marker } : runQuery(q, field);
             }
             case "system": {
                 const termFields = node.fields.filter((f) => f.type === "term");
@@ -710,8 +809,40 @@ function createPageContext(s, pageId, opts, renderIssues) {
     const fromValue = (v) => v.kind === "failed"
         ? { ok: false, marker: v.marker }
         : { ok: true, entries: v.kind === "list" ? v.entries : [] };
+    /**
+     * A paginated source field (#1257): a query, or the term_pages system
+     * source. The page size replaces the query's `limit`; the placement
+     * value may carry `paginate` overrides next to its knobs.
+     */
+    const resolvePaginated = (field, settings, value) => {
+        const { paginate: overrides, rest } = splitPaginationValue(value);
+        const valid = listPaginationSchema.safeParse(settings);
+        const eff = valid.success ? effectivePagination(valid.data, overrides) : null;
+        if (eff === null)
+            return { ok: false, marker: `list-malformed:${field.name}[paginate]` };
+        const source = field.source;
+        if (source?.kind === "query") {
+            const q = mergedQuery({ ...source, defaults: { ...source.defaults, limit: eff.perPage } }, rest, field.name, "query");
+            if ("marker" in q)
+                return { ok: false, marker: q.marker };
+            const key = JSON.stringify(["query", { ...q, limit: null }]);
+            return fromValue(paginate(field.name, key, queryHits(q), eff));
+        }
+        if (source?.kind === "system" && source.name === "term_pages") {
+            const terms = rest?.terms;
+            const list = Array.isArray(terms)
+                ? terms.filter((t) => typeof t === "string")
+                : [];
+            const key = JSON.stringify(["term_pages", [...list].sort()]);
+            return fromValue(paginate(field.name, key, termPageHits(list), eff));
+        }
+        return { ok: false, marker: `list-malformed:${field.name}[paginate]` };
+    };
     const resolveField = (field, value, holder) => {
         const bind = field.bind ?? "local";
+        if (bind === "source" && field.paginate !== undefined) {
+            return resolvePaginated(field, field.paginate, value);
+        }
         if (bind === "source") {
             const source = field.source;
             if (!source)
@@ -719,7 +850,9 @@ function createPageContext(s, pageId, opts, renderIssues) {
             switch (source.kind) {
                 case "query": {
                     const q = mergedQuery(source, value, field.name, "query");
-                    return "marker" in q ? { ok: false, marker: q.marker } : fromValue(runQuery(q));
+                    return "marker" in q
+                        ? { ok: false, marker: q.marker }
+                        : fromValue(runQuery(q, field.name));
                 }
                 case "system": {
                     const overrides = (value ?? {});
@@ -901,6 +1034,19 @@ function createPageContext(s, pageId, opts, renderIssues) {
             pages: [...depPages].sort(),
         }),
         overlayIssues: () => [...renderIssues, ...pageIssues],
+        pagination: () => paged === null
+            ? null
+            : {
+                field: paged.field,
+                perPage: paged.perPage,
+                total: paged.total,
+                pageCount: paged.pageCount,
+                page: requestedPage,
+                followUps: paged.followUps,
+                pagerShown,
+                pagerEarly,
+            },
+        truncatedLists: () => [...truncated.values()],
     };
 }
 function normaliseUrl(url) {