feat: pinned topics UI with scope selector and visual indicators (#179)

* feat(types): add isPinned, isLocked, pinnedScope to Topic interface

* feat(api): add pinTopic, lockTopic, deleteTopicMod client functions

Add typed API client functions for moderation action endpoints so the
ModerationControls component can call pin, lock, and delete operations.

* feat(web): add pin icon and visual indicator to pinned TopicCard rows

* feat(web): add pinned/regular section separator to TopicList

* feat(web): wire moderation controls to API in topic detail

TopicDetailClient now derives isLocked from topic.isLocked and
determines moderator status from useAuth() role. Passes isModerator,
isPinned, isLocked, and onModerationAction to TopicView, which
renders ModerationControls with pin/lock/delete buttons.

handleModerationAction calls pinTopic, lockTopic, or deleteTopicMod
via the API client, then refreshes the page via router.refresh().

Removes the standalone isLocked prop from TopicDetailClientProps.

* feat(web): add pin scope selector (category/forum-wide) to moderation controls

Pin confirmation dialog now shows radio buttons for selecting pin scope.
Forum-wide option only visible to admins. ConfirmDialog extended with
children prop. TopicView and TopicDetailClient updated to pass isAdmin
and scope options through the action chain.

* feat(web): soft warning when 5+ topics pinned in category

src/app/sitemap.test.ts

···
         reactionCount: 3,
         isAuthorDeleted: false,
         isModDeleted: false,
+        isPinned: false,
+        isLocked: false,
+        pinnedScope: null,
+        pinnedAt: null,
         categoryMaturityRating: 'safe' as const,
         lastActivityAt: '2025-06-15T12:00:00Z',
         createdAt: '2025-06-01T00:00:00Z',
···
         reactionCount: 1,
         isAuthorDeleted: false,
         isModDeleted: false,
+        isPinned: false,
+        isLocked: false,
+        pinnedScope: null,
+        pinnedAt: null,
         categoryMaturityRating: 'safe' as const,
         lastActivityAt: '2025-06-10T08:00:00Z',
         createdAt: '2025-06-10T00:00:00Z',
···
           reactionCount: 0,
           isAuthorDeleted: false,
           isModDeleted: false,
+          isPinned: false,
+          isLocked: false,
+          pinnedScope: null,
+          pinnedAt: null,
           categoryMaturityRating: 'safe' as const,
           lastActivityAt: '2025-06-15T12:00:00Z',
           createdAt: '2025-06-01T00:00:00Z',
···
           reactionCount: 0,
           isAuthorDeleted: false,
           isModDeleted: false,
+          isPinned: false,
+          isLocked: false,
+          pinnedScope: null,
+          pinnedAt: null,
           categoryMaturityRating: 'adult' as const,
           lastActivityAt: '2025-06-10T08:00:00Z',
           createdAt: '2025-06-10T00:00:00Z',

src/components/confirm-dialog.tsx

···
 
 'use client'
 
-import { useEffect, useRef, useCallback } from 'react'
+import { type ReactNode, useEffect, useRef, useCallback } from 'react'
 import { cn } from '@/lib/utils'
 
 interface ConfirmDialogProps {
···
   variant?: 'default' | 'destructive'
   onConfirm: () => void
   onCancel: () => void
+  children?: ReactNode
 }
 
 export function ConfirmDialog({
···
   variant = 'default',
   onConfirm,
   onCancel,
+  children,
 }: ConfirmDialogProps) {
   const dialogRef = useRef<HTMLDivElement>(null)
   const cancelRef = useRef<HTMLButtonElement>(null)
···
         <p id="confirm-dialog-description" className="mt-2 text-sm text-muted-foreground">
           {description}
         </p>
+        {children}
         <div className="mt-6 flex justify-end gap-3">
           <button
             ref={cancelRef}

src/components/moderation-controls.test.tsx

···
     const results = await axe(container)
     expect(results).toHaveNoViolations()
   })
+
+  describe('pin scope selector', () => {
+    it('should show scope selector in pin confirmation dialog', async () => {
+      const user = userEvent.setup()
+      render(
+        <ModerationControls isModerator={true} isPinned={false} isAdmin={true} onAction={vi.fn()} />
+      )
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      expect(screen.getByLabelText('This category')).toBeInTheDocument()
+      expect(screen.getByLabelText('Forum-wide')).toBeInTheDocument()
+    })
+
+    it('should not show forum-wide option for non-admin moderators', async () => {
+      const user = userEvent.setup()
+      render(
+        <ModerationControls
+          isModerator={true}
+          isPinned={false}
+          isAdmin={false}
+          onAction={vi.fn()}
+        />
+      )
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      expect(screen.getByLabelText('This category')).toBeInTheDocument()
+      expect(screen.queryByLabelText('Forum-wide')).not.toBeInTheDocument()
+    })
+
+    it('should default to category scope when isAdmin is not provided', async () => {
+      const user = userEvent.setup()
+      render(<ModerationControls isModerator={true} isPinned={false} onAction={vi.fn()} />)
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      expect(screen.getByLabelText('This category')).toBeInTheDocument()
+      expect(screen.queryByLabelText('Forum-wide')).not.toBeInTheDocument()
+    })
+
+    it('should pass scope option when confirming pin with category scope', async () => {
+      const user = userEvent.setup()
+      const onAction = vi.fn()
+      render(
+        <ModerationControls
+          isModerator={true}
+          isPinned={false}
+          isAdmin={true}
+          onAction={onAction}
+        />
+      )
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      // Category is selected by default
+      await user.click(screen.getByRole('button', { name: /confirm/i }))
+      expect(onAction).toHaveBeenCalledWith('pin', { scope: 'category' })
+    })
+
+    it('should pass scope option when confirming pin with forum-wide scope', async () => {
+      const user = userEvent.setup()
+      const onAction = vi.fn()
+      render(
+        <ModerationControls
+          isModerator={true}
+          isPinned={false}
+          isAdmin={true}
+          onAction={onAction}
+        />
+      )
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      await user.click(screen.getByLabelText('Forum-wide'))
+      await user.click(screen.getByRole('button', { name: /confirm/i }))
+      expect(onAction).toHaveBeenCalledWith('pin', { scope: 'forum' })
+    })
+
+    it('should not show scope selector for unpin action', async () => {
+      const user = userEvent.setup()
+      render(
+        <ModerationControls isModerator={true} isPinned={true} isAdmin={true} onAction={vi.fn()} />
+      )
+      await user.click(screen.getByRole('button', { name: /unpin topic/i }))
+      expect(screen.queryByLabelText('This category')).not.toBeInTheDocument()
+      expect(screen.queryByLabelText('Forum-wide')).not.toBeInTheDocument()
+    })
+
+    it('should not pass scope option for non-pin actions', async () => {
+      const user = userEvent.setup()
+      const onAction = vi.fn()
+      render(<ModerationControls isModerator={true} isAdmin={true} onAction={onAction} />)
+      await user.click(screen.getByRole('button', { name: /delete/i }))
+      await user.click(screen.getByRole('button', { name: /confirm/i }))
+      expect(onAction).toHaveBeenCalledWith('delete')
+    })
+
+    it('should reset scope to category when dialog is cancelled and reopened', async () => {
+      const user = userEvent.setup()
+      const onAction = vi.fn()
+      render(
+        <ModerationControls
+          isModerator={true}
+          isPinned={false}
+          isAdmin={true}
+          onAction={onAction}
+        />
+      )
+      // Open, select forum-wide, cancel
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      await user.click(screen.getByLabelText('Forum-wide'))
+      await user.click(screen.getByRole('button', { name: /cancel/i }))
+
+      // Reopen -- should default to category
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      const categoryRadio = screen.getByLabelText('This category') as HTMLInputElement
+      expect(categoryRadio.checked).toBe(true)
+    })
+
+    it('should show warning when pinnedCount is 5 or more', async () => {
+      const user = userEvent.setup()
+      render(
+        <ModerationControls
+          isModerator={true}
+          isPinned={false}
+          pinnedCount={6}
+          onAction={vi.fn()}
+        />
+      )
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      expect(screen.getByText(/6 pinned topics/)).toBeInTheDocument()
+      expect(screen.getByRole('status')).toBeInTheDocument()
+    })
+
+    it('should not show warning when pinnedCount is below 5', async () => {
+      const user = userEvent.setup()
+      render(
+        <ModerationControls
+          isModerator={true}
+          isPinned={false}
+          pinnedCount={3}
+          onAction={vi.fn()}
+        />
+      )
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      expect(screen.queryByText(/pinned topics/)).not.toBeInTheDocument()
+    })
+
+    it('should not show warning when pinnedCount is not provided', async () => {
+      const user = userEvent.setup()
+      render(<ModerationControls isModerator={true} isPinned={false} onAction={vi.fn()} />)
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      expect(screen.queryByRole('status')).not.toBeInTheDocument()
+    })
+
+    it('passes axe accessibility check with pin scope selector open', async () => {
+      const user = userEvent.setup()
+      const { container } = render(
+        <ModerationControls isModerator={true} isPinned={false} isAdmin={true} onAction={vi.fn()} />
+      )
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
 })

src/components/moderation-controls.tsx

···
 
 export type ModerationAction = 'lock' | 'unlock' | 'pin' | 'unpin' | 'delete'
 
+export interface ModerationActionOptions {
+  scope?: 'category' | 'forum'
+}
+
 interface ModerationControlsProps {
   isModerator: boolean
   isLocked?: boolean
   isPinned?: boolean
-  onAction: (action: ModerationAction) => void
+  isAdmin?: boolean
+  pinnedCount?: number
+  onAction: (action: ModerationAction, options?: ModerationActionOptions) => void
   className?: string
 }
 
···
   isModerator,
   isLocked = false,
   isPinned = false,
+  isAdmin = false,
+  pinnedCount,
   onAction,
   className,
 }: ModerationControlsProps) {
   const [pendingAction, setPendingAction] = useState<ModerationAction | null>(null)
+  const [pinScope, setPinScope] = useState<'category' | 'forum'>('category')
 
   if (!isModerator) return null
 
···
 
   const handleConfirm = () => {
     if (pendingAction) {
-      onAction(pendingAction)
+      if (pendingAction === 'pin') {
+        onAction(pendingAction, { scope: pinScope })
+      } else {
+        onAction(pendingAction)
+      }
       setPendingAction(null)
+      setPinScope('category')
     }
   }
 
   const handleCancel = () => {
     setPendingAction(null)
+    setPinScope('category')
   }
 
   const lockAction = isLocked ? 'unlock' : 'lock'
···
           variant={pendingAction === 'delete' ? 'destructive' : 'default'}
           onConfirm={handleConfirm}
           onCancel={handleCancel}
-        />
+        >
+          {pendingAction === 'pin' && (
+            <>
+              <fieldset className="mt-3">
+                <legend className="text-sm font-medium text-foreground">Pin scope</legend>
+                <div className="mt-2 space-y-2">
+                  <label className="flex items-center gap-2 text-sm">
+                    <input
+                      type="radio"
+                      name="pin-scope"
+                      value="category"
+                      checked={pinScope === 'category'}
+                      onChange={() => setPinScope('category')}
+                    />
+                    This category
+                  </label>
+                  {isAdmin && (
+                    <label className="flex items-center gap-2 text-sm">
+                      <input
+                        type="radio"
+                        name="pin-scope"
+                        value="forum"
+                        checked={pinScope === 'forum'}
+                        onChange={() => setPinScope('forum')}
+                      />
+                      Forum-wide
+                    </label>
+                  )}
+                </div>
+              </fieldset>
+              {pinnedCount !== undefined && pinnedCount >= 5 && (
+                <p className="mt-2 text-xs text-yellow-600 dark:text-yellow-400" role="status">
+                  This category has {pinnedCount} pinned topics. Too many pinned topics reduce their
+                  effectiveness.
+                </p>
+              )}
+            </>
+          )}
+        </ConfirmDialog>
       )}
     </>
   )

src/components/topic-card.test.tsx

···
     expect(screen.getByRole('article')).toBeInTheDocument()
   })
 
+  it('should show pin icon for pinned topics', () => {
+    const pinnedTopic = {
+      ...topic,
+      isPinned: true,
+      pinnedScope: 'category' as const,
+      pinnedAt: '2026-03-01T00:00:00Z',
+    }
+    const { getByLabelText } = render(<TopicCard topic={pinnedTopic} />)
+    expect(getByLabelText('Pinned topic')).toBeInTheDocument()
+  })
+
+  it('should show Global badge for forum-wide pinned topics', () => {
+    const globalTopic = {
+      ...topic,
+      isPinned: true,
+      pinnedScope: 'forum' as const,
+      pinnedAt: '2026-03-01T00:00:00Z',
+    }
+    const { getByText } = render(<TopicCard topic={globalTopic} />)
+    expect(getByText('Global')).toBeInTheDocument()
+  })
+
+  it('should not show pin indicator for unpinned topics', () => {
+    const { queryByLabelText } = render(<TopicCard topic={topic} />)
+    expect(queryByLabelText('Pinned topic')).not.toBeInTheDocument()
+  })
+
   it('passes axe accessibility check', async () => {
     const { container } = render(<TopicCard topic={topic} />)
     const results = await axe(container)

src/components/topic-card.tsx

···
 
 import Link from 'next/link'
 import Image from 'next/image'
-import { ChatCircle, Heart, Clock } from '@phosphor-icons/react/dist/ssr'
+import { ChatCircle, Heart, Clock, PushPin } from '@phosphor-icons/react/dist/ssr'
 import type { Topic } from '@/lib/api/types'
 import { cn } from '@/lib/utils'
 import { formatRelativeTime, getTopicUrl } from '@/lib/format'
···
   return (
     <article
       className={cn(
-        'flex items-start gap-4 rounded-lg border border-border bg-card p-4 transition-colors hover:bg-card-hover',
+        'flex items-start gap-4 rounded-lg border p-4 transition-colors hover:bg-card-hover',
+        topic.isPinned ? 'border-amber-500/30 bg-amber-500/5' : 'border-border bg-card',
         className
       )}
       aria-labelledby={`topic-title-${topic.rkey}`}
···
       {/* Content */}
       <div className="min-w-0 flex-1">
         {/* Title */}
-        <h3 id={`topic-title-${topic.rkey}`} className="mb-1">
+        <h3 id={`topic-title-${topic.rkey}`} className="mb-1 flex items-center gap-1.5">
+          {topic.isPinned && (
+            <PushPin
+              className="h-4 w-4 shrink-0 text-primary"
+              weight="fill"
+              aria-label="Pinned topic"
+            />
+          )}
           <Link
             href={topicUrl}
             className="text-base font-semibold text-foreground hover:text-primary focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 rounded-sm"
           >
             {topic.title}
           </Link>
+          {topic.pinnedScope === 'forum' && (
+            <span className="shrink-0 rounded-full bg-primary/10 px-1.5 py-0.5 text-[10px] font-medium text-primary">
+              Global
+            </span>
+          )}
         </h3>
 
         {/* Metadata */}

src/components/topic-detail-client.test.tsx

···
     handle: 'test.bsky.social',
     displayName: 'Test User',
     avatarUrl: null,
+    role: 'user',
   } as Record<string, unknown> | null,
   getAccessToken: (() => 'mock-access-token') as () => string | null,
   login: vi.fn(),
···
   }),
 }))
 
+const mockPinTopic = vi.fn().mockResolvedValue({
+  uri: 'at://did:plc:user-test-001/forum.barazo.topic/abc',
+  isPinned: true,
+  pinnedScope: 'category',
+  pinnedAt: new Date().toISOString(),
+})
+const mockLockTopic = vi.fn().mockResolvedValue({
+  uri: 'at://did:plc:user-test-001/forum.barazo.topic/abc',
+  isLocked: true,
+})
+const mockDeleteTopicMod = vi.fn().mockResolvedValue({
+  uri: 'at://did:plc:user-test-001/forum.barazo.topic/abc',
+})
+
 vi.mock('@/lib/api/client', () => ({
   createReply: vi.fn().mockResolvedValue({
     uri: 'at://did:plc:user-test-001/forum.barazo.reply/789',
···
     content: 'Test reply',
     authorDid: 'did:plc:user-test-001',
   }),
+  pinTopic: (...args: unknown[]) => mockPinTopic(...args),
+  lockTopic: (...args: unknown[]) => mockLockTopic(...args),
+  deleteTopicMod: (...args: unknown[]) => mockDeleteTopicMod(...args),
 }))
 
 // Mock next/link to render a plain anchor
···
 }))
 
 const topic = mockTopics[0]!
+const lockedTopic = { ...topic, isLocked: true }
 const replies = mockReplies.slice(0, 3)
 
 beforeEach(() => {
···
 
   describe('locked topic', () => {
     it('hides reply buttons when topic is locked', () => {
-      render(<TopicDetailClient topic={topic} replies={replies} isLocked />)
+      render(<TopicDetailClient topic={lockedTopic} replies={replies} />)
       // Neither OP reply button nor reply card buttons should be present
       expect(screen.queryByRole('button', { name: /reply to this topic/i })).not.toBeInTheDocument()
       expect(
···
     })
 
     it('shows locked notice in composer when topic is locked', () => {
-      render(<TopicDetailClient topic={topic} replies={replies} isLocked />)
+      render(<TopicDetailClient topic={lockedTopic} replies={replies} />)
       expect(
         screen.getByText('This topic is locked. New replies are not accepted.')
       ).toBeInTheDocument()
     })
 
     it('still renders replies when topic is locked', () => {
-      render(<TopicDetailClient topic={topic} replies={replies} isLocked />)
+      render(<TopicDetailClient topic={lockedTopic} replies={replies} />)
       for (const reply of replies) {
         expect(screen.getByText(reply.content)).toBeInTheDocument()
       }
···
 
     it('does not open composer when topic is locked', async () => {
       const user = userEvent.setup()
-      render(<TopicDetailClient topic={topic} replies={replies} isLocked />)
+      render(<TopicDetailClient topic={lockedTopic} replies={replies} />)
 
       await user.keyboard('r')
 
···
     })
   })
 
+  describe('moderation controls', () => {
+    it('renders moderation controls for moderators', () => {
+      mockUseAuth.mockReturnValueOnce({
+        isAuthenticated: true,
+        isLoading: false,
+        user: {
+          did: 'did:plc:user-test-001',
+          handle: 'test.bsky.social',
+          displayName: 'Test User',
+          avatarUrl: null,
+          role: 'moderator',
+        } as Record<string, unknown> | null,
+        getAccessToken: (() => 'mock-access-token') as () => string | null,
+        login: vi.fn(),
+        logout: vi.fn(),
+        setSessionFromCallback: vi.fn(),
+        authFetch: vi.fn(),
+        crossPostScopesGranted: false,
+        requestCrossPostAuth: vi.fn(),
+      })
+
+      render(<TopicDetailClient topic={topic} replies={replies} />)
+      expect(screen.getByRole('group', { name: 'Moderation actions' })).toBeInTheDocument()
+    })
+
+    it('renders moderation controls for admins', () => {
+      mockUseAuth.mockReturnValueOnce({
+        isAuthenticated: true,
+        isLoading: false,
+        user: {
+          did: 'did:plc:user-test-001',
+          handle: 'test.bsky.social',
+          displayName: 'Test User',
+          avatarUrl: null,
+          role: 'admin',
+        } as Record<string, unknown> | null,
+        getAccessToken: (() => 'mock-access-token') as () => string | null,
+        login: vi.fn(),
+        logout: vi.fn(),
+        setSessionFromCallback: vi.fn(),
+        authFetch: vi.fn(),
+        crossPostScopesGranted: false,
+        requestCrossPostAuth: vi.fn(),
+      })
+
+      render(<TopicDetailClient topic={topic} replies={replies} />)
+      expect(screen.getByRole('group', { name: 'Moderation actions' })).toBeInTheDocument()
+    })
+
+    it('does not render moderation controls for regular users', () => {
+      render(<TopicDetailClient topic={topic} replies={replies} />)
+      expect(screen.queryByRole('group', { name: 'Moderation actions' })).not.toBeInTheDocument()
+    })
+
+    it('calls pinTopic API when pin action is triggered', async () => {
+      mockUseAuth.mockReturnValueOnce({
+        isAuthenticated: true,
+        isLoading: false,
+        user: {
+          did: 'did:plc:user-test-001',
+          handle: 'test.bsky.social',
+          displayName: 'Test User',
+          avatarUrl: null,
+          role: 'moderator',
+        } as Record<string, unknown> | null,
+        getAccessToken: (() => 'mock-access-token') as () => string | null,
+        login: vi.fn(),
+        logout: vi.fn(),
+        setSessionFromCallback: vi.fn(),
+        authFetch: vi.fn(),
+        crossPostScopesGranted: false,
+        requestCrossPostAuth: vi.fn(),
+      })
+
+      const user = userEvent.setup()
+      render(<TopicDetailClient topic={topic} replies={replies} />)
+
+      // Click Pin button to open confirmation dialog
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      // Confirm the action
+      await user.click(screen.getByRole('button', { name: /confirm/i }))
+
+      await vi.waitFor(() => {
+        expect(mockPinTopic).toHaveBeenCalledWith(
+          topic.uri,
+          { scope: 'category' },
+          'mock-access-token'
+        )
+      })
+    })
+
+    it('calls lockTopic API when lock action is triggered', async () => {
+      mockUseAuth.mockReturnValueOnce({
+        isAuthenticated: true,
+        isLoading: false,
+        user: {
+          did: 'did:plc:user-test-001',
+          handle: 'test.bsky.social',
+          displayName: 'Test User',
+          avatarUrl: null,
+          role: 'moderator',
+        } as Record<string, unknown> | null,
+        getAccessToken: (() => 'mock-access-token') as () => string | null,
+        login: vi.fn(),
+        logout: vi.fn(),
+        setSessionFromCallback: vi.fn(),
+        authFetch: vi.fn(),
+        crossPostScopesGranted: false,
+        requestCrossPostAuth: vi.fn(),
+      })
+
+      const user = userEvent.setup()
+      render(<TopicDetailClient topic={topic} replies={replies} />)
+
+      // Click Lock button to open confirmation dialog
+      await user.click(screen.getByRole('button', { name: /lock topic/i }))
+      // Confirm the action
+      await user.click(screen.getByRole('button', { name: /confirm/i }))
+
+      await vi.waitFor(() => {
+        expect(mockLockTopic).toHaveBeenCalledWith(topic.uri, {}, 'mock-access-token')
+      })
+    })
+
+    it('refreshes router after successful moderation action', async () => {
+      mockUseAuth.mockReturnValueOnce({
+        isAuthenticated: true,
+        isLoading: false,
+        user: {
+          did: 'did:plc:user-test-001',
+          handle: 'test.bsky.social',
+          displayName: 'Test User',
+          avatarUrl: null,
+          role: 'moderator',
+        } as Record<string, unknown> | null,
+        getAccessToken: (() => 'mock-access-token') as () => string | null,
+        login: vi.fn(),
+        logout: vi.fn(),
+        setSessionFromCallback: vi.fn(),
+        authFetch: vi.fn(),
+        crossPostScopesGranted: false,
+        requestCrossPostAuth: vi.fn(),
+      })
+
+      const user = userEvent.setup()
+      render(<TopicDetailClient topic={topic} replies={replies} />)
+
+      // Click Pin button to open confirmation dialog, then confirm
+      await user.click(screen.getByRole('button', { name: /pin topic/i }))
+      await user.click(screen.getByRole('button', { name: /confirm/i }))
+
+      await vi.waitFor(() => {
+        expect(mockRouterRefresh).toHaveBeenCalled()
+      })
+    })
+  })
+
   describe('accessibility', () => {
     it('passes axe accessibility check when authenticated', async () => {
       const { container } = render(<TopicDetailClient topic={topic} replies={replies} />)
···
     })
 
     it('passes axe accessibility check when locked', async () => {
-      const { container } = render(<TopicDetailClient topic={topic} replies={replies} isLocked />)
+      const { container } = render(<TopicDetailClient topic={lockedTopic} replies={replies} />)
       const results = await axe(container)
       expect(results).toHaveNoViolations()
     })

src/components/topic-detail-client.tsx

···
 import { useAuth } from '@/hooks/use-auth'
 import type { Reply, Topic } from '@/lib/api/types'
 import { getTopicUrl } from '@/lib/format'
+import { pinTopic, lockTopic, deleteTopicMod } from '@/lib/api/client'
+import type { ModerationAction, ModerationActionOptions } from '@/components/moderation-controls'
 import { TopicView } from '@/components/topic-view'
 import { ReplyThread } from '@/components/reply-thread'
 import {
···
 interface TopicDetailClientProps {
   topic: Topic
   replies: Reply[]
-  isLocked?: boolean
 }
 
-export function TopicDetailClient({ topic, replies, isLocked = false }: TopicDetailClientProps) {
-  const { user, isAuthenticated, isLoading } = useAuth()
+export function TopicDetailClient({ topic, replies }: TopicDetailClientProps) {
+  const { user, isAuthenticated, isLoading, getAccessToken } = useAuth()
   const router = useRouter()
+
+  const isLocked = topic.isLocked
+  const isModerator = user?.role === 'moderator' || user?.role === 'admin'
+  const isAdmin = user?.role === 'admin'
+
+  const handleModerationAction = useCallback(
+    async (action: ModerationAction, options?: ModerationActionOptions) => {
+      const token = getAccessToken()
+      if (!token) return
+
+      try {
+        switch (action) {
+          case 'pin':
+            await pinTopic(topic.uri, { scope: options?.scope ?? 'category' }, token)
+            break
+          case 'unpin':
+            await pinTopic(topic.uri, {}, token)
+            break
+          case 'lock':
+          case 'unlock':
+            await lockTopic(topic.uri, {}, token)
+            break
+          case 'delete':
+            await deleteTopicMod(topic.uri, { reason: 'Moderator action' }, token)
+            break
+        }
+        router.refresh()
+      } catch (err) {
+        // Client-side error logging for failed moderation actions
+        console.error('Moderation action failed:', err)
+      }
+    },
+    [topic.uri, getAccessToken, router]
+  )
 
   const canEdit = isAuthenticated && user?.did === topic.authorDid
   const handleEdit = useCallback(() => {
···
           topic={topic}
           canEdit={canEdit}
           onEdit={handleEdit}
+          isModerator={isModerator}
+          isAdmin={isAdmin}
+          isPinned={topic.isPinned}
+          isLocked={isLocked}
+          onModerationAction={isModerator ? handleModerationAction : undefined}
           onReply={
             isAuthenticated && !isLocked
               ? () =>

src/components/topic-list.test.tsx

···
 import { render, screen } from '@testing-library/react'
 import { TopicList } from './topic-list'
 import { mockTopics } from '@/mocks/data'
+import type { Topic } from '@/lib/api/types'
+
+const baseTopic: Topic = { ...mockTopics[0]! }
 
 describe('TopicList', () => {
   it('renders all topics', () => {
···
   it('renders with heading', () => {
     render(<TopicList topics={mockTopics} heading="Recent Topics" />)
     expect(screen.getByRole('heading', { name: 'Recent Topics' })).toBeInTheDocument()
+  })
+
+  it('should render "Pinned" heading when there are pinned topics', () => {
+    const topics: Topic[] = [
+      {
+        ...baseTopic,
+        uri: 'at://did:plc:test/forum.barazo.topic.post/p1',
+        rkey: 'p1',
+        isPinned: true,
+        pinnedScope: 'category',
+        pinnedAt: '2026-03-01T00:00:00Z',
+      },
+      {
+        ...baseTopic,
+        uri: 'at://did:plc:test/forum.barazo.topic.post/r1',
+        rkey: 'r1',
+        isPinned: false,
+        pinnedScope: null,
+        pinnedAt: null,
+      },
+    ]
+    render(<TopicList topics={topics} />)
+    expect(screen.getByText('Pinned')).toBeInTheDocument()
+    expect(screen.getByText('Topics')).toBeInTheDocument()
+  })
+
+  it('should not render section headings when no pinned topics', () => {
+    const topics: Topic[] = [
+      {
+        ...baseTopic,
+        uri: 'at://did:plc:test/forum.barazo.topic.post/r1',
+        rkey: 'r1',
+        isPinned: false,
+        pinnedScope: null,
+        pinnedAt: null,
+      },
+    ]
+    render(<TopicList topics={topics} />)
+    expect(screen.queryByText('Pinned')).not.toBeInTheDocument()
+    expect(screen.queryByText('Topics')).not.toBeInTheDocument()
+  })
+
+  it('should render a separator between pinned and regular topics', () => {
+    const topics: Topic[] = [
+      {
+        ...baseTopic,
+        uri: 'at://did:plc:test/forum.barazo.topic.post/p1',
+        rkey: 'p1',
+        isPinned: true,
+        pinnedScope: 'category',
+        pinnedAt: '2026-03-01T00:00:00Z',
+      },
+      {
+        ...baseTopic,
+        uri: 'at://did:plc:test/forum.barazo.topic.post/r1',
+        rkey: 'r1',
+        isPinned: false,
+        pinnedScope: null,
+        pinnedAt: null,
+      },
+    ]
+    render(<TopicList topics={topics} />)
+    expect(screen.getByRole('separator')).toBeInTheDocument()
+  })
+
+  it('should render only pinned section when all topics are pinned', () => {
+    const topics: Topic[] = [
+      {
+        ...baseTopic,
+        uri: 'at://did:plc:test/forum.barazo.topic.post/p1',
+        rkey: 'p1',
+        isPinned: true,
+        pinnedScope: 'category',
+        pinnedAt: '2026-03-01T00:00:00Z',
+      },
+      {
+        ...baseTopic,
+        uri: 'at://did:plc:test/forum.barazo.topic.post/p2',
+        rkey: 'p2',
+        isPinned: true,
+        pinnedScope: 'forum',
+        pinnedAt: '2026-03-02T00:00:00Z',
+      },
+    ]
+    render(<TopicList topics={topics} />)
+    expect(screen.getByText('Pinned')).toBeInTheDocument()
+    // No regular topics section needed, but separator and "Topics" heading still render for consistency
+    const articles = screen.getAllByRole('article')
+    expect(articles).toHaveLength(2)
   })
 })

src/components/topic-list.tsx

···
 /**
  * TopicList - Paginated list of TopicCard components.
  * Renders topics with optional heading and empty state.
+ * Separates pinned topics from regular topics with section headings.
  * @see specs/prd-web.md Section 4 (Topic Components)
  */
 
···
 }
 
 export function TopicList({ topics, heading }: TopicListProps) {
+  const pinnedTopics = topics.filter((t) => t.isPinned)
+  const regularTopics = topics.filter((t) => !t.isPinned)
+  const hasPinned = pinnedTopics.length > 0
+
   return (
     <section>
       {heading && <h2 className="mb-4 text-xl font-semibold text-foreground">{heading}</h2>}
···
         </div>
       ) : (
         <div className="space-y-3">
-          {topics.map((topic) => (
+          {hasPinned && (
+            <>
+              <h3 className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                Pinned
+              </h3>
+              {pinnedTopics.map((topic) => (
+                <TopicCard key={topic.uri} topic={topic} />
+              ))}
+              <div className="border-b border-border" role="separator" />
+              <h3 className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                Topics
+              </h3>
+            </>
+          )}
+          {regularTopics.map((topic) => (
             <TopicCard key={topic.uri} topic={topic} />
           ))}
         </div>

src/components/topic-view.tsx

···
 import { MarkdownContent } from './markdown-content'
 import { LikeButton } from './like-button'
 import { ReactionBar } from './reaction-bar'
-import { ModerationControls, type ModerationAction } from './moderation-controls'
+import {
+  ModerationControls,
+  type ModerationAction,
+  type ModerationActionOptions,
+} from './moderation-controls'
 import { ReportDialog, type ReportSubmission } from './report-dialog'
 import { SelfLabelIndicator } from './self-label-indicator'
 
···
   reactions?: ReactionData[]
   onReactionToggle?: (type: string) => void
   isModerator?: boolean
+  isAdmin?: boolean
   isLocked?: boolean
   isPinned?: boolean
-  onModerationAction?: (action: ModerationAction) => void
+  onModerationAction?: (action: ModerationAction, options?: ModerationActionOptions) => void
   canEdit?: boolean
   onEdit?: () => void
   onReply?: () => void
···
   reactions,
   onReactionToggle,
   isModerator,
+  isAdmin,
   isLocked,
   isPinned,
   onModerationAction,
···
           <div className="mt-3">
             <ModerationControls
               isModerator={true}
+              isAdmin={isAdmin}
               isLocked={isLocked}
               isPinned={isPinned}
               onAction={onModerationAction}

src/lib/api/client.ts

···
   })
 }
 
+// --- Moderation action endpoints ---
+
+export interface PinTopicResponse {
+  uri: string
+  isPinned: boolean
+  pinnedScope: 'category' | 'forum' | null
+  pinnedAt: string | null
+}
+
+export function pinTopic(
+  topicUri: string,
+  params: { scope?: 'category' | 'forum'; reason?: string } = {},
+  accessToken: string,
+  options?: FetchOptions
+): Promise<PinTopicResponse> {
+  return apiFetch<PinTopicResponse>(`/api/moderation/pin/${encodeURIComponent(topicUri)}`, {
+    ...options,
+    method: 'POST',
+    headers: { ...options?.headers, Authorization: `Bearer ${accessToken}` },
+    body: params,
+  })
+}
+
+export interface LockTopicResponse {
+  uri: string
+  isLocked: boolean
+}
+
+export function lockTopic(
+  topicUri: string,
+  params: { reason?: string } = {},
+  accessToken: string,
+  options?: FetchOptions
+): Promise<LockTopicResponse> {
+  return apiFetch<LockTopicResponse>(`/api/moderation/lock/${encodeURIComponent(topicUri)}`, {
+    ...options,
+    method: 'POST',
+    headers: { ...options?.headers, Authorization: `Bearer ${accessToken}` },
+    body: params,
+  })
+}
+
+export function deleteTopicMod(
+  topicUri: string,
+  params: { reason: string },
+  accessToken: string,
+  options?: FetchOptions
+): Promise<{ uri: string }> {
+  return apiFetch<{ uri: string }>(`/api/moderation/delete/${encodeURIComponent(topicUri)}`, {
+    ...options,
+    method: 'POST',
+    headers: { ...options?.headers, Authorization: `Bearer ${accessToken}` },
+    body: params,
+  })
+}
+
 export { ApiError }

src/lib/api/types.ts

···
   reactionCount: number
   isAuthorDeleted: boolean
   isModDeleted: boolean
+  isPinned: boolean
+  isLocked: boolean
+  pinnedScope: 'category' | 'forum' | null
+  pinnedAt: string | null
   categoryMaturityRating: MaturityRating
   lastActivityAt: string
   createdAt: string

src/mocks/data.ts

···
     reactionCount: 12,
     isAuthorDeleted: false,
     isModDeleted: false,
+    isPinned: false,
+    isLocked: false,
+    pinnedScope: null,
+    pinnedAt: null,
     categoryMaturityRating: 'safe',
     lastActivityAt: NOW,
     createdAt: TWO_DAYS_AGO,
···
     reactionCount: 23,
     isAuthorDeleted: false,
     isModDeleted: false,
+    isPinned: false,
+    isLocked: false,
+    pinnedScope: null,
+    pinnedAt: null,
     categoryMaturityRating: 'safe',
     lastActivityAt: YESTERDAY,
     createdAt: TWO_DAYS_AGO,
···
     reactionCount: 7,
     isAuthorDeleted: false,
     isModDeleted: false,
+    isPinned: false,
+    isLocked: false,
+    pinnedScope: null,
+    pinnedAt: null,
     categoryMaturityRating: 'safe',
     lastActivityAt: YESTERDAY,
     createdAt: YESTERDAY,
···
     reactionCount: 31,
     isAuthorDeleted: false,
     isModDeleted: false,
+    isPinned: false,
+    isLocked: false,
+    pinnedScope: null,
+    pinnedAt: null,
     categoryMaturityRating: 'safe',
     lastActivityAt: NOW,
     createdAt: YESTERDAY,
···
     reactionCount: 9,
     isAuthorDeleted: false,
     isModDeleted: false,
+    isPinned: false,
+    isLocked: false,
+    pinnedScope: null,
+    pinnedAt: null,
     categoryMaturityRating: 'safe',
     lastActivityAt: NOW,
     createdAt: NOW,
···
   reactionCount: 0,
   isAuthorDeleted: true,
   isModDeleted: false,
+  isPinned: false,
+  isLocked: false,
+  pinnedScope: null,
+  pinnedAt: null,
   categoryMaturityRating: 'safe',
   lastActivityAt: YESTERDAY,
   createdAt: YESTERDAY,
···
   reactionCount: 0,
   isAuthorDeleted: false,
   isModDeleted: true,
+  isPinned: false,
+  isLocked: false,
+  pinnedScope: null,
+  pinnedAt: null,
   categoryMaturityRating: 'safe',
   lastActivityAt: NOW,
   createdAt: NOW,