@seedcord/kit 0.1.1 → 0.2.0-next.0

package/dist/{CustomId-TT4MsOsD.d.mts → CustomId-CtpiL97C.d.mts}

@@ -310,5 +310,5 @@ type DecodedRoute<Defs extends readonly AnyCustomId[]> = { [Index in keyof Defs]
  */
 declare function decodeFor<Defs extends readonly AnyCustomId[]>(defs: Defs, wire: string): DecodedRoute<Defs>;
 //#endregion
-export { DecodedParams as a, BuilderType as c, prefixOf as i, RowType as l, CustomId as n, BuilderComponent as o, decodeFor as r, RowComponent as s, AnyCustomId as t };
-//# sourceMappingURL=CustomId-TT4MsOsD.d.mts.map
+export { CustomIdField as a, RowComponent as c, prefixOf as i, BuilderType as l, CustomId as n, DecodedParams as o, decodeFor as r, BuilderComponent as s, AnyCustomId as t, RowType as u };
+//# sourceMappingURL=CustomId-CtpiL97C.d.mts.map

package/dist/index.cjs

@@ -1,5 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_CustomId = require('./CustomId-NsInJKhD.cjs');
+let _seedcord_errors = require("@seedcord/errors");
+let _seedcord_errors_internal = require("@seedcord/errors/internal");
 
 //#region src/stops/Fault.ts
 /**
@@ -68,10 +70,36 @@ var Silence = class extends Error {
 	}
 };
 
+//#endregion
+//#region src/pagination/paginate.ts
+/**
+* Pure page math, usable headless. Clamps `page` into range and slices the window.
+*
+* @param items - The full list to page over.
+* @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.
+* @param perPage - The page size. Must be a positive integer.
+* @returns The sliced {@link PageView}, with `totalPages` always known.
+* @throws SeedcordRangeError when `perPage` is not a positive integer.
+*/
+function paginate(items, page, perPage) {
+	if (!Number.isInteger(perPage) || perPage <= 0) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.PaginationInvalidPerPage, [perPage]);
+	const totalPages = Math.max(1, Math.ceil(items.length / perPage));
+	const clamped = Math.min(Math.max(Math.trunc(page), 0), totalPages - 1);
+	const start = clamped * perPage;
+	return {
+		items: items.slice(start, start + perPage),
+		page: clamped,
+		perPage,
+		totalPages,
+		hasPrev: clamped > 0,
+		hasNext: clamped < totalPages - 1
+	};
+}
+
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.1.1";
+const version = "0.2.0-next.0";
 
 //#endregion
 exports.BuilderComponent = require_CustomId.BuilderComponent;
@@ -80,5 +108,6 @@ exports.Fault = Fault;
 exports.Notice = require_CustomId.Notice;
 exports.RowComponent = require_CustomId.RowComponent;
 exports.Silence = Silence;
+exports.paginate = paginate;
 exports.version = version;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["Notice","NoticeCard"],"sources":["../src/stops/Fault.ts","../src/stops/Silence.ts","../src/index.ts"],"sourcesContent":["import { Notice } from './Notice';\nimport { NoticeCard } from './NoticeCard';\n\nimport type { RenderContext, ReplyResponse } from '@seedcord/types';\n\n/**\n * A generic fault you throw after catching an error you do not have a specific message for.\n *\n * The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to\n * `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`\n * to show the generic reply without the bus publish. The original error is stored as the standard\n * `cause`, so the real stack reaches the webhook. For a fault the user should see a real message,\n * subclass {@link Notice} and write your own `render` instead.\n *\n * The framework also renders this for an unhandled throw, where it points the user at\n * `ctx.developerUsername`.\n *\n * @example\n * ```ts\n * import { Fault } from '@seedcord/kit';\n *\n * try {\n *     await db.write(record);\n * } catch (cause) {\n *     // user sees the generic reply with the uuid, the real error rides along as cause for the webhook\n *     throw new Fault({ cause });\n *\n *     // pass report: false to show the same reply without publishing to the handledException bus\n *     // throw new Fault({ cause, report: false });\n * }\n * ```\n */\nexport class Fault extends Notice {\n    public constructor(options?: { cause?: unknown; report?: boolean }) {\n        super('A fault occurred', options?.cause === undefined ? undefined : { cause: options.cause });\n        this.report = options?.report ?? true;\n    }\n\n    public render(ctx: RenderContext): ReplyResponse {\n        const contact = ctx.developerUsername ?? 'the developer';\n        const card = new NoticeCard(\n            `Something went wrong. Please reach out to ${contact} with a way to reproduce the error and the following:\\n### UUID: \\`${ctx.uuid}\\``,\n            'Error'\n        );\n        return { components: [card.component] };\n    }\n}\n","/**\n * Throw to stop a handler with no reply and no report.\n *\n * The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.\n * Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to\n * leave the user with no reply for an interaction.\n *\n * @example\n * ```ts\n * import { Silence } from '@seedcord/kit';\n *\n * // before any reply or defer, drop the interaction with no reply and no report\n * if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');\n * ```\n */\nexport class Silence extends Error {\n    /**\n     * @param reason - Optional note written only to a debug log, never shown to the user or reported.\n     */\n    public constructor(public readonly reason?: string) {\n        super(reason ?? 'Silence');\n\n        Error.captureStackTrace(this, this.constructor);\n    }\n}\n","export { BuilderComponent, RowComponent } from '@components/Component';\nexport { type RowType, type BuilderType } from '@components/builderTypes';\nexport { Notice } from '@stops/Notice';\nexport { Fault } from '@stops/Fault';\nexport { Silence } from '@stops/Silence';\nexport { CustomId } from '@customId/CustomId';\n\n/** Package version */\nexport const version = process.env.PACKAGE_VERSION ?? '0.0.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,QAAb,cAA2BA,wBAAO;CAC9B,AAAO,YAAY,SAAiD;EAChE,MAAM,oBAAoB,SAAS,UAAU,SAAY,SAAY,EAAE,OAAO,QAAQ,MAAM,CAAC;EAC7F,KAAK,SAAS,SAAS,UAAU;CACrC;CAEA,AAAO,OAAO,KAAmC;EAM7C,OAAO,EAAE,YAAY,CAAC,IAJLC,4BACb,6CAFY,IAAI,qBAAqB,gBAEgB,qEAAqE,IAAI,KAAK,KACnI,OAEqB,CAAC,CAAC,SAAS,EAAE;CAC1C;AACJ;;;;;;;;;;;;;;;;;;;AC/BA,IAAa,UAAb,cAA6B,MAAM;CAII;;;;CAAnC,AAAO,YAAY,AAAgB,QAAiB;EAChD,MAAM,UAAU,SAAS;EADM;EAG/B,MAAM,kBAAkB,MAAM,KAAK,WAAW;CAClD;AACJ;;;;;AChBA,MAAa"}
+{"version":3,"file":"index.cjs","names":["Notice","NoticeCard","SeedcordRangeError","SeedcordErrorCode"],"sources":["../src/stops/Fault.ts","../src/stops/Silence.ts","../src/pagination/paginate.ts","../src/index.ts"],"sourcesContent":["import { Notice } from './Notice';\nimport { NoticeCard } from './NoticeCard';\n\nimport type { RenderContext, ReplyResponse } from '@seedcord/types';\n\n/**\n * A generic fault you throw after catching an error you do not have a specific message for.\n *\n * The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to\n * `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`\n * to show the generic reply without the bus publish. The original error is stored as the standard\n * `cause`, so the real stack reaches the webhook. For a fault the user should see a real message,\n * subclass {@link Notice} and write your own `render` instead.\n *\n * The framework also renders this for an unhandled throw, where it points the user at\n * `ctx.developerUsername`.\n *\n * @example\n * ```ts\n * import { Fault } from '@seedcord/kit';\n *\n * try {\n *     await db.write(record);\n * } catch (cause) {\n *     // user sees the generic reply with the uuid, the real error rides along as cause for the webhook\n *     throw new Fault({ cause });\n *\n *     // pass report: false to show the same reply without publishing to the handledException bus\n *     // throw new Fault({ cause, report: false });\n * }\n * ```\n */\nexport class Fault extends Notice {\n    public constructor(options?: { cause?: unknown; report?: boolean }) {\n        super('A fault occurred', options?.cause === undefined ? undefined : { cause: options.cause });\n        this.report = options?.report ?? true;\n    }\n\n    public render(ctx: RenderContext): ReplyResponse {\n        const contact = ctx.developerUsername ?? 'the developer';\n        const card = new NoticeCard(\n            `Something went wrong. Please reach out to ${contact} with a way to reproduce the error and the following:\\n### UUID: \\`${ctx.uuid}\\``,\n            'Error'\n        );\n        return { components: [card.component] };\n    }\n}\n","/**\n * Throw to stop a handler with no reply and no report.\n *\n * The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.\n * Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to\n * leave the user with no reply for an interaction.\n *\n * @example\n * ```ts\n * import { Silence } from '@seedcord/kit';\n *\n * // before any reply or defer, drop the interaction with no reply and no report\n * if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');\n * ```\n */\nexport class Silence extends Error {\n    /**\n     * @param reason - Optional note written only to a debug log, never shown to the user or reported.\n     */\n    public constructor(public readonly reason?: string) {\n        super(reason ?? 'Silence');\n\n        Error.captureStackTrace(this, this.constructor);\n    }\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordRangeError } from '@seedcord/errors/internal';\n\nimport type { PageView } from './PageView';\n\n/**\n * Pure page math, usable headless. Clamps `page` into range and slices the window.\n *\n * @param items - The full list to page over.\n * @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.\n * @param perPage - The page size. Must be a positive integer.\n * @returns The sliced {@link PageView}, with `totalPages` always known.\n * @throws SeedcordRangeError when `perPage` is not a positive integer.\n */\nexport function paginate<Item>(items: readonly Item[], page: number, perPage: number): PageView<Item> {\n    if (!Number.isInteger(perPage) || perPage <= 0) {\n        throw new SeedcordRangeError(SeedcordErrorCode.PaginationInvalidPerPage, [perPage]);\n    }\n\n    const totalPages = Math.max(1, Math.ceil(items.length / perPage));\n    // a headless caller can pass a non-integer or out-of-range page.\n    const clamped = Math.min(Math.max(Math.trunc(page), 0), totalPages - 1);\n    const start = clamped * perPage;\n\n    return {\n        items: items.slice(start, start + perPage),\n        page: clamped,\n        perPage,\n        totalPages,\n        hasPrev: clamped > 0,\n        hasNext: clamped < totalPages - 1\n    };\n}\n","export { BuilderComponent, RowComponent } from '@components/Component';\nexport { type RowType, type BuilderType } from '@components/builderTypes';\nexport { Notice } from '@stops/Notice';\nexport { Fault } from '@stops/Fault';\nexport { Silence } from '@stops/Silence';\nexport { CustomId } from '@customId/CustomId';\nexport { paginate } from '@pagination/paginate';\nexport { type PageView } from '@pagination/PageView';\n\n/** Package version */\nexport const version = process.env.PACKAGE_VERSION ?? '0.0.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,QAAb,cAA2BA,wBAAO;CAC9B,AAAO,YAAY,SAAiD;EAChE,MAAM,oBAAoB,SAAS,UAAU,SAAY,SAAY,EAAE,OAAO,QAAQ,MAAM,CAAC;EAC7F,KAAK,SAAS,SAAS,UAAU;CACrC;CAEA,AAAO,OAAO,KAAmC;EAM7C,OAAO,EAAE,YAAY,CAAC,IAJLC,4BACb,6CAFY,IAAI,qBAAqB,gBAEgB,qEAAqE,IAAI,KAAK,KACnI,OAEqB,CAAC,CAAC,SAAS,EAAE;CAC1C;AACJ;;;;;;;;;;;;;;;;;;;AC/BA,IAAa,UAAb,cAA6B,MAAM;CAII;;;;CAAnC,AAAO,YAAY,AAAgB,QAAiB;EAChD,MAAM,UAAU,SAAS;EADM;EAG/B,MAAM,kBAAkB,MAAM,KAAK,WAAW;CAClD;AACJ;;;;;;;;;;;;;ACVA,SAAgB,SAAe,OAAwB,MAAc,SAAiC;CAClG,IAAI,CAAC,OAAO,UAAU,OAAO,KAAK,WAAW,GACzC,MAAM,IAAIC,6CAAmBC,mCAAkB,0BAA0B,CAAC,OAAO,CAAC;CAGtF,MAAM,aAAa,KAAK,IAAI,GAAG,KAAK,KAAK,MAAM,SAAS,OAAO,CAAC;CAEhE,MAAM,UAAU,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,CAAC;CACtE,MAAM,QAAQ,UAAU;CAExB,OAAO;EACH,OAAO,MAAM,MAAM,OAAO,QAAQ,OAAO;EACzC,MAAM;EACN;EACA;EACA,SAAS,UAAU;EACnB,SAAS,UAAU,aAAa;CACpC;AACJ;;;;;ACtBA,MAAa"}

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { c as BuilderType, l as RowType, n as CustomId, o as BuilderComponent, s as RowComponent } from "./CustomId-TT4MsOsD.mjs";
+import { c as RowComponent, l as BuilderType, n as CustomId, s as BuilderComponent, u as RowType } from "./CustomId-CtpiL97C.mjs";
 import { RenderContext, ReplyResponse } from "@seedcord/types";
 
 //#region src/stops/Notice.d.ts
@@ -127,9 +127,38 @@ declare class Silence extends Error {
   constructor(reason?: string | undefined);
 }
 //#endregion
+//#region src/pagination/PageView.d.ts
+/**
+ * One rendered page of a paginated list.
+ *
+ * @typeParam Item - The item type.
+ */
+interface PageView<Item> {
+  items: Item[];
+  /** Zero-based, already clamped into range. */
+  page: number;
+  perPage: number;
+  /** The total page count, or `undefined` for a cursor source that has no cheap total. */
+  totalPages?: number;
+  hasPrev: boolean;
+  hasNext: boolean;
+}
+//#endregion
+//#region src/pagination/paginate.d.ts
+/**
+ * Pure page math, usable headless. Clamps `page` into range and slices the window.
+ *
+ * @param items - The full list to page over.
+ * @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.
+ * @param perPage - The page size. Must be a positive integer.
+ * @returns The sliced {@link PageView}, with `totalPages` always known.
+ * @throws SeedcordRangeError when `perPage` is not a positive integer.
+ */
+declare function paginate<Item>(items: readonly Item[], page: number, perPage: number): PageView<Item>;
+//#endregion
 //#region src/index.d.ts
 /** Package version */
 declare const version: string;
 //#endregion
-export { BuilderComponent, type BuilderType, CustomId, Fault, Notice, RowComponent, type RowType, Silence, version };
+export { BuilderComponent, type BuilderType, CustomId, Fault, Notice, type PageView, RowComponent, type RowType, Silence, paginate, version };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,6 @@
 import { a as Notice, i as NoticeCard, o as BuilderComponent, s as RowComponent, t as CustomId } from "./CustomId-BKioviDw.mjs";
+import { SeedcordErrorCode } from "@seedcord/errors";
+import { SeedcordRangeError } from "@seedcord/errors/internal";
 
 //#region src/stops/Fault.ts
 /**
@@ -67,11 +69,37 @@ var Silence = class extends Error {
 	}
 };
 
+//#endregion
+//#region src/pagination/paginate.ts
+/**
+* Pure page math, usable headless. Clamps `page` into range and slices the window.
+*
+* @param items - The full list to page over.
+* @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.
+* @param perPage - The page size. Must be a positive integer.
+* @returns The sliced {@link PageView}, with `totalPages` always known.
+* @throws SeedcordRangeError when `perPage` is not a positive integer.
+*/
+function paginate(items, page, perPage) {
+	if (!Number.isInteger(perPage) || perPage <= 0) throw new SeedcordRangeError(SeedcordErrorCode.PaginationInvalidPerPage, [perPage]);
+	const totalPages = Math.max(1, Math.ceil(items.length / perPage));
+	const clamped = Math.min(Math.max(Math.trunc(page), 0), totalPages - 1);
+	const start = clamped * perPage;
+	return {
+		items: items.slice(start, start + perPage),
+		page: clamped,
+		perPage,
+		totalPages,
+		hasPrev: clamped > 0,
+		hasNext: clamped < totalPages - 1
+	};
+}
+
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.1.1";
+const version = "0.2.0-next.0";
 
 //#endregion
-export { BuilderComponent, CustomId, Fault, Notice, RowComponent, Silence, version };
+export { BuilderComponent, CustomId, Fault, Notice, RowComponent, Silence, paginate, version };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/stops/Fault.ts","../src/stops/Silence.ts","../src/index.ts"],"sourcesContent":["import { Notice } from './Notice';\nimport { NoticeCard } from './NoticeCard';\n\nimport type { RenderContext, ReplyResponse } from '@seedcord/types';\n\n/**\n * A generic fault you throw after catching an error you do not have a specific message for.\n *\n * The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to\n * `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`\n * to show the generic reply without the bus publish. The original error is stored as the standard\n * `cause`, so the real stack reaches the webhook. For a fault the user should see a real message,\n * subclass {@link Notice} and write your own `render` instead.\n *\n * The framework also renders this for an unhandled throw, where it points the user at\n * `ctx.developerUsername`.\n *\n * @example\n * ```ts\n * import { Fault } from '@seedcord/kit';\n *\n * try {\n *     await db.write(record);\n * } catch (cause) {\n *     // user sees the generic reply with the uuid, the real error rides along as cause for the webhook\n *     throw new Fault({ cause });\n *\n *     // pass report: false to show the same reply without publishing to the handledException bus\n *     // throw new Fault({ cause, report: false });\n * }\n * ```\n */\nexport class Fault extends Notice {\n    public constructor(options?: { cause?: unknown; report?: boolean }) {\n        super('A fault occurred', options?.cause === undefined ? undefined : { cause: options.cause });\n        this.report = options?.report ?? true;\n    }\n\n    public render(ctx: RenderContext): ReplyResponse {\n        const contact = ctx.developerUsername ?? 'the developer';\n        const card = new NoticeCard(\n            `Something went wrong. Please reach out to ${contact} with a way to reproduce the error and the following:\\n### UUID: \\`${ctx.uuid}\\``,\n            'Error'\n        );\n        return { components: [card.component] };\n    }\n}\n","/**\n * Throw to stop a handler with no reply and no report.\n *\n * The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.\n * Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to\n * leave the user with no reply for an interaction.\n *\n * @example\n * ```ts\n * import { Silence } from '@seedcord/kit';\n *\n * // before any reply or defer, drop the interaction with no reply and no report\n * if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');\n * ```\n */\nexport class Silence extends Error {\n    /**\n     * @param reason - Optional note written only to a debug log, never shown to the user or reported.\n     */\n    public constructor(public readonly reason?: string) {\n        super(reason ?? 'Silence');\n\n        Error.captureStackTrace(this, this.constructor);\n    }\n}\n","export { BuilderComponent, RowComponent } from '@components/Component';\nexport { type RowType, type BuilderType } from '@components/builderTypes';\nexport { Notice } from '@stops/Notice';\nexport { Fault } from '@stops/Fault';\nexport { Silence } from '@stops/Silence';\nexport { CustomId } from '@customId/CustomId';\n\n/** Package version */\nexport const version = process.env.PACKAGE_VERSION ?? '0.0.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,QAAb,cAA2B,OAAO;CAC9B,AAAO,YAAY,SAAiD;EAChE,MAAM,oBAAoB,SAAS,UAAU,SAAY,SAAY,EAAE,OAAO,QAAQ,MAAM,CAAC;EAC7F,KAAK,SAAS,SAAS,UAAU;CACrC;CAEA,AAAO,OAAO,KAAmC;EAM7C,OAAO,EAAE,YAAY,CAAC,IAJL,WACb,6CAFY,IAAI,qBAAqB,gBAEgB,qEAAqE,IAAI,KAAK,KACnI,OAEqB,CAAC,CAAC,SAAS,EAAE;CAC1C;AACJ;;;;;;;;;;;;;;;;;;;AC/BA,IAAa,UAAb,cAA6B,MAAM;CAII;;;;CAAnC,AAAO,YAAY,AAAgB,QAAiB;EAChD,MAAM,UAAU,SAAS;EADM;EAG/B,MAAM,kBAAkB,MAAM,KAAK,WAAW;CAClD;AACJ;;;;;AChBA,MAAa"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/stops/Fault.ts","../src/stops/Silence.ts","../src/pagination/paginate.ts","../src/index.ts"],"sourcesContent":["import { Notice } from './Notice';\nimport { NoticeCard } from './NoticeCard';\n\nimport type { RenderContext, ReplyResponse } from '@seedcord/types';\n\n/**\n * A generic fault you throw after catching an error you do not have a specific message for.\n *\n * The user sees a fixed generic reply with the tracking uuid, never the cause. `report` defaults to\n * `true`, so the framework logs it and publishes it to the `handledException` bus. Pass `report: false`\n * to show the generic reply without the bus publish. The original error is stored as the standard\n * `cause`, so the real stack reaches the webhook. For a fault the user should see a real message,\n * subclass {@link Notice} and write your own `render` instead.\n *\n * The framework also renders this for an unhandled throw, where it points the user at\n * `ctx.developerUsername`.\n *\n * @example\n * ```ts\n * import { Fault } from '@seedcord/kit';\n *\n * try {\n *     await db.write(record);\n * } catch (cause) {\n *     // user sees the generic reply with the uuid, the real error rides along as cause for the webhook\n *     throw new Fault({ cause });\n *\n *     // pass report: false to show the same reply without publishing to the handledException bus\n *     // throw new Fault({ cause, report: false });\n * }\n * ```\n */\nexport class Fault extends Notice {\n    public constructor(options?: { cause?: unknown; report?: boolean }) {\n        super('A fault occurred', options?.cause === undefined ? undefined : { cause: options.cause });\n        this.report = options?.report ?? true;\n    }\n\n    public render(ctx: RenderContext): ReplyResponse {\n        const contact = ctx.developerUsername ?? 'the developer';\n        const card = new NoticeCard(\n            `Something went wrong. Please reach out to ${contact} with a way to reproduce the error and the following:\\n### UUID: \\`${ctx.uuid}\\``,\n            'Error'\n        );\n        return { components: [card.component] };\n    }\n}\n","/**\n * Throw to stop a handler with no reply and no report.\n *\n * The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.\n * Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to\n * leave the user with no reply for an interaction.\n *\n * @example\n * ```ts\n * import { Silence } from '@seedcord/kit';\n *\n * // before any reply or defer, drop the interaction with no reply and no report\n * if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');\n * ```\n */\nexport class Silence extends Error {\n    /**\n     * @param reason - Optional note written only to a debug log, never shown to the user or reported.\n     */\n    public constructor(public readonly reason?: string) {\n        super(reason ?? 'Silence');\n\n        Error.captureStackTrace(this, this.constructor);\n    }\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordRangeError } from '@seedcord/errors/internal';\n\nimport type { PageView } from './PageView';\n\n/**\n * Pure page math, usable headless. Clamps `page` into range and slices the window.\n *\n * @param items - The full list to page over.\n * @param page - The requested zero-based page, clamped into `[0, totalPages - 1]`.\n * @param perPage - The page size. Must be a positive integer.\n * @returns The sliced {@link PageView}, with `totalPages` always known.\n * @throws SeedcordRangeError when `perPage` is not a positive integer.\n */\nexport function paginate<Item>(items: readonly Item[], page: number, perPage: number): PageView<Item> {\n    if (!Number.isInteger(perPage) || perPage <= 0) {\n        throw new SeedcordRangeError(SeedcordErrorCode.PaginationInvalidPerPage, [perPage]);\n    }\n\n    const totalPages = Math.max(1, Math.ceil(items.length / perPage));\n    // a headless caller can pass a non-integer or out-of-range page.\n    const clamped = Math.min(Math.max(Math.trunc(page), 0), totalPages - 1);\n    const start = clamped * perPage;\n\n    return {\n        items: items.slice(start, start + perPage),\n        page: clamped,\n        perPage,\n        totalPages,\n        hasPrev: clamped > 0,\n        hasNext: clamped < totalPages - 1\n    };\n}\n","export { BuilderComponent, RowComponent } from '@components/Component';\nexport { type RowType, type BuilderType } from '@components/builderTypes';\nexport { Notice } from '@stops/Notice';\nexport { Fault } from '@stops/Fault';\nexport { Silence } from '@stops/Silence';\nexport { CustomId } from '@customId/CustomId';\nexport { paginate } from '@pagination/paginate';\nexport { type PageView } from '@pagination/PageView';\n\n/** Package version */\nexport const version = process.env.PACKAGE_VERSION ?? '0.0.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,QAAb,cAA2B,OAAO;CAC9B,AAAO,YAAY,SAAiD;EAChE,MAAM,oBAAoB,SAAS,UAAU,SAAY,SAAY,EAAE,OAAO,QAAQ,MAAM,CAAC;EAC7F,KAAK,SAAS,SAAS,UAAU;CACrC;CAEA,AAAO,OAAO,KAAmC;EAM7C,OAAO,EAAE,YAAY,CAAC,IAJL,WACb,6CAFY,IAAI,qBAAqB,gBAEgB,qEAAqE,IAAI,KAAK,KACnI,OAEqB,CAAC,CAAC,SAAS,EAAE;CAC1C;AACJ;;;;;;;;;;;;;;;;;;;AC/BA,IAAa,UAAb,cAA6B,MAAM;CAII;;;;CAAnC,AAAO,YAAY,AAAgB,QAAiB;EAChD,MAAM,UAAU,SAAS;EADM;EAG/B,MAAM,kBAAkB,MAAM,KAAK,WAAW;CAClD;AACJ;;;;;;;;;;;;;ACVA,SAAgB,SAAe,OAAwB,MAAc,SAAiC;CAClG,IAAI,CAAC,OAAO,UAAU,OAAO,KAAK,WAAW,GACzC,MAAM,IAAI,mBAAmB,kBAAkB,0BAA0B,CAAC,OAAO,CAAC;CAGtF,MAAM,aAAa,KAAK,IAAI,GAAG,KAAK,KAAK,MAAM,SAAS,OAAO,CAAC;CAEhE,MAAM,UAAU,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,CAAC;CACtE,MAAM,QAAQ,UAAU;CAExB,OAAO;EACH,OAAO,MAAM,MAAM,OAAO,QAAQ,OAAO;EACzC,MAAM;EACN;EACA;EACA,SAAS,UAAU;EACnB,SAAS,UAAU,aAAa;CACpC;AACJ;;;;;ACtBA,MAAa"}

package/dist/internal.index.cjs

@@ -1,6 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_CustomId = require('./CustomId-NsInJKhD.cjs');
 
+//#region src/pagination/cursor.ts
+const PAGE_MAX = 1e6;
+const SLOT_MAX = 4;
+/** Build the page cursor for a paginator. */
+function pageCursor(prefix) {
+	return new require_CustomId.CustomId(prefix).int("page", 0, PAGE_MAX).int("slot", 0, 4);
+}
+
+//#endregion
 //#region src/customId/routing.ts
 /**
 * The route decorators store a handler's customId definitions here so the component base can decode
@@ -13,7 +22,9 @@ const ComponentDefsKey = Symbol("seedcord:customId:componentDefs");
 //#endregion
 exports.ComponentDefsKey = ComponentDefsKey;
 exports.NoticeCard = require_CustomId.NoticeCard;
+exports.PAGE_MAX = PAGE_MAX;
 exports.decodeFor = require_CustomId.decodeFor;
+exports.pageCursor = pageCursor;
 exports.prefixOf = require_CustomId.prefixOf;
 exports.setBotColor = require_CustomId.setBotColor;
 //# sourceMappingURL=internal.index.cjs.map

package/dist/internal.index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"internal.index.cjs","names":[],"sources":["../src/customId/routing.ts"],"sourcesContent":["import type { AnyCustomId } from './CustomId';\n\n/**\n * The route decorators store a handler's customId definitions here so the component base can decode\n * against them at runtime.\n *\n * @internal\n */\nexport const ComponentDefsKey = Symbol('seedcord:customId:componentDefs');\n\n/**\n * The phantom a component handler base carries. A route decorator constrains its argument to this, so\n * passing different definitions to the decorator and the handler's generic is a compile error. Never set at runtime.\n *\n * @internal\n */\nexport interface HasComponentDefs<Defs extends readonly AnyCustomId[]> {\n    readonly __componentDefs?: Defs;\n}\n"],"mappings":";;;;;;;;;;AAQA,MAAa,mBAAmB,OAAO,iCAAiC"}
+{"version":3,"file":"internal.index.cjs","names":["CustomId"],"sources":["../src/pagination/cursor.ts","../src/customId/routing.ts"],"sourcesContent":["import { CustomId } from '@customId/CustomId';\n\nimport type { CustomIdField } from '@customId/Field';\n\n// Included in the layout hash so it is fixed per prefix. Reducing it marks every active button as StaleCustomId.\n// @internal\nexport const PAGE_MAX = 1_000_000;\n\n// Discord rejects a message with duplicate custom_ids, and two controls can target the same page (first and\n// prev both hit 0), so each control uses a distinct slot.\n// @internal\nexport const SLOT_MAX = 4;\n\n/** Page cursor for a paginator. */\nexport type PageCursor<Prefix extends string> = CustomId<\n    Prefix,\n    { page: CustomIdField<number>; slot: CustomIdField<number> }\n>;\n\n/** Build the page cursor for a paginator. */\nexport function pageCursor<Prefix extends string>(prefix: Prefix): PageCursor<Prefix> {\n    return new CustomId(prefix).int('page', 0, PAGE_MAX).int('slot', 0, SLOT_MAX);\n}\n","import type { AnyCustomId } from './CustomId';\n\n/**\n * The route decorators store a handler's customId definitions here so the component base can decode\n * against them at runtime.\n *\n * @internal\n */\nexport const ComponentDefsKey = Symbol('seedcord:customId:componentDefs');\n\n/**\n * The phantom a component handler base carries. A route decorator constrains its argument to this, so\n * passing different definitions to the decorator and the handler's generic is a compile error. Never set at runtime.\n *\n * @internal\n */\nexport interface HasComponentDefs<Defs extends readonly AnyCustomId[]> {\n    readonly __componentDefs?: Defs;\n}\n"],"mappings":";;;;AAMA,MAAa,WAAW;AAKxB,MAAa,WAAW;;AASxB,SAAgB,WAAkC,QAAoC;CAClF,OAAO,IAAIA,0BAAS,MAAM,CAAC,CAAC,IAAI,QAAQ,GAAG,QAAQ,CAAC,CAAC,IAAI,QAAQ,IAAW;AAChF;;;;;;;;;;ACdA,MAAa,mBAAmB,OAAO,iCAAiC"}

package/dist/internal.index.d.mts

@@ -1,10 +1,20 @@
-import { a as DecodedParams, i as prefixOf, o as BuilderComponent, r as decodeFor, t as AnyCustomId } from "./CustomId-TT4MsOsD.mjs";
+import { a as CustomIdField, i as prefixOf, n as CustomId, o as DecodedParams, r as decodeFor, s as BuilderComponent, t as AnyCustomId } from "./CustomId-CtpiL97C.mjs";
 import { ColorResolvable } from "discord.js";
 
 //#region src/botColorHolder.d.ts
 /** @internal */
 declare function setBotColor(color: ColorResolvable | undefined): void;
 //#endregion
+//#region src/pagination/cursor.d.ts
+declare const PAGE_MAX = 1000000;
+/** Page cursor for a paginator. */
+type PageCursor<Prefix extends string> = CustomId<Prefix, {
+  page: CustomIdField<number>;
+  slot: CustomIdField<number>;
+}>;
+/** Build the page cursor for a paginator. */
+declare function pageCursor<Prefix extends string>(prefix: Prefix): PageCursor<Prefix>;
+//#endregion
 //#region src/customId/routing.d.ts
 /**
  * The route decorators store a handler's customId definitions here so the component base can decode
@@ -32,5 +42,5 @@ declare class NoticeCard extends BuilderComponent<'container'> {
   constructor(description: string, title?: string);
 }
 //#endregion
-export { type AnyCustomId, ComponentDefsKey, type DecodedParams, type HasComponentDefs, NoticeCard, decodeFor, prefixOf, setBotColor };
+export { type AnyCustomId, ComponentDefsKey, type DecodedParams, type HasComponentDefs, NoticeCard, PAGE_MAX, type PageCursor, decodeFor, pageCursor, prefixOf, setBotColor };
 //# sourceMappingURL=internal.index.d.mts.map

package/dist/internal.index.mjs

@@ -1,5 +1,14 @@
-import { c as setBotColor, i as NoticeCard, n as decodeFor, r as prefixOf } from "./CustomId-BKioviDw.mjs";
+import { c as setBotColor, i as NoticeCard, n as decodeFor, r as prefixOf, t as CustomId } from "./CustomId-BKioviDw.mjs";
 
+//#region src/pagination/cursor.ts
+const PAGE_MAX = 1e6;
+const SLOT_MAX = 4;
+/** Build the page cursor for a paginator. */
+function pageCursor(prefix) {
+	return new CustomId(prefix).int("page", 0, PAGE_MAX).int("slot", 0, 4);
+}
+
+//#endregion
 //#region src/customId/routing.ts
 /**
 * The route decorators store a handler's customId definitions here so the component base can decode
@@ -10,5 +19,5 @@ import { c as setBotColor, i as NoticeCard, n as decodeFor, r as prefixOf } from
 const ComponentDefsKey = Symbol("seedcord:customId:componentDefs");
 
 //#endregion
-export { ComponentDefsKey, NoticeCard, decodeFor, prefixOf, setBotColor };
+export { ComponentDefsKey, NoticeCard, PAGE_MAX, decodeFor, pageCursor, prefixOf, setBotColor };
 //# sourceMappingURL=internal.index.mjs.map

package/dist/internal.index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"internal.index.mjs","names":[],"sources":["../src/customId/routing.ts"],"sourcesContent":["import type { AnyCustomId } from './CustomId';\n\n/**\n * The route decorators store a handler's customId definitions here so the component base can decode\n * against them at runtime.\n *\n * @internal\n */\nexport const ComponentDefsKey = Symbol('seedcord:customId:componentDefs');\n\n/**\n * The phantom a component handler base carries. A route decorator constrains its argument to this, so\n * passing different definitions to the decorator and the handler's generic is a compile error. Never set at runtime.\n *\n * @internal\n */\nexport interface HasComponentDefs<Defs extends readonly AnyCustomId[]> {\n    readonly __componentDefs?: Defs;\n}\n"],"mappings":";;;;;;;;;AAQA,MAAa,mBAAmB,OAAO,iCAAiC"}
+{"version":3,"file":"internal.index.mjs","names":[],"sources":["../src/pagination/cursor.ts","../src/customId/routing.ts"],"sourcesContent":["import { CustomId } from '@customId/CustomId';\n\nimport type { CustomIdField } from '@customId/Field';\n\n// Included in the layout hash so it is fixed per prefix. Reducing it marks every active button as StaleCustomId.\n// @internal\nexport const PAGE_MAX = 1_000_000;\n\n// Discord rejects a message with duplicate custom_ids, and two controls can target the same page (first and\n// prev both hit 0), so each control uses a distinct slot.\n// @internal\nexport const SLOT_MAX = 4;\n\n/** Page cursor for a paginator. */\nexport type PageCursor<Prefix extends string> = CustomId<\n    Prefix,\n    { page: CustomIdField<number>; slot: CustomIdField<number> }\n>;\n\n/** Build the page cursor for a paginator. */\nexport function pageCursor<Prefix extends string>(prefix: Prefix): PageCursor<Prefix> {\n    return new CustomId(prefix).int('page', 0, PAGE_MAX).int('slot', 0, SLOT_MAX);\n}\n","import type { AnyCustomId } from './CustomId';\n\n/**\n * The route decorators store a handler's customId definitions here so the component base can decode\n * against them at runtime.\n *\n * @internal\n */\nexport const ComponentDefsKey = Symbol('seedcord:customId:componentDefs');\n\n/**\n * The phantom a component handler base carries. A route decorator constrains its argument to this, so\n * passing different definitions to the decorator and the handler's generic is a compile error. Never set at runtime.\n *\n * @internal\n */\nexport interface HasComponentDefs<Defs extends readonly AnyCustomId[]> {\n    readonly __componentDefs?: Defs;\n}\n"],"mappings":";;;AAMA,MAAa,WAAW;AAKxB,MAAa,WAAW;;AASxB,SAAgB,WAAkC,QAAoC;CAClF,OAAO,IAAI,SAAS,MAAM,CAAC,CAAC,IAAI,QAAQ,GAAG,QAAQ,CAAC,CAAC,IAAI,QAAQ,IAAW;AAChF;;;;;;;;;;ACdA,MAAa,mBAAmB,OAAO,iCAAiC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seedcord/kit",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.0-next.0",
   "description": "Reusable Seedcord building blocks: component builders, the Notice error tree, and the typed customId codec",
   "repository": {
     "type": "git",
@@ -42,15 +42,15 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@seedcord/errors": "0.2.0",
+    "@seedcord/errors": "0.2.1-next.0",
     "@seedcord/types": "0.7.0"
   },
   "devDependencies": {
     "discord.js": "^14.26.4",
     "type-fest": "^5.7.0",
     "vite": "^8.0.16",
-    "@seedcord/eslint-config": "1.4.2",
     "@seedcord/tsconfig": "2.0.0",
+    "@seedcord/eslint-config": "1.4.2",
     "@seedcord/tsdown-config": "2.0.0"
   },
   "publishConfig": {