@btst/stack 2.11.8 → 2.12.0

package/dist/packages/stack/src/plugins/comments/api/query-key-defs.cjs

@@ -27,6 +27,7 @@ function commentsThreadDiscriminator(params) {
     parentId: params?.parentId,
     status: params?.status,
     currentUserId: params?.currentUserId,
+    sort: params?.sort,
     limit: params?.limit ?? 20
   };
 }
@@ -48,7 +49,7 @@ const COMMENTS_QUERY_KEYS = {
   commentCount: (params) => ["comments", "count", commentCountDiscriminator(params)],
   /**
    * Key for the infinite thread query (top-level comments, load-more).
-   * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+   * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, sort, limit }]
    * Offset is excluded — it is driven by `pageParam`, not baked into the key.
    */
   commentsThread: (params) => ["commentsThread", "list", commentsThreadDiscriminator(params)]

package/dist/packages/stack/src/plugins/comments/api/query-key-defs.mjs

@@ -25,6 +25,7 @@ function commentsThreadDiscriminator(params) {
     parentId: params?.parentId,
     status: params?.status,
     currentUserId: params?.currentUserId,
+    sort: params?.sort,
     limit: params?.limit ?? 20
   };
 }
@@ -46,7 +47,7 @@ const COMMENTS_QUERY_KEYS = {
   commentCount: (params) => ["comments", "count", commentCountDiscriminator(params)],
   /**
    * Key for the infinite thread query (top-level comments, load-more).
-   * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+   * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, sort, limit }]
    * Offset is excluded — it is driven by `pageParam`, not baked into the key.
    */
   commentsThread: (params) => ["commentsThread", "list", commentsThreadDiscriminator(params)]

package/dist/packages/stack/src/plugins/comments/client/components/comment-thread.cjs

@@ -195,12 +195,14 @@ function CommentThreadInner({
   localization: localizationProp,
   pageSize: pageSizeProp,
   allowPosting: allowPostingProp,
-  allowEditing: allowEditingProp
+  allowEditing: allowEditingProp,
+  sort: sortProp
 }) {
   const overrides = context.usePluginOverrides("comments", {});
   const pageSize = pageSizeProp ?? overrides.defaultCommentPageSize ?? DEFAULT_PAGE_SIZE;
   const allowPosting = allowPostingProp ?? overrides.allowPosting ?? true;
   const allowEditing = allowEditingProp ?? overrides.allowEditing ?? true;
+  const sort = sortProp ?? overrides.defaultCommentSort ?? "desc";
   const loc = { ...index.COMMENTS_LOCALIZATION, ...localizationProp };
   const [replyingTo, setReplyingTo] = React.useState(null);
   const [expandedReplies, setExpandedReplies] = React.useState(
@@ -222,6 +224,7 @@ function CommentThreadInner({
     status: "approved",
     parentId: null,
     currentUserId,
+    sort,
     pageSize
   });
   const postMutation = useComments.usePostComment(config, {
@@ -229,7 +232,8 @@ function CommentThreadInner({
     resourceType,
     currentUserId,
     infiniteKey: threadQueryKey,
-    pageSize
+    pageSize,
+    sort
   });
   const handlePost = async (body) => {
     if (!currentUserId) return;

package/dist/packages/stack/src/plugins/comments/client/components/comment-thread.mjs

@@ -193,12 +193,14 @@ function CommentThreadInner({
   localization: localizationProp,
   pageSize: pageSizeProp,
   allowPosting: allowPostingProp,
-  allowEditing: allowEditingProp
+  allowEditing: allowEditingProp,
+  sort: sortProp
 }) {
   const overrides = usePluginOverrides("comments", {});
   const pageSize = pageSizeProp ?? overrides.defaultCommentPageSize ?? DEFAULT_PAGE_SIZE;
   const allowPosting = allowPostingProp ?? overrides.allowPosting ?? true;
   const allowEditing = allowEditingProp ?? overrides.allowEditing ?? true;
+  const sort = sortProp ?? overrides.defaultCommentSort ?? "desc";
   const loc = { ...COMMENTS_LOCALIZATION, ...localizationProp };
   const [replyingTo, setReplyingTo] = useState(null);
   const [expandedReplies, setExpandedReplies] = useState(
@@ -220,6 +222,7 @@ function CommentThreadInner({
     status: "approved",
     parentId: null,
     currentUserId,
+    sort,
     pageSize
   });
   const postMutation = usePostComment(config, {
@@ -227,7 +230,8 @@ function CommentThreadInner({
     resourceType,
     currentUserId,
     infiniteKey: threadQueryKey,
-    pageSize
+    pageSize,
+    sort
   });
   const handlePost = async (body) => {
     if (!currentUserId) return;

package/dist/packages/stack/src/plugins/comments/client/hooks/use-comments.cjs

@@ -84,6 +84,7 @@ function useInfiniteComments(config, params, options) {
     parentId: params.parentId ?? null,
     status: params.status,
     currentUserId: params.currentUserId,
+    sort: params.sort,
     limit: pageSize
   });
   const query = reactQuery.useInfiniteQuery({
@@ -183,6 +184,7 @@ function usePostComment(config, params) {
       };
       if (isInfinitePost(input.parentId)) {
         const previous2 = queryClient.getQueryData(listKey);
+        const isDesc = params.sort === "desc";
         queryClient.setQueryData(
           listKey,
           (old) => {
@@ -199,15 +201,15 @@ function usePostComment(config, params) {
                 pageParams: [0]
               };
             }
-            const lastIdx = old.pages.length - 1;
+            const targetIdx = isDesc ? 0 : old.pages.length - 1;
             return {
               ...old,
               // Increment `total` on every page so the header count (which reads
               // pages[0].total) stays in sync even after multiple pages are loaded.
               pages: old.pages.map(
-                (page, idx) => idx === lastIdx ? {
+                (page, idx) => idx === targetIdx ? {
                   ...page,
-                  items: [...page.items, optimistic],
+                  items: isDesc ? [optimistic, ...page.items] : [...page.items, optimistic],
                   total: page.total + 1
                 } : { ...page, total: page.total + 1 }
               )

package/dist/packages/stack/src/plugins/comments/client/hooks/use-comments.mjs

@@ -82,6 +82,7 @@ function useInfiniteComments(config, params, options) {
     parentId: params.parentId ?? null,
     status: params.status,
     currentUserId: params.currentUserId,
+    sort: params.sort,
     limit: pageSize
   });
   const query = useInfiniteQuery({
@@ -181,6 +182,7 @@ function usePostComment(config, params) {
       };
       if (isInfinitePost(input.parentId)) {
         const previous2 = queryClient.getQueryData(listKey);
+        const isDesc = params.sort === "desc";
         queryClient.setQueryData(
           listKey,
           (old) => {
@@ -197,15 +199,15 @@ function usePostComment(config, params) {
                 pageParams: [0]
               };
             }
-            const lastIdx = old.pages.length - 1;
+            const targetIdx = isDesc ? 0 : old.pages.length - 1;
             return {
               ...old,
               // Increment `total` on every page so the header count (which reads
               // pages[0].total) stays in sync even after multiple pages are loaded.
               pages: old.pages.map(
-                (page, idx) => idx === lastIdx ? {
+                (page, idx) => idx === targetIdx ? {
                   ...page,
-                  items: [...page.items, optimistic],
+                  items: isDesc ? [optimistic, ...page.items] : [...page.items, optimistic],
                   total: page.total + 1
                 } : { ...page, total: page.total + 1 }
               )

package/dist/plugins/comments/api/index.d.cts

@@ -1,8 +1,8 @@
-import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CmHRdhl8.cjs';
-export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CmHRdhl8.cjs';
+import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CCncwK6g.cjs';
+export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CCncwK6g.cjs';
 import { DBAdapter } from '@btst/db';
-import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C-b3Sn8j.cjs';
-export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C-b3Sn8j.cjs';
+import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C7KNNiJm.cjs';
+export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C7KNNiJm.cjs';
 import { z } from 'zod';
 import '@btst/stack/plugins/api';
 import 'better-call';

package/dist/plugins/comments/api/index.d.mts

@@ -1,8 +1,8 @@
-import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.Dcz6636A.mjs';
-export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.Dcz6636A.mjs';
+import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CO1g47IS.mjs';
+export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CO1g47IS.mjs';
 import { DBAdapter } from '@btst/db';
-import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C-b3Sn8j.mjs';
-export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C-b3Sn8j.mjs';
+import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C7KNNiJm.mjs';
+export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C7KNNiJm.mjs';
 import { z } from 'zod';
 import '@btst/stack/plugins/api';
 import 'better-call';

package/dist/plugins/comments/api/index.d.ts

@@ -1,8 +1,8 @@
-import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CJE9sAjV.js';
-export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CJE9sAjV.js';
+import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.Bq3kiUaM.js';
+export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.Bq3kiUaM.js';
 import { DBAdapter } from '@btst/db';
-import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C-b3Sn8j.js';
-export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C-b3Sn8j.js';
+import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C7KNNiJm.js';
+export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C7KNNiJm.js';
 import { z } from 'zod';
 import '@btst/stack/plugins/api';
 import 'better-call';

package/dist/plugins/comments/client/components/index.d.cts

@@ -59,6 +59,17 @@ interface CommentThreadProps {
      * Defaults to true.
      */
     allowEditing?: boolean;
+    /**
+     * Sort direction for top-level comments by `createdAt`.
+     * - `"desc"` (default): newest first.
+     * - `"asc"`: oldest first.
+     *
+     * Replies inside each thread always render chronologically (oldest → newest)
+     * and are unaffected by this prop.
+     *
+     * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+     */
+    sort?: "asc" | "desc";
 }
 declare function CommentThread(props: CommentThreadProps): react_jsx_runtime.JSX.Element;
 

package/dist/plugins/comments/client/components/index.d.mts

@@ -59,6 +59,17 @@ interface CommentThreadProps {
      * Defaults to true.
      */
     allowEditing?: boolean;
+    /**
+     * Sort direction for top-level comments by `createdAt`.
+     * - `"desc"` (default): newest first.
+     * - `"asc"`: oldest first.
+     *
+     * Replies inside each thread always render chronologically (oldest → newest)
+     * and are unaffected by this prop.
+     *
+     * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+     */
+    sort?: "asc" | "desc";
 }
 declare function CommentThread(props: CommentThreadProps): react_jsx_runtime.JSX.Element;
 

package/dist/plugins/comments/client/components/index.d.ts

@@ -59,6 +59,17 @@ interface CommentThreadProps {
      * Defaults to true.
      */
     allowEditing?: boolean;
+    /**
+     * Sort direction for top-level comments by `createdAt`.
+     * - `"desc"` (default): newest first.
+     * - `"asc"`: oldest first.
+     *
+     * Replies inside each thread always render chronologically (oldest → newest)
+     * and are unaffected by this prop.
+     *
+     * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+     */
+    sort?: "asc" | "desc";
 }
 declare function CommentThread(props: CommentThreadProps): react_jsx_runtime.JSX.Element;
 

package/dist/plugins/comments/client/hooks/index.d.cts

@@ -1,4 +1,4 @@
-import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.cjs';
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C7KNNiJm.cjs';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { InfiniteData } from '@tanstack/react-query';
 
@@ -81,6 +81,11 @@ declare function useInfiniteComments(config: CommentsClientConfig, params: {
     parentId?: string | null;
     status?: "pending" | "approved" | "spam";
     currentUserId?: string;
+    /**
+     * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+     * the server-side default. Pass `"desc"` for newest-first threads.
+     */
+    sort?: "asc" | "desc";
     pageSize?: number;
 }, options?: {
     enabled?: boolean;
@@ -129,6 +134,17 @@ declare function usePostComment(config: CommentsClientConfig, params: {
      * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
      */
     pageSize?: number;
+    /**
+     * Sort direction of the surrounding infinite thread.
+     * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+     *   item is appended to `pages[last].items`.
+     * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+     *   is prepended to `pages[0].items`.
+     *
+     * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+     * item appears in the same position the server will place it.
+     */
+    sort?: "asc" | "desc";
 }): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
     body: string;
     parentId?: string | null;

package/dist/plugins/comments/client/hooks/index.d.mts

@@ -1,4 +1,4 @@
-import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.mjs';
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C7KNNiJm.mjs';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { InfiniteData } from '@tanstack/react-query';
 
@@ -81,6 +81,11 @@ declare function useInfiniteComments(config: CommentsClientConfig, params: {
     parentId?: string | null;
     status?: "pending" | "approved" | "spam";
     currentUserId?: string;
+    /**
+     * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+     * the server-side default. Pass `"desc"` for newest-first threads.
+     */
+    sort?: "asc" | "desc";
     pageSize?: number;
 }, options?: {
     enabled?: boolean;
@@ -129,6 +134,17 @@ declare function usePostComment(config: CommentsClientConfig, params: {
      * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
      */
     pageSize?: number;
+    /**
+     * Sort direction of the surrounding infinite thread.
+     * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+     *   item is appended to `pages[last].items`.
+     * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+     *   is prepended to `pages[0].items`.
+     *
+     * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+     * item appears in the same position the server will place it.
+     */
+    sort?: "asc" | "desc";
 }): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
     body: string;
     parentId?: string | null;

package/dist/plugins/comments/client/hooks/index.d.ts

@@ -1,4 +1,4 @@
-import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.js';
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C7KNNiJm.js';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { InfiniteData } from '@tanstack/react-query';
 
@@ -81,6 +81,11 @@ declare function useInfiniteComments(config: CommentsClientConfig, params: {
     parentId?: string | null;
     status?: "pending" | "approved" | "spam";
     currentUserId?: string;
+    /**
+     * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+     * the server-side default. Pass `"desc"` for newest-first threads.
+     */
+    sort?: "asc" | "desc";
     pageSize?: number;
 }, options?: {
     enabled?: boolean;
@@ -129,6 +134,17 @@ declare function usePostComment(config: CommentsClientConfig, params: {
      * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
      */
     pageSize?: number;
+    /**
+     * Sort direction of the surrounding infinite thread.
+     * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+     *   item is appended to `pages[last].items`.
+     * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+     *   is prepended to `pages[0].items`.
+     *
+     * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+     * item appears in the same position the server will place it.
+     */
+    sort?: "asc" | "desc";
 }): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
     body: string;
     parentId?: string | null;

package/dist/plugins/comments/client/index.d.cts

@@ -197,6 +197,15 @@ interface CommentsPluginOverrides {
      * Defaults to 100 when not set.
      */
     defaultCommentPageSize?: number;
+    /**
+     * Default sort direction (by `createdAt`) for top-level comments in
+     * `CommentThread`.
+     * - `"desc"` (default): newest comments first.
+     * - `"asc"`: oldest comments first.
+     *
+     * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+     */
+    defaultCommentSort?: "asc" | "desc";
     /**
      * When false, the comment form and reply buttons are hidden in all
      * `CommentThread` instances. Users can still read existing comments.

package/dist/plugins/comments/client/index.d.mts

@@ -197,6 +197,15 @@ interface CommentsPluginOverrides {
      * Defaults to 100 when not set.
      */
     defaultCommentPageSize?: number;
+    /**
+     * Default sort direction (by `createdAt`) for top-level comments in
+     * `CommentThread`.
+     * - `"desc"` (default): newest comments first.
+     * - `"asc"`: oldest comments first.
+     *
+     * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+     */
+    defaultCommentSort?: "asc" | "desc";
     /**
      * When false, the comment form and reply buttons are hidden in all
      * `CommentThread` instances. Users can still read existing comments.

package/dist/plugins/comments/client/index.d.ts

@@ -197,6 +197,15 @@ interface CommentsPluginOverrides {
      * Defaults to 100 when not set.
      */
     defaultCommentPageSize?: number;
+    /**
+     * Default sort direction (by `createdAt`) for top-level comments in
+     * `CommentThread`.
+     * - `"desc"` (default): newest comments first.
+     * - `"asc"`: oldest comments first.
+     *
+     * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+     */
+    defaultCommentSort?: "asc" | "desc";
     /**
      * When false, the comment form and reply buttons are hidden in all
      * `CommentThread` instances. Users can still read existing comments.

package/dist/plugins/comments/query-keys.cjs

@@ -90,6 +90,7 @@ function createCommentsThreadQueries(client, headers) {
             // The server resolves the caller's identity server-side via the
             // resolveCurrentUserId hook. It is still included in the queryKey
             // above for client-side cache segregation.
+            sort: params?.sort,
             limit: params?.limit ?? 20,
             offset: pageParam ?? 0
           },

package/dist/plugins/comments/query-keys.d.cts

@@ -1,7 +1,7 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { b as CommentsListDiscriminator, C as CommentListResult, c as CommentCountDiscriminator, a as CommentsThreadDiscriminator } from '../../shared/stack.C-b3Sn8j.cjs';
+import { b as CommentsListDiscriminator, C as CommentListResult, c as CommentCountDiscriminator, a as CommentsThreadDiscriminator } from '../../shared/stack.C7KNNiJm.cjs';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { C as CommentsApiRouter } from '../../shared/stack.CmHRdhl8.cjs';
+import { C as CommentsApiRouter } from '../../shared/stack.CCncwK6g.cjs';
 import '@btst/stack/plugins/api';
 import 'better-call';
 import 'zod';
@@ -56,6 +56,7 @@ declare function createCommentsQueryKeys(client: ReturnType<typeof createApiClie
             parentId?: string | null;
             status?: "pending" | "approved" | "spam";
             currentUserId?: string;
+            sort?: "asc" | "desc";
             limit?: number;
         } | undefined) => Omit<Omit<{
             queryKey: readonly ["commentsThread", "list", CommentsThreadDiscriminator];

package/dist/plugins/comments/query-keys.d.mts

@@ -1,7 +1,7 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { b as CommentsListDiscriminator, C as CommentListResult, c as CommentCountDiscriminator, a as CommentsThreadDiscriminator } from '../../shared/stack.C-b3Sn8j.mjs';
+import { b as CommentsListDiscriminator, C as CommentListResult, c as CommentCountDiscriminator, a as CommentsThreadDiscriminator } from '../../shared/stack.C7KNNiJm.mjs';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { C as CommentsApiRouter } from '../../shared/stack.Dcz6636A.mjs';
+import { C as CommentsApiRouter } from '../../shared/stack.CO1g47IS.mjs';
 import '@btst/stack/plugins/api';
 import 'better-call';
 import 'zod';
@@ -56,6 +56,7 @@ declare function createCommentsQueryKeys(client: ReturnType<typeof createApiClie
             parentId?: string | null;
             status?: "pending" | "approved" | "spam";
             currentUserId?: string;
+            sort?: "asc" | "desc";
             limit?: number;
         } | undefined) => Omit<Omit<{
             queryKey: readonly ["commentsThread", "list", CommentsThreadDiscriminator];

package/dist/plugins/comments/query-keys.d.ts

@@ -1,7 +1,7 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { b as CommentsListDiscriminator, C as CommentListResult, c as CommentCountDiscriminator, a as CommentsThreadDiscriminator } from '../../shared/stack.C-b3Sn8j.js';
+import { b as CommentsListDiscriminator, C as CommentListResult, c as CommentCountDiscriminator, a as CommentsThreadDiscriminator } from '../../shared/stack.C7KNNiJm.js';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { C as CommentsApiRouter } from '../../shared/stack.CJE9sAjV.js';
+import { C as CommentsApiRouter } from '../../shared/stack.Bq3kiUaM.js';
 import '@btst/stack/plugins/api';
 import 'better-call';
 import 'zod';
@@ -56,6 +56,7 @@ declare function createCommentsQueryKeys(client: ReturnType<typeof createApiClie
             parentId?: string | null;
             status?: "pending" | "approved" | "spam";
             currentUserId?: string;
+            sort?: "asc" | "desc";
             limit?: number;
         } | undefined) => Omit<Omit<{
             queryKey: readonly ["commentsThread", "list", CommentsThreadDiscriminator];

package/dist/plugins/comments/query-keys.mjs

@@ -88,6 +88,7 @@ function createCommentsThreadQueries(client, headers) {
             // The server resolves the caller's identity server-side via the
             // resolveCurrentUserId hook. It is still included in the queryKey
             // above for client-side cache segregation.
+            sort: params?.sort,
             limit: params?.limit ?? 20,
             offset: pageParam ?? 0
           },

package/dist/shared/{stack.CJE9sAjV.d.ts → stack.Bq3kiUaM.d.ts}

@@ -1,5 +1,5 @@
 import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
-import { d as Comment, S as SerializedComment, C as CommentListResult } from './stack.C-b3Sn8j.js';
+import { d as Comment, S as SerializedComment, C as CommentListResult } from './stack.C7KNNiJm.js';
 import * as better_call from 'better-call';
 import { z } from 'zod';
 

package/dist/shared/{stack.C-b3Sn8j.d.cts → stack.C7KNNiJm.d.cts}

@@ -90,6 +90,7 @@ interface CommentsThreadDiscriminator {
     parentId: string | null | undefined;
     status: string | undefined;
     currentUserId: string | undefined;
+    sort: string | undefined;
     limit: number;
 }
 /** Full query key builders — use with queryClient.setQueryData() */
@@ -125,7 +126,7 @@ declare const COMMENTS_QUERY_KEYS: {
     }) => readonly ["comments", "count", CommentCountDiscriminator];
     /**
      * Key for the infinite thread query (top-level comments, load-more).
-     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, sort, limit }]
      * Offset is excluded — it is driven by `pageParam`, not baked into the key.
      */
     commentsThread: (params?: {
@@ -134,6 +135,7 @@ declare const COMMENTS_QUERY_KEYS: {
         parentId?: string | null;
         status?: string;
         currentUserId?: string;
+        sort?: string;
         limit?: number;
     }) => readonly ["commentsThread", "list", CommentsThreadDiscriminator];
 };

package/dist/shared/{stack.C-b3Sn8j.d.mts → stack.C7KNNiJm.d.mts}

@@ -90,6 +90,7 @@ interface CommentsThreadDiscriminator {
     parentId: string | null | undefined;
     status: string | undefined;
     currentUserId: string | undefined;
+    sort: string | undefined;
     limit: number;
 }
 /** Full query key builders — use with queryClient.setQueryData() */
@@ -125,7 +126,7 @@ declare const COMMENTS_QUERY_KEYS: {
     }) => readonly ["comments", "count", CommentCountDiscriminator];
     /**
      * Key for the infinite thread query (top-level comments, load-more).
-     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, sort, limit }]
      * Offset is excluded — it is driven by `pageParam`, not baked into the key.
      */
     commentsThread: (params?: {
@@ -134,6 +135,7 @@ declare const COMMENTS_QUERY_KEYS: {
         parentId?: string | null;
         status?: string;
         currentUserId?: string;
+        sort?: string;
         limit?: number;
     }) => readonly ["commentsThread", "list", CommentsThreadDiscriminator];
 };

package/dist/shared/{stack.C-b3Sn8j.d.ts → stack.C7KNNiJm.d.ts}

@@ -90,6 +90,7 @@ interface CommentsThreadDiscriminator {
     parentId: string | null | undefined;
     status: string | undefined;
     currentUserId: string | undefined;
+    sort: string | undefined;
     limit: number;
 }
 /** Full query key builders — use with queryClient.setQueryData() */
@@ -125,7 +126,7 @@ declare const COMMENTS_QUERY_KEYS: {
     }) => readonly ["comments", "count", CommentCountDiscriminator];
     /**
      * Key for the infinite thread query (top-level comments, load-more).
-     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, sort, limit }]
      * Offset is excluded — it is driven by `pageParam`, not baked into the key.
      */
     commentsThread: (params?: {
@@ -134,6 +135,7 @@ declare const COMMENTS_QUERY_KEYS: {
         parentId?: string | null;
         status?: string;
         currentUserId?: string;
+        sort?: string;
         limit?: number;
     }) => readonly ["commentsThread", "list", CommentsThreadDiscriminator];
 };

package/dist/shared/{stack.CmHRdhl8.d.cts → stack.CCncwK6g.d.cts}

@@ -1,5 +1,5 @@
 import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
-import { d as Comment, S as SerializedComment, C as CommentListResult } from './stack.C-b3Sn8j.cjs';
+import { d as Comment, S as SerializedComment, C as CommentListResult } from './stack.C7KNNiJm.cjs';
 import * as better_call from 'better-call';
 import { z } from 'zod';
 

package/dist/shared/{stack.Dcz6636A.d.mts → stack.CO1g47IS.d.mts}

@@ -1,5 +1,5 @@
 import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
-import { d as Comment, S as SerializedComment, C as CommentListResult } from './stack.C-b3Sn8j.mjs';
+import { d as Comment, S as SerializedComment, C as CommentListResult } from './stack.C7KNNiJm.mjs';
 import * as better_call from 'better-call';
 import { z } from 'zod';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.11.8",
+  "version": "2.12.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",

package/src/plugins/comments/api/query-key-defs.ts

@@ -71,6 +71,7 @@ export interface CommentsThreadDiscriminator {
 	parentId: string | null | undefined;
 	status: string | undefined;
 	currentUserId: string | undefined;
+	sort: string | undefined;
 	limit: number;
 }
 
@@ -80,6 +81,7 @@ export function commentsThreadDiscriminator(params?: {
 	parentId?: string | null;
 	status?: string;
 	currentUserId?: string;
+	sort?: string;
 	limit?: number;
 }): CommentsThreadDiscriminator {
 	return {
@@ -88,6 +90,7 @@ export function commentsThreadDiscriminator(params?: {
 		parentId: params?.parentId,
 		status: params?.status,
 		currentUserId: params?.currentUserId,
+		sort: params?.sort,
 		limit: params?.limit ?? 20,
 	};
 }
@@ -128,7 +131,7 @@ export const COMMENTS_QUERY_KEYS = {
 
 	/**
 	 * Key for the infinite thread query (top-level comments, load-more).
-	 * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+	 * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, sort, limit }]
 	 * Offset is excluded — it is driven by `pageParam`, not baked into the key.
 	 */
 	commentsThread: (params?: {
@@ -137,6 +140,7 @@ export const COMMENTS_QUERY_KEYS = {
 		parentId?: string | null;
 		status?: string;
 		currentUserId?: string;
+		sort?: string;
 		limit?: number;
 	}) =>
 		["commentsThread", "list", commentsThreadDiscriminator(params)] as const,

package/src/plugins/comments/client/components/comment-thread.tsx

@@ -98,6 +98,17 @@ export interface CommentThreadProps {
 	 * Defaults to true.
 	 */
 	allowEditing?: boolean;
+	/**
+	 * Sort direction for top-level comments by `createdAt`.
+	 * - `"desc"` (default): newest first.
+	 * - `"asc"`: oldest first.
+	 *
+	 * Replies inside each thread always render chronologically (oldest → newest)
+	 * and are unaffected by this prop.
+	 *
+	 * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+	 */
+	sort?: "asc" | "desc";
 }
 
 const DEFAULT_RENDERER: ComponentType<CommentRendererProps> = ({ body }) => (
@@ -325,6 +336,7 @@ function CommentThreadInner({
 	pageSize: pageSizeProp,
 	allowPosting: allowPostingProp,
 	allowEditing: allowEditingProp,
+	sort: sortProp,
 }: CommentThreadProps) {
 	const overrides = usePluginOverrides<
 		CommentsPluginOverrides,
@@ -334,6 +346,7 @@ function CommentThreadInner({
 		pageSizeProp ?? overrides.defaultCommentPageSize ?? DEFAULT_PAGE_SIZE;
 	const allowPosting = allowPostingProp ?? overrides.allowPosting ?? true;
 	const allowEditing = allowEditingProp ?? overrides.allowEditing ?? true;
+	const sort = sortProp ?? overrides.defaultCommentSort ?? "desc";
 	const loc = { ...COMMENTS_LOCALIZATION, ...localizationProp };
 	const [replyingTo, setReplyingTo] = useState<string | null>(null);
 	const [expandedReplies, setExpandedReplies] = useState<Set<string>>(
@@ -357,6 +370,7 @@ function CommentThreadInner({
 		status: "approved",
 		parentId: null,
 		currentUserId,
+		sort,
 		pageSize,
 	});
 
@@ -366,6 +380,7 @@ function CommentThreadInner({
 		currentUserId,
 		infiniteKey: threadQueryKey,
 		pageSize,
+		sort,
 	});
 
 	const handlePost = async (body: string) => {

package/src/plugins/comments/client/hooks/use-comments.tsx

@@ -164,6 +164,11 @@ export function useInfiniteComments(
 		parentId?: string | null;
 		status?: "pending" | "approved" | "spam";
 		currentUserId?: string;
+		/**
+		 * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+		 * the server-side default. Pass `"desc"` for newest-first threads.
+		 */
+		sort?: "asc" | "desc";
 		pageSize?: number;
 	},
 	options?: { enabled?: boolean },
@@ -178,6 +183,7 @@ export function useInfiniteComments(
 		parentId: params.parentId ?? null,
 		status: params.status,
 		currentUserId: params.currentUserId,
+		sort: params.sort,
 		limit: pageSize,
 	});
 
@@ -266,6 +272,17 @@ export function usePostComment(
 		 * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
 		 */
 		pageSize?: number;
+		/**
+		 * Sort direction of the surrounding infinite thread.
+		 * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+		 *   item is appended to `pages[last].items`.
+		 * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+		 *   is prepended to `pages[0].items`.
+		 *
+		 * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+		 * item appears in the same position the server will place it.
+		 */
+		sort?: "asc" | "desc";
 	},
 ) {
 	const queryClient = useQueryClient();
@@ -350,6 +367,7 @@ export function usePostComment(
 				const previous =
 					queryClient.getQueryData<InfiniteData<CommentListResult>>(listKey);
 
+				const isDesc = params.sort === "desc";
 				queryClient.setQueryData<InfiniteData<CommentListResult>>(
 					listKey,
 					(old) => {
@@ -366,16 +384,21 @@ export function usePostComment(
 								pageParams: [0],
 							};
 						}
-						const lastIdx = old.pages.length - 1;
+						// For asc (oldest-first) threads the new comment lives at the end →
+						// append to the last page. For desc (newest-first) threads it lives
+						// at the top → prepend to the first page.
+						const targetIdx = isDesc ? 0 : old.pages.length - 1;
 						return {
 							...old,
 							// Increment `total` on every page so the header count (which reads
 							// pages[0].total) stays in sync even after multiple pages are loaded.
 							pages: old.pages.map((page, idx) =>
-								idx === lastIdx
+								idx === targetIdx
 									? {
 											...page,
-											items: [...page.items, optimistic],
+											items: isDesc
+												? [optimistic, ...page.items]
+												: [...page.items, optimistic],
 											total: page.total + 1,
 										}
 									: { ...page, total: page.total + 1 },

package/src/plugins/comments/client/overrides.ts

@@ -75,6 +75,16 @@ export interface CommentsPluginOverrides {
 	 */
 	defaultCommentPageSize?: number;
 
+	/**
+	 * Default sort direction (by `createdAt`) for top-level comments in
+	 * `CommentThread`.
+	 * - `"desc"` (default): newest comments first.
+	 * - `"asc"`: oldest comments first.
+	 *
+	 * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+	 */
+	defaultCommentSort?: "asc" | "desc";
+
 	/**
 	 * When false, the comment form and reply buttons are hidden in all
 	 * `CommentThread` instances. Users can still read existing comments.

package/src/plugins/comments/query-keys.ts

@@ -142,6 +142,7 @@ function createCommentsThreadQueries(
 			parentId?: string | null;
 			status?: "pending" | "approved" | "spam";
 			currentUserId?: string;
+			sort?: "asc" | "desc";
 			limit?: number;
 		}) => ({
 			// Offset is excluded from the key — it is driven by pageParam.
@@ -162,6 +163,7 @@ function createCommentsThreadQueries(
 						// The server resolves the caller's identity server-side via the
 						// resolveCurrentUserId hook. It is still included in the queryKey
 						// above for client-side cache segregation.
+						sort: params?.sort,
 						limit: params?.limit ?? 20,
 						offset: pageParam ?? 0,
 					},