@pkcprotocol/active-page-sort 0.0.5 → 0.0.7

package/AGENTS.md

@@ -25,11 +25,12 @@ Conventions specific to this package:
 - `NO_BUMP_KEYWORDS_OPTION` (`noBumpKeywords`) is the wire contract. UIs read it off
   `community.pageSorts.posts.active.publicOptions` to render a sage marker, and most of them never install
   this package. A rename is a new contract, never an edit. The literal is pinned in `test/unit/no-bump.test.ts`.
+  `BUMP_LIMIT_OPTION` (`bumpLimit`) is the same kind of contract and is pinned next to it.
 - The match is a whole line equal to the keyword, exact and case-sensitive. `src/no-bump.ts` imports
   nothing and must keep matching what the README describes, because UIs copy or bundle it for the browser.
 - `score` is sync and never returns `null`: a saged thread sinks, it is not filtered. It reads
   `comment.timestamp`, the reserved `exclude*` options, and per reply `timestamp`, `content`, and the
-  CommentUpdate's `removed`, `approved`, `pendingApproval` and `edit.deleted`. There is no database access and
+  CommentUpdate's `cid`, `removed`, `approved`, `pendingApproval` and `edit.deleted`. There is no database access and
   no network; a need for either is a later iteration of the pkc-js contract, not a reason to reach around it.
 - `isCountedReply` / `bumpTimestamp` (in `src/no-bump.ts`) apply the `exclude*` options to each reply's own
   CommentUpdate, the tombstone rule of pkc-js's "Which replies count" (`docs/protocol/comment-lifecycle.md`):
@@ -38,9 +39,11 @@ Conventions specific to this package:
   (trimmed, case-insensitive `true`). With the `posts` defaults it must match the built-in `active`. A new
   reserved exclusion in pkc-js means a release here. `excludeCommentsWithDifferentCommunityAddress` is left
   out on purpose: pkc-js applies it, and `score` has no community address (pkc-js#401).
+- The bump limit counts the replies `isCountedReply` keeps, saged or not, ordered by `(timestamp, cid)` with the
+  CID compared as a plain string, so the community and a client re-sort agree on a tie at the boundary.
 - The scorer ignores `commentUpdate.lastReplyTimestamp` on purpose. That aggregate counts saged replies.
 - `validatePageSortSettings` is sync and rejects only what can never work (empty list, line break, size
-  bounds). An unset option is valid and means plain bump order.
+  bounds, a `bumpLimit` that is not a positive integer). An unset option is valid and means plain bump order.
 - Test fixtures are typed against pkc-js's own types through `test/unit/fixtures.ts`. Do not cast a
   fixture through `unknown`; a field that does not exist on the wire must fail to compile.
 - Never use the `any` type.

package/README.md

@@ -10,12 +10,13 @@ A board's catalog shows threads in bump order: the thread with the newest reply
 - A **no-bump reply** is a reply whose content has a whole line equal to one of the configured keywords. The match is exact and case-sensitive: a content of `sage`, or a multi-line content with a line that is exactly `sage`, does not bump. `sage is overused` in prose, `Sage`, `#sage` and ` sage` all bump.
 - Replies **under** a no-bump reply still count, at any depth. Someone answering a saged reply bumps the thread as usual.
 - A reply the sort's exclusion options drop (by default: removed, deleted, disapproved or pending approval) does not bump the thread, but the present replies under it still do, at any depth: a removed or deleted reply is a **tombstone**, not a cut. This is pkc-js's [Which replies count](https://github.com/pkcprotocol/pkc-js/blob/master/docs/protocol/comment-lifecycle.md#which-replies-count) rule, the one the built-in `active` follows through `lastReplyTimestamp`. A board that turns a flag off (`excludeDeletedComments: "false"`) lets those replies bump again.
-- A saged thread **sinks, it is never hidden**. The sort ranks, it does not filter.
-- With the keyword option unset the sort is plain bump order, identical to pkc-js's built-in `active`.
+- With a **bump limit** set, only a thread's first `bumpLimit` counted replies can bump it. Past the limit the thread stays open and keeps taking replies, but none of them bump it, so it sinks, the imageboard bump limit. Every counted reply counts toward the limit, saged or not, at any depth. "First" is by reply timestamp, ties broken by the reply's CID.
+- A saged thread, or one past its bump limit, **sinks, it is never hidden**. The sort ranks, it does not filter.
+- With both options unset the sort is plain bump order, identical to pkc-js's built-in `active`.
 
 The sort publishes under the wire key `active`, the same key as the built-in, so a UI that already reads `community.posts.pages.active` shows the saged order without any change. The community also publishes what the key means in `community.pageSorts.posts.active`, including the keyword list, so a UI can tell this sort from the built-in and render a sage marker on matching replies.
 
-The word `sage` appears nowhere in this package. The board supplies its vocabulary through the `noBumpKeywords` option.
+The word `sage` appears nowhere in this package. The board supplies its vocabulary through the `noBumpKeywords` option, and its limit through `bumpLimit`.
 
 ## How the sorting works
 
@@ -23,7 +24,8 @@ pkc-js regenerates a community's post pages on every publish cycle. For each con
 
 ```
 counted = replies no exclude* option that is on drops (each judged on its own)
-max(post.timestamp, ...counted.filter(not no-bump).map(reply => reply.timestamp))
+within  = counted sorted by (timestamp, cid), the first bumpLimit of them (all of them without a limit)
+max(post.timestamp, ...within.filter(not no-bump).map(reply => reply.timestamp))
 ```
 
 Each reply is judged on its own, so a skipped reply never hides the replies under it. The reply pages a UI walks keep removed and deleted replies as tombstones too, so a raw walk scores like the community (see [Re-sort a page locally](#4-re-sort-a-page-locally-optional)). That is the whole algorithm. pkc-js owns everything around it: pinned threads first (`pinnedFirst`), the optional age window (`maxAge`), chunking into pages, the moderation exclusions on the threads being ranked. The file contains no date arithmetic and never sees a pinned flag.
@@ -119,11 +121,12 @@ Page sort options are strings, like challenge options. Unlike challenge options
 | Option | Required | Published in `publicOptions` | Default | Description |
 |---|---|---|---|---|
 | `noBumpKeywords` | no | yes, unless listed in `privateOptions` | unset (plain bump order) | Comma-separated keywords, e.g. `sage` or `sage,nobump`. A reply whose content has a whole line equal to one of these does not bump its thread. Exact and case-sensitive |
+| `bumpLimit` | no | yes, unless listed in `privateOptions` | unset (no limit) | A positive integer, e.g. `"300"`. Only a thread's first this many counted replies, saged or not, can bump it; past the limit it sinks while staying open. Counted replies are the ones the `exclude*` options keep, the same set as the thread's `replyCount` |
 | `maxAge` | no | always (reserved) | none | pkc-js reserved: a sliding window such as `"36h"`, `"7d"`, `"2w"`, `"1M"`, `"1y"`. Threads older than the window drop out of the pages (pinned threads bypass it) |
 | `pinnedFirst` | no | always (reserved) | `"true"` | pkc-js reserved: pinned threads first and outside the window. `"false"` treats them as ordinary threads |
 | `excludeRemovedComments`, `excludeDeletedComments`, `excludeCommentPendingApproval`, `excludeCommentWithApprovedFalse`, `excludeCommentsWithDifferentCommunityAddress` | no | always (reserved) | `"true"` for the `posts` scope | pkc-js reserved moderation filters on the threads the sort ranks. `score` also applies the first four to the replies: a reply one of them drops does not bump, the replies under it still do. `excludeCommentsWithDifferentCommunityAddress` is applied to replies by pkc-js before `score` runs (checking it needs the community's address, which `score` does not get, [pkc-js#401](https://github.com/pkcprotocol/pkc-js/issues/401)) |
 
-Keep `noBumpKeywords` public unless you have a reason not to: a UI reads it to know the board supports sage, to put the keyword on the wire the way the sort reads it, and to mark saged replies. With the option private the order still applies but UIs cannot do any of that. The reserved options cannot be made private (`ERR_PAGE_SORT_RESERVED_OPTION_CANNOT_BE_PRIVATE`): a client re-sorting a page must know how its comment set was filtered. Their full semantics are in the pkc-js page sorts doc, "Reserved options". If pkc-js adds a reserved exclusion, this package needs a release that applies it to replies too.
+Keep `noBumpKeywords` public unless you have a reason not to: a UI reads it to know the board supports sage, to put the keyword on the wire the way the sort reads it, and to mark saged replies. With the option private the order still applies but UIs cannot do any of that. The same goes for `bumpLimit`: a UI compares it to a thread's `replyCount` to show that the thread no longer bumps. The reserved options cannot be made private (`ERR_PAGE_SORT_RESERVED_OPTION_CANNOT_BE_PRIVATE`): a client re-sorting a page must know how its comment set was filtered. Their full semantics are in the pkc-js page sorts doc, "Reserved options". If pkc-js adds a reserved exclusion, this package needs a release that applies it to replies too.
 
 ### Validation
 
@@ -132,6 +135,7 @@ The entry is validated when the community is created, on every edit (rejecting t
 - `noBumpKeywords` set but holding no keyword (`""`, `" , ,"`): that would silently be plain bump order. Unset it instead.
 - More than 64 keywords, or a keyword over 128 characters.
 - A keyword containing a line break, which can never equal a line.
+- `bumpLimit` set to anything but a positive integer (`"0"`, `"-1"`, `"1.5"`, `"300 replies"`, `""`). Surrounding whitespace is trimmed. Unset it for no limit.
 
 Failures surface as `ERR_PAGE_SORT_SETTINGS_VALIDATION_FAILED` inside pkc-js's aggregated `ERR_PAGE_SORT_SETTINGS_VALIDATION_FAILED_FOR_PAGE_SORTS`.
 
@@ -142,9 +146,10 @@ community.pageSorts = {
     posts: {
         active: {
             name: "@pkcprotocol/active-page-sort", // absent for a path entry
-            description: "Bump order where a reply whose content has a line equal to a configured keyword does not bump its thread",
+            description: "Bump order where a reply whose content has a line equal to a configured keyword does not bump its thread, with an optional bump limit",
             publicOptions: {
                 noBumpKeywords: "sage",
+                bumpLimit: "300",
                 pinnedFirst: "true",
                 excludeRemovedComments: "true",
                 excludeDeletedComments: "true",
@@ -190,7 +195,7 @@ import { isNoBumpReplyForOptions } from "@pkcprotocol/active-page-sort";
 const saged = isNoBumpReplyForOptions(reply.content, community.pageSorts?.posts?.active?.publicOptions);
 ```
 
-`isNoBumpContent(content, keywords)` and `splitKeywords(raw)` are the same test without the options lookup, and `bumpTimestamp({ postTimestamp, replies, keywords, options })` gives a thread's effective bump time from a reply tree walked from reply pages, tombstones included, with the published `publicOptions` as `options`. `isCountedReply(reply, options)` is the exclusion check on its own. `src/no-bump.ts` imports nothing and bundles for a browser.
+`isNoBumpContent(content, keywords)` and `splitKeywords(raw)` are the same test without the options lookup, and `bumpTimestamp({ postTimestamp, replies, keywords, options, bumpLimit })` gives a thread's effective bump time from a reply tree walked from reply pages, tombstones included, with the published `publicOptions` as `options` and `parseBumpLimit(publicOptions.bumpLimit)` as `bumpLimit`. `isCountedReply(reply, options)` is the exclusion check on its own. `src/no-bump.ts` imports nothing and bundles for a browser.
 
 ### 4. Re-sort a page locally (optional)
 
@@ -216,8 +221,8 @@ Treat `community.pageSorts[].name` as data: look it up in your own registry, nev
 |---|---|
 | `default` / `activePageSort` | The `PageSortFileFactory` pkc-js calls |
 | `SORT_NAME`, `DESCRIPTION`, `optionInputs`, `validatePageSortSettings` | The file's declared surface, for config UIs and tests |
-| `NO_BUMP_KEYWORDS_OPTION` | `"noBumpKeywords"`, the option key. Renaming it is a new contract |
-| `splitKeywords`, `isNoBumpContent`, `bumpTimestamp`, `isNoBumpReplyForOptions` | The matching rules, import-free, for browsers |
+| `NO_BUMP_KEYWORDS_OPTION`, `BUMP_LIMIT_OPTION` | `"noBumpKeywords"` and `"bumpLimit"`, the option keys. Renaming one is a new contract |
+| `splitKeywords`, `isNoBumpContent`, `parseBumpLimit`, `bumpTimestamp`, `isNoBumpReplyForOptions` | The matching rules, import-free, for browsers |
 | `isCountedReply`, `EXCLUSION_OPTIONS` | Whether a reply can bump at all: the published `exclude*` options checked against its own CommentUpdate, never its ancestors. Import-free |
 | `PageSortFile`, `PageSortFileInput`, `PageSortFileFactory`, `PageSortFileFactoryInput`, `PageSortFileFactoryArgs`, `PageSortScoreArgs`, `PageSortReplyEntry`, `PageSortScope`, `CommunityPageSortSetting` | Re-exported pkc-js types (root exports since pkc-js 0.0.110) |
 | `PageSortSettingsEntry` | Alias of `CommunityPageSortSetting`, the `settings.pages` entry the factory receives |

package/dist/active-page-sort.d.ts

@@ -1,7 +1,7 @@
 import type { PageSortFile, PageSortFileFactory, PageSortSettingsEntry } from "./types.js";
 /** The wire key: this sort publishes under `community.posts.pages.active` / `pageCids.active`, like the built-in it replaces. */
 export declare const SORT_NAME = "active";
-export declare const DESCRIPTION = "Bump order where a reply whose content has a line equal to a configured keyword does not bump its thread";
+export declare const DESCRIPTION = "Bump order where a reply whose content has a line equal to a configured keyword does not bump its thread, with an optional bump limit";
 export declare const MAX_KEYWORDS = 64;
 export declare const MAX_KEYWORD_LENGTH = 128;
 export declare const optionInputs: NonNullable<PageSortFile["optionInputs"]>;

package/dist/active-page-sort.js

@@ -1,7 +1,7 @@
-import { NO_BUMP_KEYWORDS_OPTION, bumpTimestamp, isNoBumpContent, splitKeywords } from "./no-bump.js";
+import { BUMP_LIMIT_OPTION, NO_BUMP_KEYWORDS_OPTION, bumpTimestamp, isNoBumpContent, parseBumpLimit, splitKeywords } from "./no-bump.js";
 /** The wire key: this sort publishes under `community.posts.pages.active` / `pageCids.active`, like the built-in it replaces. */
 export const SORT_NAME = "active";
-export const DESCRIPTION = "Bump order where a reply whose content has a line equal to a configured keyword does not bump its thread";
+export const DESCRIPTION = "Bump order where a reply whose content has a line equal to a configured keyword does not bump its thread, with an optional bump limit";
 export const MAX_KEYWORDS = 64;
 export const MAX_KEYWORD_LENGTH = 128;
 export const optionInputs = [
@@ -10,6 +10,12 @@ export const optionInputs = [
         label: "No-bump keywords",
         description: "Comma-separated. A reply whose content has a whole line equal to one of these does not bump its thread (exact, case-sensitive). Leave unset for plain bump order.",
         placeholder: "sage"
+    },
+    {
+        option: BUMP_LIMIT_OPTION,
+        label: "Bump limit",
+        description: "A positive integer. Only a thread's first this many replies, saged or not, can bump it; past the limit it sinks while staying open. Leave unset for no limit.",
+        placeholder: "300"
     }
 ];
 const keywordsOf = (pageSortSettings) => splitKeywords(pageSortSettings.options?.[NO_BUMP_KEYWORDS_OPTION]);
@@ -18,6 +24,9 @@ const keywordsOf = (pageSortSettings) => splitKeywords(pageSortSettings.options?
  * cannot match anything, which would silently turn the board into plain bump order.
  */
 export const validatePageSortSettings = ({ pageSortSettings }) => {
+    const rawLimit = pageSortSettings.options?.[BUMP_LIMIT_OPTION];
+    if (rawLimit !== undefined && parseBumpLimit(rawLimit) === undefined)
+        throw new Error(`${BUMP_LIMIT_OPTION} must be a positive integer, got "${rawLimit.slice(0, 32)}": unset it for no limit`);
     const raw = pageSortSettings.options?.[NO_BUMP_KEYWORDS_OPTION];
     if (raw === undefined)
         return;
@@ -41,6 +50,7 @@ export const validatePageSortSettings = ({ pageSortSettings }) => {
  */
 export const activePageSort = ({ pageSortSettings }) => {
     const keywords = keywordsOf(pageSortSettings);
+    const bumpLimit = parseBumpLimit(pageSortSettings.options?.[BUMP_LIMIT_OPTION]);
     return {
         sortName: SORT_NAME,
         description: DESCRIPTION,
@@ -51,7 +61,7 @@ export const activePageSort = ({ pageSortSettings }) => {
         // MAX(timestamp) over the post and its counted, non-no-bump descendants. pkc-js hands `replies` as one flat
         // list of every descendant, tombstones and pending replies included (pkc-js#407), and so does a client's walk
         // of the reply pages; bumpTimestamp skips what the exclude* options drop and keeps the replies under them.
-        score: ({ comment, options, replies }) => bumpTimestamp({ postTimestamp: comment.timestamp, replies: replies ?? [], keywords, options }),
+        score: ({ comment, options, replies }) => bumpTimestamp({ postTimestamp: comment.timestamp, replies: replies ?? [], keywords, options, bumpLimit }),
         validatePageSortSettings
     };
 };

package/dist/active-page-sort.js.map

@@ -1 +1 @@
-{"version":3,"file":"active-page-sort.js","sourceRoot":"","sources":["../src/active-page-sort.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEtG,iIAAiI;AACjI,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAElC,MAAM,CAAC,MAAM,WAAW,GAAG,0GAA0G,CAAC;AAEtI,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAC/B,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,MAAM,CAAC,MAAM,YAAY,GAA8C;IACrE;QACE,MAAM,EAAE,uBAAuB;QAC/B,KAAK,EAAE,kBAAkB;QACzB,WAAW,EACT,mKAAmK;QACrK,WAAW,EAAE,MAAM;KACpB;CACF,CAAC;AAEF,MAAM,UAAU,GAAG,CAAC,gBAAuC,EAAY,EAAE,CAAC,aAAa,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC;AAE7I;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,EAAE,gBAAgB,EAA+C,EAAQ,EAAE;IAClH,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,EAAE,CAAC,uBAAuB,CAAC,CAAC;IAChE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO;IAC9B,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,6DAA6D,CAAC,CAAC;IACpI,IAAI,QAAQ,CAAC,MAAM,GAAG,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,UAAU,QAAQ,CAAC,MAAM,6BAA6B,YAAY,EAAE,CAAC,CAAC;IACpJ,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,MAAM,GAAG,kBAAkB;YACrC,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,aAAa,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,OAAO,CAAC,MAAM,0BAA0B,kBAAkB,EAAE,CAAC,CAAC;QACtJ,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,2DAA2D,CAAC,CAAC;IACrI,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB,CAAC,EAAE,gBAAgB,EAA2B,EAAgB,EAAE;IACjH,MAAM,QAAQ,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC9C,OAAO;QACL,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,WAAW;QACxB,KAAK,EAAE,OAAO;QACd,cAAc,EAAE,IAAI;QACpB,YAAY;QACZ,cAAc,EAAE,EAAE;QAClB,4GAA4G;QAC5G,8GAA8G;QAC9G,2GAA2G;QAC3G,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QACxI,wBAAwB;KACzB,CAAC;AACJ,CAAC,CAAC;AAEF,qHAAqH;AACrH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,OAAgB,EAAE,OAA2C,EAAW,EAAE,CAChH,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAE9E,eAAe,cAAc,CAAC"}
+{"version":3,"file":"active-page-sort.js","sourceRoot":"","sources":["../src/active-page-sort.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEzI,iIAAiI;AACjI,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAElC,MAAM,CAAC,MAAM,WAAW,GACtB,uIAAuI,CAAC;AAE1I,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAC/B,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,MAAM,CAAC,MAAM,YAAY,GAA8C;IACrE;QACE,MAAM,EAAE,uBAAuB;QAC/B,KAAK,EAAE,kBAAkB;QACzB,WAAW,EACT,mKAAmK;QACrK,WAAW,EAAE,MAAM;KACpB;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,KAAK,EAAE,YAAY;QACnB,WAAW,EACT,+JAA+J;QACjK,WAAW,EAAE,KAAK;KACnB;CACF,CAAC;AAEF,MAAM,UAAU,GAAG,CAAC,gBAAuC,EAAY,EAAE,CAAC,aAAa,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC;AAE7I;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,EAAE,gBAAgB,EAA+C,EAAQ,EAAE;IAClH,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;IAC/D,IAAI,QAAQ,KAAK,SAAS,IAAI,cAAc,CAAC,QAAQ,CAAC,KAAK,SAAS;QAClE,MAAM,IAAI,KAAK,CAAC,GAAG,iBAAiB,qCAAqC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,0BAA0B,CAAC,CAAC;IAC5H,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,EAAE,CAAC,uBAAuB,CAAC,CAAC;IAChE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO;IAC9B,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,6DAA6D,CAAC,CAAC;IACpI,IAAI,QAAQ,CAAC,MAAM,GAAG,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,UAAU,QAAQ,CAAC,MAAM,6BAA6B,YAAY,EAAE,CAAC,CAAC;IACpJ,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,MAAM,GAAG,kBAAkB;YACrC,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,aAAa,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,OAAO,CAAC,MAAM,0BAA0B,kBAAkB,EAAE,CAAC,CAAC;QACtJ,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAuB,2DAA2D,CAAC,CAAC;IACrI,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB,CAAC,EAAE,gBAAgB,EAA2B,EAAgB,EAAE;IACjH,MAAM,QAAQ,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,cAAc,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAChF,OAAO;QACL,QAAQ,EAAE,SAAS;QACnB,WAAW,EAAE,WAAW;QACxB,KAAK,EAAE,OAAO;QACd,cAAc,EAAE,IAAI;QACpB,YAAY;QACZ,cAAc,EAAE,EAAE;QAClB,4GAA4G;QAC5G,8GAA8G;QAC9G,2GAA2G;QAC3G,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QACnJ,wBAAwB;KACzB,CAAC;AACJ,CAAC,CAAC;AAEF,qHAAqH;AACrH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,OAAgB,EAAE,OAA2C,EAAW,EAAE,CAChH,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAE9E,eAAe,cAAc,CAAC"}

package/dist/no-bump.d.ts

@@ -1,8 +1,15 @@
 import type { NoBumpReplyLike } from "./types.js";
 /** The option key under `settings.pages.posts[i].options`. Published as `community.pageSorts.posts.active.publicOptions.noBumpKeywords`. */
 export declare const NO_BUMP_KEYWORDS_OPTION = "noBumpKeywords";
+/** The option key for the bump limit. Published as `community.pageSorts.posts.active.publicOptions.bumpLimit`. */
+export declare const BUMP_LIMIT_OPTION = "bumpLimit";
 /** Comma-separated list to keywords: trimmed, empty entries dropped, duplicates kept out. */
 export declare const splitKeywords: (raw: string | undefined) => string[];
+/**
+ * The bump limit an option value holds: a positive integer, surrounding whitespace trimmed. `undefined` for an
+ * unset option (no limit) and for anything else, which `validatePageSortSettings` rejects on the community.
+ */
+export declare const parseBumpLimit: (raw: string | undefined) => number | undefined;
 /**
  * Whether a reply is a no-bump reply: its content has a whole line equal to one of the keywords. Exact and
  * case-sensitive, so `sage` in prose ("sage is overused") still bumps, while a content of `sage`, or a
@@ -32,13 +39,15 @@ export declare const isCountedReply: (reply: NoBumpReplyLike, options: Readonly<
 /**
  * A thread's bump time: the newest of the post's own timestamp and the timestamps of its counted replies (see
  * `isCountedReply`) that are not no-bump replies. Each reply is judged on its own: a normal reply under a saged
- * reply or a tombstone bumps. This is exactly what `score` returns, exposed so a UI can show "last bump" without
- * the page sort machinery. Pass the replies as pkc-js or a reply-page walk gives them, tombstones included, and
- * the published `publicOptions` as `options`.
+ * reply or a tombstone bumps. With a `bumpLimit`, only the first `bumpLimit` counted replies by `(timestamp, cid)`
+ * can bump, saged ones included in the count. This is exactly what `score` returns, exposed so a UI can show
+ * "last bump" without the page sort machinery. Pass the replies as pkc-js or a reply-page walk gives them,
+ * tombstones included, the published `publicOptions` as `options`, and `parseBumpLimit` of its `bumpLimit`.
  */
-export declare const bumpTimestamp: ({ postTimestamp, replies, keywords, options }: {
+export declare const bumpTimestamp: ({ postTimestamp, replies, keywords, options, bumpLimit }: {
     postTimestamp: number;
     replies: readonly NoBumpReplyLike[];
     keywords: readonly string[];
     options?: Readonly<Record<string, string>>;
+    bumpLimit?: number | undefined;
 }) => number;

package/dist/no-bump.js

@@ -3,6 +3,8 @@
 // README's description of the match: both are the contract a board's users rely on.
 /** The option key under `settings.pages.posts[i].options`. Published as `community.pageSorts.posts.active.publicOptions.noBumpKeywords`. */
 export const NO_BUMP_KEYWORDS_OPTION = "noBumpKeywords";
+/** The option key for the bump limit. Published as `community.pageSorts.posts.active.publicOptions.bumpLimit`. */
+export const BUMP_LIMIT_OPTION = "bumpLimit";
 /** Comma-separated list to keywords: trimmed, empty entries dropped, duplicates kept out. */
 export const splitKeywords = (raw) => {
     const keywords = [];
@@ -13,6 +15,17 @@ export const splitKeywords = (raw) => {
     }
     return keywords;
 };
+/**
+ * The bump limit an option value holds: a positive integer, surrounding whitespace trimmed. `undefined` for an
+ * unset option (no limit) and for anything else, which `validatePageSortSettings` rejects on the community.
+ */
+export const parseBumpLimit = (raw) => {
+    const trimmed = raw?.trim();
+    if (!trimmed || !/^[1-9][0-9]*$/.test(trimmed))
+        return undefined;
+    const limit = Number(trimmed);
+    return Number.isSafeInteger(limit) ? limit : undefined;
+};
 /**
  * Whether a reply is a no-bump reply: its content has a whole line equal to one of the keywords. Exact and
  * case-sensitive, so `sage` in prose ("sage is overused") still bumps, while a content of `sage`, or a
@@ -50,19 +63,26 @@ export const isCountedReply = (reply, options) => !exclusionsOf(options).some((d
 /**
  * A thread's bump time: the newest of the post's own timestamp and the timestamps of its counted replies (see
  * `isCountedReply`) that are not no-bump replies. Each reply is judged on its own: a normal reply under a saged
- * reply or a tombstone bumps. This is exactly what `score` returns, exposed so a UI can show "last bump" without
- * the page sort machinery. Pass the replies as pkc-js or a reply-page walk gives them, tombstones included, and
- * the published `publicOptions` as `options`.
+ * reply or a tombstone bumps. With a `bumpLimit`, only the first `bumpLimit` counted replies by `(timestamp, cid)`
+ * can bump, saged ones included in the count. This is exactly what `score` returns, exposed so a UI can show
+ * "last bump" without the page sort machinery. Pass the replies as pkc-js or a reply-page walk gives them,
+ * tombstones included, the published `publicOptions` as `options`, and `parseBumpLimit` of its `bumpLimit`.
  */
-export const bumpTimestamp = ({ postTimestamp, replies, keywords, options = {} }) => {
+export const bumpTimestamp = ({ postTimestamp, replies, keywords, options = {}, bumpLimit }) => {
     const exclusions = exclusionsOf(options);
+    let counted = replies.filter((reply) => !exclusions.some((drops) => drops(reply.commentUpdate)));
+    if (bumpLimit !== undefined && counted.length > bumpLimit)
+        counted = [...counted].sort(byTimestampThenCid).slice(0, bumpLimit);
     let bump = postTimestamp;
-    for (const reply of replies) {
-        if (exclusions.some((drops) => drops(reply.commentUpdate)) || isNoBumpContent(reply.comment.content, keywords))
+    for (const reply of counted) {
+        if (isNoBumpContent(reply.comment.content, keywords))
             continue;
         if (reply.comment.timestamp > bump)
             bump = reply.comment.timestamp;
     }
     return bump;
 };
+// The order "the first bumpLimit replies" is taken in. The CID breaks a tie in the same second, compared as a
+// plain string so the community and every client agree.
+const byTimestampThenCid = (a, b) => a.comment.timestamp - b.comment.timestamp || (a.commentUpdate.cid < b.commentUpdate.cid ? -1 : a.commentUpdate.cid > b.commentUpdate.cid ? 1 : 0);
 //# sourceMappingURL=no-bump.js.map

package/dist/no-bump.js.map

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

package/dist/types.d.ts

@@ -12,6 +12,7 @@ export interface NoBumpReplyLike {
         content?: string | undefined;
     };
     commentUpdate: {
+        cid: string;
         removed?: boolean | undefined;
         approved?: boolean | undefined;
         pendingApproval?: boolean | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pkcprotocol/active-page-sort",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Bump-order (active) page sort for pkc-js communities where replies carrying a configured keyword, such as sage, do not bump the thread",
   "type": "module",
   "main": "./dist/index.js",