@jant/core 0.3.39 → 1.0.0

package/src/services/collection.ts

@@ -2,7 +2,8 @@
  * Collection Service (v2)
  *
  * Manages collections. Posts belong to collections via post_collections junction table (M:N).
- * Sidebar ordering is managed through the collection_directory_item table with fractional indexing.
+ * Collection directory ordering is managed through the collection_directory_item
+ * table with fractional indexing.
  */
 
 import { eq, asc, sql, and, inArray, desc } from "drizzle-orm";
@@ -22,22 +23,28 @@ import { now } from "../lib/time.js";
 import type {
   Collection,
   CollectionDirectoryCollection,
+  CollectionDirectoryEntry,
+  CollectionDirectoryEntryType,
   CollectionDirectoryItem,
   CollectionsDirectoryData,
-  SidebarItem,
-  SidebarItemType,
   CreateCollection,
+  CreateCollectionDirectoryEntry,
   UpdateCollection,
-  UpdateSidebarItem,
+  UpdateCollectionDirectoryEntry,
   CollectionSortOrder,
 } from "../types.js";
-import { ConflictError } from "../lib/errors.js";
+import { ConflictError, ValidationError } from "../lib/errors.js";
 import {
   createPathService,
   toCollectionPath,
   type PathService,
 } from "./path.js";
+import { getCollectionPagePath } from "../lib/collection-paths.js";
 import {
+  CreateCollectionDirectoryItemSchema,
+  CollectionDirectoryLabelSchema,
+  CollectionDirectoryLinkLabelSchema,
+  CollectionDirectoryLinkUrlSchema,
   CollectionDescriptionValueSchema,
   CollectionSlugSchema,
   CollectionTitleSchema,
@@ -46,27 +53,42 @@ import {
 
 const POSITION_RETRY_ATTEMPTS = 5;
 
-function isUniqueConstraintError(err: unknown): boolean {
-  let current: unknown = err;
-  while (current) {
-    const msg = String(current);
-    if (
-      msg.includes("UNIQUE constraint") ||
-      msg.includes("SQLITE_CONSTRAINT")
-    ) {
-      return true;
-    }
-    current =
-      current instanceof Error && current.cause !== current
-        ? current.cause
-        : undefined;
+// Re-export shared constraint detection — see db/dialect.ts
+import { isUniqueConstraintError } from "../db/dialect.js";
+
+export interface ResolvedCollectionSelection {
+  collections: Collection[];
+  slugs: string[];
+  slugExpression: string;
+}
+
+function parseCollectionSelectionSlugs(
+  slugExpression: string,
+): string[] | null {
+  const parts = slugExpression.split("+");
+  if (parts.length === 0) return null;
+
+  const seen = new Set<string>();
+  const slugs: string[] = [];
+
+  for (const part of parts) {
+    const slug = part.trim();
+    if (!slug) return null;
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    slugs.push(slug);
   }
-  return false;
+
+  return slugs.length > 0 ? slugs : null;
 }
 
 export interface CollectionService {
   getById(id: string): Promise<Collection | null>;
   getBySlug(slug: string): Promise<Collection | null>;
+  getBySlugs(slugs: string[]): Promise<Collection[]>;
+  resolveSelection(
+    slugExpression: string,
+  ): Promise<ResolvedCollectionSelection | null>;
   list(): Promise<Collection[]>;
   listDirectoryData(): Promise<CollectionsDirectoryData>;
   /** List collections sorted by most recent post addition (for compose dialog) */
@@ -74,39 +96,99 @@ export interface CollectionService {
   create(data: CreateCollection): Promise<Collection>;
   update(id: string, data: UpdateCollection): Promise<Collection | null>;
   delete(id: string): Promise<boolean>;
-  /** List all sidebar items ordered by position */
-  listSidebarItems(): Promise<SidebarItem[]>;
-  /** Create a sidebar item (collection or divider) */
-  createSidebarItem(
-    type: SidebarItemType,
-    collectionId?: string,
-    label?: string | null,
-  ): Promise<SidebarItem>;
-  /** Delete a sidebar item by ID */
-  deleteSidebarItem(id: string): Promise<boolean>;
-  /** Update a sidebar item */
-  updateSidebarItem(
+  /** List all collection directory items ordered by position */
+  listDirectoryItems(): Promise<CollectionDirectoryEntry[]>;
+  /** Create a collection directory item (collection, divider, or link) */
+  createDirectoryItem(
+    data: CreateCollectionDirectoryEntry,
+  ): Promise<CollectionDirectoryEntry>;
+  /** Delete a collection directory item by ID */
+  deleteDirectoryItem(id: string): Promise<boolean>;
+  /** Update a collection directory item */
+  updateDirectoryItem(
     id: string,
-    data: UpdateSidebarItem,
-  ): Promise<SidebarItem | null>;
-  /** Move a sidebar item between two neighbors */
-  moveSidebarItem(
+    data: UpdateCollectionDirectoryEntry,
+  ): Promise<CollectionDirectoryEntry | null>;
+  /** Move a collection directory item between two neighbors */
+  moveDirectoryItem(
     id: string,
     after: string | null,
     before: string | null,
-  ): Promise<SidebarItem | null>;
+  ): Promise<CollectionDirectoryEntry | null>;
   /** Get post count per collection */
   getPostCounts(): Promise<Map<string, number>>;
-  /** Add a post to a collection */
-  addPost(collectionId: string, postId: string): Promise<void>;
+  /**
+   * Add a post to a collection. Optional metadata lets the caller set the
+   * per-row `createdAt` / `position` / `pinnedAt` explicitly; omitted
+   * fields default to `now()` / append-at-end / `null`.
+   */
+  addPost(
+    collectionId: string,
+    postId: string,
+    opts?: {
+      createdAt?: number;
+      position?: number;
+      pinnedAt?: number | null;
+    },
+  ): Promise<void>;
+  /**
+   * Replace all collection memberships of a post in one transaction,
+   * preserving each entry's `createdAt` / `position` / `pinnedAt`.
+   * Used by the Hugo import path so round-tripping through
+   * `jant site export | jant site import` is lossless.
+   */
+  syncPostCollectionsWithMeta(
+    postId: string,
+    entries: {
+      collectionId: string;
+      createdAt?: number;
+      position?: number;
+      pinnedAt?: number | null;
+    }[],
+  ): Promise<void>;
   /** Remove a post from a collection */
   removePost(collectionId: string, postId: string): Promise<void>;
+  /** Pin a post within a collection */
+  pinPost(collectionId: string, postId: string): Promise<void>;
+  /** Unpin a post within a collection */
+  unpinPost(collectionId: string, postId: string): Promise<void>;
+  /** Get pinned post IDs for given collections */
+  getPinnedPostIds(collectionIds: string[]): Promise<Set<string>>;
   /** Get all collections a post belongs to */
   getCollectionsByPostId(postId: string): Promise<Collection[]>;
   /** Batch get collections for multiple posts */
   getCollectionsByPostIds(
     postIds: string[],
   ): Promise<Map<string, Collection[]>>;
+  /**
+   * Batch get the set of collection IDs each post is pinned in.
+   *
+   * Used by the Hugo export to surface per-collection pins so the static
+   * collection page can sort pinned posts to the top, mirroring the live
+   * site behavior.
+   */
+  getCollectionPinsByPostIds(
+    postIds: string[],
+  ): Promise<Map<string, Set<string>>>;
+  /**
+   * Batch fetch the full per-entry collection metadata for each post: the
+   * `createdAt` timestamp, `position`, and per-collection `pinnedAt`.
+   *
+   * Used by the Hugo export to emit lossless `collections` front-matter
+   * entries so round-tripping through `jant site export | jant site import`
+   * preserves per-entry state.
+   */
+  getCollectionEntriesByPostIds(postIds: string[]): Promise<
+    Map<
+      string,
+      {
+        collectionId: string;
+        createdAt: number;
+        position: number;
+        pinnedAt: number | null;
+      }[]
+    >
+  >;
   /** Get all post IDs in a collection */
   getPostIds(collectionId: string): Promise<string[]>;
   /** Sync a post's collection memberships (replace all with given IDs) */
@@ -124,9 +206,10 @@ export function createCollectionService(
   const {
     collections,
     pathRegistry,
-    collectionDirectoryItems: sidebarItems,
+    collectionDirectoryItems: directoryItemsTable,
     postCollections,
     posts,
+    navItems,
   } = databaseSchema;
   const usesBatchWrites = !supportsDrizzleTransaction(db, databaseDialect);
 
@@ -184,45 +267,100 @@ export function createCollectionService(
     };
   }
 
-  function toSidebarItem(row: typeof sidebarItems.$inferSelect): SidebarItem {
+  function toDirectoryItem(
+    row: typeof directoryItemsTable.$inferSelect,
+  ): CollectionDirectoryEntry {
     return {
       id: row.id,
       siteId: row.siteId,
-      type: row.type as SidebarItemType,
+      type: row.type as CollectionDirectoryEntryType,
       collectionId: row.collectionId,
       label: row.label,
+      url: row.url,
+      description: row.description,
       position: row.position,
       createdAt: row.createdAt,
       updatedAt: row.updatedAt,
     };
   }
 
-  function normalizeSidebarLabel(label?: string | null): string | null {
-    const trimmed = label?.trim();
+  function normalizeDirectoryLabel(label?: string | null): string | null {
+    if (label === null) return null;
+    if (label === undefined) return null;
+
+    const trimmed = parseValidated(CollectionDirectoryLabelSchema, label);
     return trimmed ? trimmed : null;
   }
 
-  async function getLastSidebarPosition(): Promise<string | null> {
+  function normalizeDirectoryLinkLabel(label: string): string {
+    return parseValidated(CollectionDirectoryLinkLabelSchema, label);
+  }
+
+  function normalizeDirectoryUrl(url: string): string {
+    return parseValidated(CollectionDirectoryLinkUrlSchema, url);
+  }
+
+  function normalizeDirectoryDescription(
+    description?: string | null,
+  ): string | null {
+    if (description === null || description === undefined) return null;
+    const trimmed = parseValidated(
+      CollectionDescriptionValueSchema,
+      description,
+    );
+    return trimmed || null;
+  }
+
+  function normalizeCreateDirectoryItemInput(
+    data: CreateCollectionDirectoryEntry,
+  ): CreateCollectionDirectoryEntry {
+    if (data.type === "collection") {
+      return data;
+    }
+
+    const normalized = parseValidated(
+      CreateCollectionDirectoryItemSchema,
+      data,
+    );
+    if (normalized.type === "divider") {
+      return {
+        type: "divider",
+        label: normalizeDirectoryLabel(normalized.label),
+      };
+    }
+
+    return {
+      type: "link",
+      label: normalizeDirectoryLinkLabel(normalized.label),
+      url: normalizeDirectoryUrl(normalized.url),
+      description: normalizeDirectoryDescription(normalized.description),
+    };
+  }
+
+  async function getLastDirectoryPosition(): Promise<string | null> {
     const rows = await db
-      .select({ position: sidebarItems.position })
-      .from(sidebarItems)
-      .where(eq(sidebarItems.siteId, siteId))
-      .orderBy(sql`${sidebarItems.position} DESC`)
+      .select({ position: directoryItemsTable.position })
+      .from(directoryItemsTable)
+      .where(eq(directoryItemsTable.siteId, siteId))
+      .orderBy(sql`${directoryItemsTable.position} DESC`)
       .limit(1);
     return rows[0]?.position ?? null;
   }
 
-  async function listOrderedSidebarPositions(excludeId?: string) {
+  async function listOrderedDirectoryPositions(excludeId?: string) {
     const rows = await db
-      .select({ id: sidebarItems.id, position: sidebarItems.position })
-      .from(sidebarItems)
-      .where(eq(sidebarItems.siteId, siteId))
-      .orderBy(asc(sidebarItems.position));
+      .select({
+        id: directoryItemsTable.id,
+        position: directoryItemsTable.position,
+      })
+      .from(directoryItemsTable)
+      .where(eq(directoryItemsTable.siteId, siteId))
+      .orderBy(asc(directoryItemsTable.position));
     return excludeId ? rows.filter((row) => row.id !== excludeId) : rows;
   }
 
-  async function getAppendSidebarPosition(): Promise<string> {
-    const lastPos = await getLastSidebarPosition();
+  async function getAppendDirectoryPosition(): Promise<string> {
+    const lastPos = await getLastDirectoryPosition();
     return generateKeyBetween(lastPos, null);
   }
 
@@ -235,12 +373,12 @@ export function createCollectionService(
     return rows.length > 0;
   }
 
-  async function getSidebarMovePosition(
+  async function getDirectoryMovePosition(
     id: string,
     afterId: string | null,
     beforeId: string | null,
   ): Promise<string> {
-    const rows = await listOrderedSidebarPositions(id);
+    const rows = await listOrderedDirectoryPositions(id);
     const afterIndex = afterId
       ? rows.findIndex((row) => row.id === afterId)
       : -1;
@@ -288,29 +426,15 @@ export function createCollectionService(
       .filter((row): row is Collection => row !== null);
   }
 
-  async function getPostCollectionIds(postId: string): Promise<string[]> {
-    const rows = await db
-      .select({ collectionId: postCollections.collectionId })
-      .from(postCollections)
-      .where(
-        and(
-          eq(postCollections.siteId, siteId),
-          eq(postCollections.postId, postId),
-        ),
-      );
-
-    return rows.map((row) => row.collectionId);
-  }
-
   async function listDirectoryCollections(): Promise<
     CollectionDirectoryCollection[]
   > {
     const postCount = sql<number>`
-      COUNT(
+      CAST(COUNT(
         CASE
           WHEN ${posts.id} IS NOT NULL AND ${posts.deletedAt} IS NULL THEN 1
         END
-      )
+      ) AS INTEGER)
     `.as("post_count");
     const recentActivityAt = sql<number | null>`
       MAX(
@@ -369,7 +493,7 @@ export function createCollectionService(
 
   function buildDirectoryItems(
     directoryCollections: CollectionDirectoryCollection[],
-    orderedSidebarItems: SidebarItem[],
+    orderedDirectoryItems: CollectionDirectoryEntry[],
   ): CollectionDirectoryItem[] {
     const collectionMap = new Map(
       directoryCollections.map((collection) => [collection.id, collection]),
@@ -377,7 +501,7 @@ export function createCollectionService(
     const seenCollections = new Set<string>();
     const items: CollectionDirectoryItem[] = [];
 
-    for (const item of orderedSidebarItems) {
+    for (const item of orderedDirectoryItems) {
       if (item.type === "divider") {
         items.push({
           id: item.id,
@@ -387,6 +511,18 @@ export function createCollectionService(
         continue;
       }
 
+      if (item.type === "link") {
+        if (!item.label || !item.url) continue;
+        items.push({
+          id: item.id,
+          type: "link",
+          label: item.label,
+          url: item.url,
+          description: item.description,
+        });
+        continue;
+      }
+
       const collection = item.collectionId
         ? collectionMap.get(item.collectionId)
         : undefined;
@@ -430,6 +566,31 @@ export function createCollectionService(
       return this.getById(resolved.collectionId);
     },
 
+    async getBySlugs(slugs) {
+      if (slugs.length === 0) return [];
+
+      const collections = await Promise.all(
+        slugs.map((slug) => this.getBySlug(slug)),
+      );
+      return collections.filter(
+        (collection): collection is Collection => collection !== null,
+      );
+    },
+
+    async resolveSelection(slugExpression) {
+      const slugs = parseCollectionSelectionSlugs(slugExpression);
+      if (!slugs) return null;
+
+      const collections = await this.getBySlugs(slugs);
+      if (collections.length !== slugs.length) return null;
+
+      return {
+        collections,
+        slugs,
+        slugExpression: slugs.join("+"),
+      };
+    },
+
     async list() {
       const rows = await db
         .select()
@@ -440,15 +601,15 @@ export function createCollectionService(
     },
 
     async listDirectoryData() {
-      const [directoryCollections, orderedSidebarItems] = await Promise.all([
+      const [directoryCollections, orderedDirectoryItems] = await Promise.all([
         listDirectoryCollections(),
-        this.listSidebarItems(),
+        this.listDirectoryItems(),
       ]);
 
       return {
         collections: directoryCollections,
-        items: buildDirectoryItems(directoryCollections, orderedSidebarItems),
-        sidebarItems: orderedSidebarItems,
+        items: buildDirectoryItems(directoryCollections, orderedDirectoryItems),
+        directoryItems: orderedDirectoryItems,
       };
     },
 
@@ -468,7 +629,10 @@ export function createCollectionService(
         )
         .where(eq(collections.siteId, siteId))
         .groupBy(collections.id)
-        .orderBy(desc(sql`last_added_at`), desc(collections.createdAt));
+        .orderBy(
+          desc(sql`COALESCE(MAX(${postCollections.createdAt}), 0)`),
+          desc(collections.createdAt),
+        );
       return hydrateCollections(rows.map((row) => row.collection));
     },
 
@@ -480,7 +644,7 @@ export function createCollectionService(
 
       for (let attempt = 0; attempt < POSITION_RETRY_ATTEMPTS; attempt += 1) {
         try {
-          const position = await getAppendSidebarPosition();
+          const position = await getAppendDirectoryPosition();
           if (usesBatchWrites) {
             const writeQueries = [
               db.insert(collections).values({
@@ -504,11 +668,13 @@ export function createCollectionService(
                 createdAt: timestamp,
                 updatedAt: timestamp,
               }),
-              db.insert(sidebarItems).values({
+              db.insert(directoryItemsTable).values({
                 id: createEntityId("collectionDirectoryItem"),
                 siteId,
                 type: "collection",
                 collectionId: id,
+                label: null,
+                url: null,
                 position,
                 createdAt: timestamp,
                 updatedAt: timestamp,
@@ -546,11 +712,13 @@ export function createCollectionService(
                 updatedAt: timestamp,
               });
 
-              await tx.insert(sidebarItems).values({
+              await tx.insert(directoryItemsTable).values({
                 id: createEntityId("collectionDirectoryItem"),
                 siteId,
                 type: "collection",
                 collectionId: id,
+                label: null,
+                url: null,
                 position,
                 createdAt: timestamp,
                 updatedAt: timestamp,
@@ -580,7 +748,7 @@ export function createCollectionService(
         }
       }
 
-      throw new Error("Failed to assign a unique sidebar item position");
+      throw new Error("Failed to assign a unique directory item position");
     },
 
     async update(id, data) {
@@ -605,6 +773,22 @@ export function createCollectionService(
       }
 
       const timestamp = now();
+
+      // Update nav item URLs when the collection slug changes
+      if (
+        normalizedData.slug !== undefined &&
+        normalizedData.slug !== existing.slug
+      ) {
+        await db
+          .update(navItems)
+          .set({
+            url: getCollectionPagePath(normalizedData.slug),
+            updatedAt: timestamp,
+          })
+          .where(
+            and(eq(navItems.siteId, siteId), eq(navItems.collectionId, id)),
+          );
+      }
       const updates: Partial<typeof collections.$inferInsert> = {
         updatedAt: timestamp,
       };
@@ -638,13 +822,16 @@ export function createCollectionService(
           ),
         );
       await db
-        .delete(sidebarItems)
+        .delete(directoryItemsTable)
         .where(
           and(
-            eq(sidebarItems.siteId, siteId),
-            eq(sidebarItems.collectionId, id),
+            eq(directoryItemsTable.siteId, siteId),
+            eq(directoryItemsTable.collectionId, id),
           ),
         );
+      await db
+        .delete(navItems)
+        .where(and(eq(navItems.siteId, siteId), eq(navItems.collectionId, id)));
       const result = await db
         .delete(collections)
         .where(and(eq(collections.siteId, siteId), eq(collections.id, id)))
@@ -652,57 +839,73 @@ export function createCollectionService(
       return result.length > 0;
     },
 
-    async listSidebarItems() {
+    async listDirectoryItems() {
       const rows = await db
         .select()
-        .from(sidebarItems)
-        .where(eq(sidebarItems.siteId, siteId))
-        .orderBy(asc(sidebarItems.position));
-      return rows.map(toSidebarItem);
+        .from(directoryItemsTable)
+        .where(eq(directoryItemsTable.siteId, siteId))
+        .orderBy(asc(directoryItemsTable.position));
+      return rows.map(toDirectoryItem);
     },
 
-    async createSidebarItem(type, collectionId, label) {
+    async createDirectoryItem(data) {
+      const normalizedData = normalizeCreateDirectoryItemInput(data);
       const id = createEntityId("collectionDirectoryItem");
       const timestamp = now();
-      const normalizedLabel =
-        type === "divider" ? normalizeSidebarLabel(label) : null;
 
       for (let attempt = 0; attempt < POSITION_RETRY_ATTEMPTS; attempt += 1) {
         try {
           const result = await db
-            .insert(sidebarItems)
+            .insert(directoryItemsTable)
             .values({
               id,
               siteId,
-              type,
-              collectionId: collectionId ?? null,
-              label: normalizedLabel,
-              position: await getAppendSidebarPosition(),
+              type: normalizedData.type,
+              collectionId:
+                normalizedData.type === "collection"
+                  ? normalizedData.collectionId
+                  : null,
+              label:
+                normalizedData.type === "divider"
+                  ? (normalizedData.label ?? null)
+                  : normalizedData.type === "link"
+                    ? normalizedData.label
+                    : null,
+              url: normalizedData.type === "link" ? normalizedData.url : null,
+              description:
+                normalizedData.type === "link"
+                  ? (normalizedData.description ?? null)
+                  : null,
+              position: await getAppendDirectoryPosition(),
               createdAt: timestamp,
               updatedAt: timestamp,
             })
             .returning();
 
           // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- DB insert with .returning() always returns inserted row
-          return toSidebarItem(result[0]!);
+          return toDirectoryItem(result[0]!);
         } catch (err) {
           if (
-            type === "collection" &&
-            collectionId &&
+            normalizedData.type === "collection" &&
             isUniqueConstraintError(err)
           ) {
             const existing = await db
-              .select({ id: sidebarItems.id })
-              .from(sidebarItems)
+              .select({ id: directoryItemsTable.id })
+              .from(directoryItemsTable)
               .where(
                 and(
-                  eq(sidebarItems.siteId, siteId),
-                  eq(sidebarItems.collectionId, collectionId),
+                  eq(directoryItemsTable.siteId, siteId),
+                  eq(
+                    directoryItemsTable.collectionId,
+                    normalizedData.collectionId,
+                  ),
                 ),
               )
               .limit(1);
             if (existing.length > 0) {
-              throw new ConflictError("Collection is already in the sidebar.");
+              throw new ConflictError(
+                "Collection is already in the directory.",
+              );
             }
           }
           if (
@@ -714,48 +917,96 @@ export function createCollectionService(
         }
       }
 
-      throw new Error("Failed to assign a unique sidebar item position");
+      throw new Error("Failed to assign a unique directory item position");
     },
 
-    async deleteSidebarItem(id) {
+    async deleteDirectoryItem(id) {
       const result = await db
-        .delete(sidebarItems)
-        .where(and(eq(sidebarItems.siteId, siteId), eq(sidebarItems.id, id)))
+        .delete(directoryItemsTable)
+        .where(
+          and(
+            eq(directoryItemsTable.siteId, siteId),
+            eq(directoryItemsTable.id, id),
+          ),
+        )
         .returning();
       return result.length > 0;
     },
 
-    async updateSidebarItem(id, data) {
+    async updateDirectoryItem(id, data) {
       const existing = await db
         .select()
-        .from(sidebarItems)
-        .where(and(eq(sidebarItems.siteId, siteId), eq(sidebarItems.id, id)))
+        .from(directoryItemsTable)
+        .where(
+          and(
+            eq(directoryItemsTable.siteId, siteId),
+            eq(directoryItemsTable.id, id),
+          ),
+        )
         .limit(1);
       const item = existing[0];
       if (!item) return null;
 
-      if (data.label === undefined) {
-        return toSidebarItem(item);
+      if (
+        data.label === undefined &&
+        data.url === undefined &&
+        data.description === undefined
+      ) {
+        return toDirectoryItem(item);
+      }
+
+      let nextLabel = item.label;
+      let nextUrl = item.url;
+      let nextDescription = item.description;
+
+      if (item.type === "divider" && data.label !== undefined) {
+        nextLabel = normalizeDirectoryLabel(data.label);
+      }
+
+      if (item.type === "link") {
+        if (data.label !== undefined) {
+          if (data.label === null) {
+            throw new ValidationError("Link label is required.");
+          }
+          nextLabel = normalizeDirectoryLinkLabel(data.label);
+        }
+        if (data.url !== undefined) {
+          nextUrl = normalizeDirectoryUrl(data.url);
+        }
+        if (data.description !== undefined) {
+          nextDescription = normalizeDirectoryDescription(data.description);
+        }
       }
 
       const result = await db
-        .update(sidebarItems)
+        .update(directoryItemsTable)
         .set({
-          label:
-            item.type === "divider" ? normalizeSidebarLabel(data.label) : null,
+          label: item.type === "collection" ? null : nextLabel,
+          url: item.type === "link" ? nextUrl : null,
+          description: item.type === "link" ? nextDescription : null,
           updatedAt: now(),
         })
-        .where(and(eq(sidebarItems.siteId, siteId), eq(sidebarItems.id, id)))
+        .where(
+          and(
+            eq(directoryItemsTable.siteId, siteId),
+            eq(directoryItemsTable.id, id),
+          ),
+        )
         .returning();
 
-      return result[0] ? toSidebarItem(result[0]) : null;
+      return result[0] ? toDirectoryItem(result[0]) : null;
     },
 
-    async moveSidebarItem(id, afterId, beforeId) {
+    async moveDirectoryItem(id, afterId, beforeId) {
       const items = await db
         .select()
-        .from(sidebarItems)
-        .where(and(eq(sidebarItems.siteId, siteId), eq(sidebarItems.id, id)))
+        .from(directoryItemsTable)
+        .where(
+          and(
+            eq(directoryItemsTable.siteId, siteId),
+            eq(directoryItemsTable.id, id),
+          ),
+        )
         .limit(1);
       if (!items[0]) return null;
 
@@ -763,17 +1014,20 @@ export function createCollectionService(
       for (let attempt = 0; attempt < POSITION_RETRY_ATTEMPTS; attempt += 1) {
         try {
           const result = await db
-            .update(sidebarItems)
+            .update(directoryItemsTable)
             .set({
-              position: await getSidebarMovePosition(id, afterId, beforeId),
+              position: await getDirectoryMovePosition(id, afterId, beforeId),
               updatedAt: timestamp,
             })
             .where(
-              and(eq(sidebarItems.siteId, siteId), eq(sidebarItems.id, id)),
+              and(
+                eq(directoryItemsTable.siteId, siteId),
+                eq(directoryItemsTable.id, id),
+              ),
             )
             .returning();
 
-          return result[0] ? toSidebarItem(result[0]) : null;
+          return result[0] ? toDirectoryItem(result[0]) : null;
         } catch (err) {
           if (
             !isUniqueConstraintError(err) ||
@@ -784,14 +1038,14 @@ export function createCollectionService(
         }
       }
 
-      throw new Error("Failed to assign a unique sidebar item position");
+      throw new Error("Failed to assign a unique directory item position");
     },
 
     async getPostCounts() {
       const rows = await db
         .select({
           collectionId: postCollections.collectionId,
-          count: sql<number>`count(*)`.as("count"),
+          count: sql<number>`CAST(count(*) AS INTEGER)`.as("count"),
         })
         .from(postCollections)
         .innerJoin(
@@ -808,13 +1062,97 @@ export function createCollectionService(
       return counts;
     },
 
-    async addPost(collectionId, postId) {
+    async addPost(collectionId, postId, opts) {
+      const [maxRow] = await db
+        .select({
+          maxPos: sql<number>`COALESCE(MAX(${postCollections.position}), -1)`,
+        })
+        .from(postCollections)
+        .where(
+          and(
+            eq(postCollections.siteId, siteId),
+            eq(postCollections.postId, postId),
+          ),
+        );
+      const nextPosition = (maxRow?.maxPos ?? -1) + 1;
       await db
         .insert(postCollections)
-        .values({ siteId, postId, collectionId, createdAt: now() })
+        .values({
+          siteId,
+          postId,
+          collectionId,
+          createdAt: opts?.createdAt ?? now(),
+          position: opts?.position ?? nextPosition,
+          pinnedAt: opts?.pinnedAt ?? null,
+        })
         .onConflictDoNothing();
     },
 
+    async syncPostCollectionsWithMeta(postId, entries) {
+      const seen = new Set<string>();
+      const timestamp = now();
+      const insertValues: {
+        siteId: string;
+        postId: string;
+        collectionId: string;
+        createdAt: number;
+        position: number;
+        pinnedAt: number | null;
+      }[] = [];
+      let fallbackPosition = 0;
+      for (const entry of entries) {
+        if (seen.has(entry.collectionId)) continue;
+        seen.add(entry.collectionId);
+        insertValues.push({
+          siteId,
+          postId,
+          collectionId: entry.collectionId,
+          createdAt: entry.createdAt ?? timestamp,
+          position: entry.position ?? fallbackPosition,
+          pinnedAt: entry.pinnedAt ?? null,
+        });
+        fallbackPosition++;
+      }
+
+      const deleteQuery = db
+        .delete(postCollections)
+        .where(
+          and(
+            eq(postCollections.siteId, siteId),
+            eq(postCollections.postId, postId),
+          ),
+        );
+
+      if (usesBatchWrites) {
+        const writeQueries = [];
+        writeQueries.push(deleteQuery);
+        if (insertValues.length > 0) {
+          writeQueries.push(db.insert(postCollections).values(insertValues));
+        }
+        await db.batch(
+          writeQueries as [
+            (typeof writeQueries)[number],
+            ...(typeof writeQueries)[number][],
+          ],
+        );
+        return;
+      }
+
+      await db.transaction(async (tx) => {
+        await tx
+          .delete(postCollections)
+          .where(
+            and(
+              eq(postCollections.siteId, siteId),
+              eq(postCollections.postId, postId),
+            ),
+          );
+        if (insertValues.length > 0) {
+          await tx.insert(postCollections).values(insertValues);
+        }
+      });
+    },
+
     async removePost(collectionId, postId) {
       await db
         .delete(postCollections)
@@ -827,6 +1165,47 @@ export function createCollectionService(
         );
     },
 
+    async pinPost(collectionId, postId) {
+      await db
+        .update(postCollections)
+        .set({ pinnedAt: now() })
+        .where(
+          and(
+            eq(postCollections.siteId, siteId),
+            eq(postCollections.postId, postId),
+            eq(postCollections.collectionId, collectionId),
+          ),
+        );
+    },
+
+    async unpinPost(collectionId, postId) {
+      await db
+        .update(postCollections)
+        .set({ pinnedAt: null })
+        .where(
+          and(
+            eq(postCollections.siteId, siteId),
+            eq(postCollections.postId, postId),
+            eq(postCollections.collectionId, collectionId),
+          ),
+        );
+    },
+
+    async getPinnedPostIds(collectionIds) {
+      if (collectionIds.length === 0) return new Set<string>();
+      const rows = await db
+        .select({ postId: postCollections.postId })
+        .from(postCollections)
+        .where(
+          and(
+            eq(postCollections.siteId, siteId),
+            inArray(postCollections.collectionId, collectionIds),
+            sql`${postCollections.pinnedAt} IS NOT NULL`,
+          ),
+        );
+      return new Set(rows.map((r) => r.postId));
+    },
+
     async getCollectionsByPostId(postId) {
       const rows = await db
         .select({ collection: collections })
@@ -842,7 +1221,7 @@ export function createCollectionService(
             eq(postCollections.postId, postId),
           ),
         )
-        .orderBy(asc(collections.createdAt));
+        .orderBy(asc(postCollections.position), asc(postCollections.createdAt));
 
       return hydrateCollections(rows.map((row) => row.collection));
     },
@@ -869,7 +1248,10 @@ export function createCollectionService(
               inArray(postCollections.postId, chunk),
             ),
           )
-          .orderBy(asc(collections.createdAt)),
+          .orderBy(
+            asc(postCollections.position),
+            asc(postCollections.createdAt),
+          ),
       );
 
       const collectionRows = rows.map((row) => row.collection);
@@ -888,6 +1270,35 @@ export function createCollectionService(
       return result;
     },
 
+    async getCollectionPinsByPostIds(postIds) {
+      const result = new Map<string, Set<string>>();
+      if (postIds.length === 0) return result;
+
+      const rows = await batchQueryRows(postIds, (chunk) =>
+        db
+          .select({
+            postId: postCollections.postId,
+            collectionId: postCollections.collectionId,
+          })
+          .from(postCollections)
+          .where(
+            and(
+              eq(postCollections.siteId, siteId),
+              inArray(postCollections.postId, chunk),
+              sql`${postCollections.pinnedAt} IS NOT NULL`,
+            ),
+          ),
+      );
+
+      for (const row of rows) {
+        const existing = result.get(row.postId) ?? new Set<string>();
+        existing.add(row.collectionId);
+        result.set(row.postId, existing);
+      }
+
+      return result;
+    },
+
     async getPostIds(collectionId) {
       const rows = await db
         .select({ postId: postCollections.postId })
@@ -902,49 +1313,103 @@ export function createCollectionService(
       return rows.map((row) => row.postId);
     },
 
+    async getCollectionEntriesByPostIds(postIds) {
+      const result = new Map<
+        string,
+        {
+          collectionId: string;
+          createdAt: number;
+          position: number;
+          pinnedAt: number | null;
+        }[]
+      >();
+      if (postIds.length === 0) return result;
+
+      const rows = await batchQueryRows(postIds, (chunk) =>
+        db
+          .select({
+            postId: postCollections.postId,
+            collectionId: postCollections.collectionId,
+            createdAt: postCollections.createdAt,
+            position: postCollections.position,
+            pinnedAt: postCollections.pinnedAt,
+          })
+          .from(postCollections)
+          .where(
+            and(
+              eq(postCollections.siteId, siteId),
+              inArray(postCollections.postId, chunk),
+            ),
+          )
+          .orderBy(
+            asc(postCollections.position),
+            asc(postCollections.createdAt),
+          ),
+      );
+
+      for (const row of rows) {
+        const existing = result.get(row.postId) ?? [];
+        existing.push({
+          collectionId: row.collectionId,
+          createdAt: row.createdAt,
+          position: row.position,
+          pinnedAt: row.pinnedAt,
+        });
+        result.set(row.postId, existing);
+      }
+
+      return result;
+    },
+
     async syncPostCollections(postId, collectionIds) {
       const nextCollectionIds = [...new Set(collectionIds)];
-      const existingCollectionIds = await getPostCollectionIds(postId);
-      const existingIds = new Set(existingCollectionIds);
-      const nextIds = new Set(nextCollectionIds);
-      const removedIds = existingCollectionIds.filter((id) => !nextIds.has(id));
-      const addedIds = nextCollectionIds.filter((id) => !existingIds.has(id));
 
-      if (removedIds.length === 0 && addedIds.length === 0) {
+      // Fetch existing rows to preserve createdAt for retained collections
+      const existingRows = await db
+        .select({
+          collectionId: postCollections.collectionId,
+          createdAt: postCollections.createdAt,
+        })
+        .from(postCollections)
+        .where(
+          and(
+            eq(postCollections.siteId, siteId),
+            eq(postCollections.postId, postId),
+          ),
+        );
+
+      if (existingRows.length === 0 && nextCollectionIds.length === 0) {
         return;
       }
 
+      const existingTimestamps = new Map(
+        existingRows.map((r) => [r.collectionId, r.createdAt]),
+      );
+      const timestamp = now();
+      const insertValues = nextCollectionIds.map((collectionId, index) => ({
+        siteId,
+        postId,
+        collectionId,
+        createdAt: existingTimestamps.get(collectionId) ?? timestamp,
+        position: index,
+      }));
+
+      // Delete all and re-insert to preserve user-specified ordering
+      const deleteQuery = db
+        .delete(postCollections)
+        .where(
+          and(
+            eq(postCollections.siteId, siteId),
+            eq(postCollections.postId, postId),
+          ),
+        );
+
       if (usesBatchWrites) {
         const writeQueries = [];
-
-        if (removedIds.length > 0) {
-          writeQueries.push(
-            db
-              .delete(postCollections)
-              .where(
-                and(
-                  eq(postCollections.siteId, siteId),
-                  eq(postCollections.postId, postId),
-                  inArray(postCollections.collectionId, removedIds),
-                ),
-              ),
-          );
-        }
-
-        if (addedIds.length > 0) {
-          const timestamp = now();
-          writeQueries.push(
-            db.insert(postCollections).values(
-              addedIds.map((collectionId) => ({
-                siteId,
-                postId,
-                collectionId,
-                createdAt: timestamp,
-              })),
-            ),
-          );
+        writeQueries.push(deleteQuery);
+        if (insertValues.length > 0) {
+          writeQueries.push(db.insert(postCollections).values(insertValues));
         }
-
         await db.batch(
           writeQueries as [
             (typeof writeQueries)[number],
@@ -955,28 +1420,16 @@ export function createCollectionService(
       }
 
       await db.transaction(async (tx) => {
-        if (removedIds.length > 0) {
-          await tx
-            .delete(postCollections)
-            .where(
-              and(
-                eq(postCollections.siteId, siteId),
-                eq(postCollections.postId, postId),
-                inArray(postCollections.collectionId, removedIds),
-              ),
-            );
-        }
-
-        if (addedIds.length > 0) {
-          const timestamp = now();
-          await tx.insert(postCollections).values(
-            addedIds.map((collectionId) => ({
-              siteId,
-              postId,
-              collectionId,
-              createdAt: timestamp,
-            })),
+        await tx
+          .delete(postCollections)
+          .where(
+            and(
+              eq(postCollections.siteId, siteId),
+              eq(postCollections.postId, postId),
+            ),
           );
+        if (insertValues.length > 0) {
+          await tx.insert(postCollections).values(insertValues);
         }
       });
     },