@actuate-media/cms-admin 0.11.0 → 0.12.1

package/src/lib/collaboration-provider.ts

@@ -0,0 +1,306 @@
+/**
+ * Browser-side Yjs collaboration provider for the TipTap editor.
+ *
+ * Wraps `y-websocket`'s `WebsocketProvider` with sensible defaults and a
+ * narrow public API. The wire protocol is byte-compatible with the
+ * cms-core realtime gateway shipped in PR #106, so the standard
+ * `WebsocketProvider` connects without any custom client code.
+ *
+ * Auth flows through the browser's cookie jar — `cms-admin` already uses
+ * cookie-based sessions, and the WebSocket upgrade request carries those
+ * cookies automatically against same-origin gateways. For cross-origin
+ * deployments, attach a query-string token via the `params` option.
+ */
+import { Awareness } from 'y-protocols/awareness'
+import { WebsocketProvider } from 'y-websocket'
+import { IndexeddbPersistence } from 'y-indexeddb'
+import * as Y from 'yjs'
+
+/** Connection status reported via `onStatus` and surfaced in the editor UI. */
+export type CollaborationStatus = 'connecting' | 'connected' | 'disconnected'
+
+/**
+ * Offline-draft persistence status. Slice 6 layers a local IndexedDB
+ * mirror on top of the y-websocket transport so edits made while
+ * disconnected aren't lost. The lifecycle is:
+ *
+ * - `unsupported` — `indexedDB` is unavailable (Safari private mode,
+ *   SSR, jsdom-without-fake-indexeddb).
+ * - `pending` — provider is being constructed; no local state yet.
+ * - `loading` — IndexedDB is replaying the last saved snapshot into
+ *   the Y.Doc.
+ * - `ready` — the local store is initialised and every change is
+ *   persisted locally before the WebSocket pushes it upstream.
+ * - `error` — IndexedDB threw; the editor still works in-memory but
+ *   refresh will lose pending edits.
+ */
+export type OfflinePersistenceStatus = 'unsupported' | 'pending' | 'loading' | 'ready' | 'error'
+
+/** Per-user presence info that becomes the local awareness state. */
+export interface CollaborationUser {
+  /** Display name (used for cursor labels and the presence chip strip). */
+  name: string
+  /** CSS color value for the user's cursor / chip background. */
+  color: string
+  /** Optional avatar URL (32-square recommended). Rendered if present. */
+  avatarUrl?: string
+  /** Stable user id from the cms-core session (used as a dedup key). */
+  userId?: string
+}
+
+export interface CollaborationOptions {
+  /** Logical document id (becomes the y-websocket "room name"). */
+  documentId: string
+  /**
+   * Base URL of the realtime gateway, e.g. `wss://your.app/api/cms/realtime/sync`.
+   * The provider appends `/${documentId}` automatically (y-websocket convention).
+   * Use `ws://` for local dev.
+   */
+  url: string
+  /** Presence info for the local user. */
+  user: CollaborationUser
+  /**
+   * Extra query-string parameters (e.g. an auth token for cross-origin
+   * deployments). Forwarded to `WebsocketProvider`'s `params` option.
+   */
+  params?: Record<string, string>
+  /** Called on every connection-state transition. */
+  onStatus?: (status: CollaborationStatus) => void
+  /** Called on connection-level errors (e.g. 4401 auth rejection). */
+  onError?: (err: Error) => void
+  /**
+   * If `false`, the helper does not connect on construction. Useful for
+   * tests and for editors that want a `Y.Doc` without network traffic.
+   * Defaults to `true`.
+   */
+  connect?: boolean
+  /**
+   * Offline-draft persistence. When `true` (default), the provider
+   * mounts a `y-indexeddb` mirror so edits made while the WebSocket is
+   * disconnected survive a refresh. Pass `false` to skip the mirror
+   * (e.g. on shared kiosk machines where you don't want drafts in
+   * IndexedDB).
+   */
+  offline?: boolean
+  /** Called on every offline-persistence status transition. */
+  onOfflineStatus?: (status: OfflinePersistenceStatus) => void
+}
+
+export interface CollaborationContext {
+  /** Shared Y.Doc — bind this to the TipTap `Collaboration` extension. */
+  ydoc: Y.Doc
+  /** The underlying y-websocket provider. */
+  provider: WebsocketProvider
+  /** Awareness instance — bind to `CollaborationCursor` and the presence strip. */
+  awareness: Awareness
+  /**
+   * Local IndexedDB mirror, when `offline` is enabled and the runtime
+   * supports it. `null` when persistence is disabled or unsupported
+   * (e.g. SSR / Safari private browsing).
+   */
+  offlinePersistence: IndexeddbPersistence | null
+  /** Latest offline-persistence status. Mirrors `onOfflineStatus`. */
+  offlineStatus: OfflinePersistenceStatus
+  /** Stop the provider, evict awareness, and destroy the Y.Doc. */
+  destroy: () => void
+}
+
+/** Optional dependency-injection seam used by tests to avoid real WebSockets. */
+export interface CollaborationDeps {
+  WebsocketProviderCtor?: typeof WebsocketProvider
+  /**
+   * Override the IndexedDB persistence constructor (test seam). The
+   * default uses `y-indexeddb` which requires a browser-like
+   * `indexedDB` global; tests inject a no-op stub.
+   */
+  IndexeddbPersistenceCtor?: typeof IndexeddbPersistence
+  /**
+   * Override the IndexedDB feature check. Defaults to inspecting
+   * `globalThis.indexedDB`. Tests inject `() => true` to exercise the
+   * persistence path under happy-dom.
+   */
+  isIndexedDbSupported?: () => boolean
+}
+
+/**
+ * Open a collaboration session for `documentId`. Must be called in a browser
+ * context (jsdom is fine for tests when a fake provider is injected).
+ *
+ * The returned `ydoc` is the document the editor binds to via TipTap's
+ * `Collaboration` extension; `awareness` carries cursor + presence state.
+ * Always call `destroy()` on unmount to evict the local awareness state and
+ * close the socket.
+ */
+export function createCollaborationProvider(
+  opts: CollaborationOptions,
+  deps: CollaborationDeps = {},
+): CollaborationContext {
+  if (
+    typeof globalThis === 'undefined' ||
+    typeof (globalThis as { window?: unknown }).window === 'undefined'
+  ) {
+    // Note: jsdom defines `window`, so this only trips on bare-Node SSR.
+    throw new Error(
+      'createCollaborationProvider can only be called in a browser context (window is undefined)',
+    )
+  }
+  if (!opts.documentId || !opts.url) {
+    throw new Error('createCollaborationProvider requires both documentId and url')
+  }
+
+  const Ctor = deps.WebsocketProviderCtor ?? WebsocketProvider
+  const ydoc = new Y.Doc()
+  const provider = new Ctor(opts.url, opts.documentId, ydoc, {
+    connect: opts.connect ?? true,
+    params: opts.params,
+  })
+
+  // Layer y-indexeddb on top of the y-websocket transport for offline
+  // drafts. Both providers share the same Y.Doc, so they automatically
+  // converge: IndexedDB hydrates the doc on load, the websocket pushes
+  // pending updates to the gateway on reconnect.
+  const offlineEnabled = opts.offline !== false
+  const offlineCheck = deps.isIndexedDbSupported ?? defaultIndexedDbSupportCheck
+  let offlineStatus: OfflinePersistenceStatus = 'pending'
+  const setOfflineStatus = (next: OfflinePersistenceStatus) => {
+    offlineStatus = next
+    opts.onOfflineStatus?.(next)
+  }
+  let offlinePersistence: IndexeddbPersistence | null = null
+  if (!offlineEnabled) {
+    setOfflineStatus('unsupported')
+  } else if (!offlineCheck()) {
+    setOfflineStatus('unsupported')
+  } else {
+    setOfflineStatus('loading')
+    const PersistenceCtor = deps.IndexeddbPersistenceCtor ?? IndexeddbPersistence
+    try {
+      offlinePersistence = new PersistenceCtor(
+        // Namespace the IndexedDB key by documentId so multiple docs in
+        // the same admin session don't collide.
+        `actuate-cms:${opts.documentId}`,
+        ydoc,
+      )
+      // `whenSynced` is the canonical "snapshot replay finished" hook
+      // from y-indexeddb (https://github.com/yjs/y-indexeddb).
+      offlinePersistence.whenSynced
+        .then(() => setOfflineStatus('ready'))
+        .catch((err: unknown) => {
+          opts.onError?.(err instanceof Error ? err : new Error('Offline persistence failed'))
+          setOfflineStatus('error')
+        })
+    } catch (err) {
+      opts.onError?.(err instanceof Error ? err : new Error('Offline persistence failed'))
+      setOfflineStatus('error')
+      offlinePersistence = null
+    }
+  }
+
+  // Seed local awareness with the user's presence info. The
+  // `CollaborationCursor` TipTap extension reads `user.name` + `user.color`
+  // out of awareness state and renders cursors accordingly.
+  provider.awareness.setLocalState({
+    user: {
+      name: opts.user.name,
+      color: opts.user.color,
+      avatarUrl: opts.user.avatarUrl,
+      userId: opts.user.userId,
+    },
+  })
+
+  if (opts.onStatus) {
+    const handler = (event: { status: string }) => {
+      const status = normaliseStatus(event.status)
+      if (status) opts.onStatus!(status)
+    }
+    provider.on('status', handler)
+  }
+  if (opts.onError) {
+    const handler = () => {
+      // y-websocket emits this on socket close + on protocol errors. We
+      // surface a generic Error so callers can render a toast without
+      // sniffing y-websocket internals.
+      opts.onError!(new Error('Realtime connection error'))
+    }
+    provider.on('connection-error', handler)
+  }
+
+  const destroy = () => {
+    try {
+      provider.awareness.setLocalState(null)
+    } catch {
+      /* awareness may already be torn down */
+    }
+    try {
+      provider.destroy()
+    } catch {
+      /* idempotent */
+    }
+    if (offlinePersistence) {
+      try {
+        // y-indexeddb keeps the IDB connection open until `destroy()`;
+        // we don't drop the stored data (that's the point of offline
+        // drafts), but we close the handle so the runtime can GC.
+        offlinePersistence.destroy()
+      } catch {
+        /* idempotent */
+      }
+    }
+    try {
+      ydoc.destroy()
+    } catch {
+      /* idempotent */
+    }
+  }
+
+  return {
+    ydoc,
+    provider,
+    awareness: provider.awareness,
+    offlinePersistence,
+    get offlineStatus() {
+      return offlineStatus
+    },
+    destroy,
+  }
+}
+
+function defaultIndexedDbSupportCheck(): boolean {
+  return (
+    typeof globalThis !== 'undefined' &&
+    typeof (globalThis as { indexedDB?: unknown }).indexedDB !== 'undefined'
+  )
+}
+
+function normaliseStatus(value: string): CollaborationStatus | null {
+  if (value === 'connected') return 'connected'
+  if (value === 'connecting') return 'connecting'
+  if (value === 'disconnected') return 'disconnected'
+  return null
+}
+
+/**
+ * Reduce an Awareness map into a deduplicated array of `CollaborationUser`s.
+ * Used by `PresenceChips` and any other UI that visualises co-editors.
+ */
+export interface PresenceSnapshot {
+  /** Local user's client id (so UIs can omit themselves from the strip). */
+  selfClientId: number
+  /** Connected users, deduplicated by `userId` when present, otherwise by clientId. */
+  users: Array<{ clientId: number; user: CollaborationUser }>
+}
+
+export function summarisePresence(awareness: Awareness): PresenceSnapshot {
+  const seenUserIds = new Set<string>()
+  const users: PresenceSnapshot['users'] = []
+  for (const [clientId, state] of awareness.getStates()) {
+    const user = (state as { user?: CollaborationUser })?.user
+    if (!user || typeof user.name !== 'string') continue
+    if (user.userId) {
+      if (seenUserIds.has(user.userId)) continue
+      seenUserIds.add(user.userId)
+    }
+    users.push({ clientId, user })
+  }
+  return { selfClientId: awareness.clientID, users }
+}

package/src/lib/comment-anchor.ts

@@ -0,0 +1,179 @@
+/**
+ * Comment anchor helpers — convert between Yjs **relative positions** and
+ * the Base64 wire format the comments REST API speaks.
+ *
+ * Why relative positions: storing absolute offsets (e.g. char 42–58) is
+ * fatal under concurrent editing because someone inserting text before
+ * char 42 silently shifts the meaning of every saved anchor. Yjs ships
+ * `createRelativePositionFromTypeIndex` /
+ * `createAbsolutePositionFromRelativePosition` for exactly this case —
+ * they identify a slot in the CRDT graph that survives concurrent edits.
+ *
+ * The wire shape is `{ from: string; to: string }` where each end is the
+ * Base64 of `Y.encodeRelativePosition(rel)`. The slice 4 server treats
+ * the field as opaque; this module is the only place in the workspace
+ * that interprets it.
+ *
+ * ## Choosing the right Yjs type to anchor against
+ *
+ * `createRelativePositionFromTypeIndex(type, index)` interprets `index`
+ * differently depending on the type:
+ *
+ * - `Y.XmlText` / `Y.Text` — index is the character offset within the
+ *   text. **This is what comment anchors use** because character offsets
+ *   are the natural unit for a text selection.
+ * - `Y.XmlFragment` / `Y.XmlElement` — index counts *children*. Useful
+ *   for "before/after this child" anchors but not what we want here.
+ *
+ * Slice 5's TipTap binding maps a PM selection to the underlying
+ * `Y.XmlText` instance + character offset before calling `encodeAnchor`,
+ * and inverts that mapping after `decodeAnchor` returns. The y-prosemirror
+ * plugin keeps a `mapping` for this conversion; consumers that aren't
+ * using y-prosemirror can talk to the Y types directly.
+ */
+
+import * as Y from 'yjs'
+
+import type { CommentAnchor } from './comments-client.js'
+
+export interface CreateAnchorInput {
+  /** Live Yjs document the editor is bound to. */
+  doc: Y.Doc
+  /**
+   * Yjs text type the selection lives in. Almost always a `Y.XmlText`
+   * for TipTap; we keep the bound a little loose so plain `Y.Text` works
+   * for non-rich-text editors.
+   */
+  yType: Y.XmlText | Y.Text
+  /** Character offset (inclusive) of the selection start within `yType`. */
+  from: number
+  /** Character offset (exclusive) of the selection end within `yType`. */
+  to: number
+}
+
+/**
+ * Build a comment anchor from an editor selection. Returns `null` when
+ * the range is empty or inverted — the caller should not save anchors
+ * that would resolve to nothing.
+ */
+export function encodeAnchor(input: CreateAnchorInput): CommentAnchor | null {
+  if (input.from >= input.to) return null
+  if (input.from < 0) return null
+  // `createRelativePositionFromTypeIndex` clamps `index` to `[0, type.length]`
+  // internally, but we surface an explicit failure when the *intent* is
+  // out of bounds so the caller can flag a stale selection.
+  if (input.to > input.yType.length) return null
+
+  const relFrom = Y.createRelativePositionFromTypeIndex(input.yType, input.from)
+  const relTo = Y.createRelativePositionFromTypeIndex(input.yType, input.to)
+
+  return {
+    from: encodeBase64(Y.encodeRelativePosition(relFrom)),
+    to: encodeBase64(Y.encodeRelativePosition(relTo)),
+  }
+}
+
+export interface ResolveAnchorInput {
+  doc: Y.Doc
+  anchor: CommentAnchor
+}
+
+export interface ResolvedAnchor {
+  /**
+   * The text type the relative position landed on. Comparing identity
+   * (`resolved.yType === editorBoundText`) lets the caller decide
+   * whether a comment is still attached to the expected text node.
+   */
+  yType: Y.AbstractType<unknown>
+  /** Character offset of the saved selection start, after concurrent edits. */
+  from: number
+  /** Character offset of the saved selection end. */
+  to: number
+}
+
+/**
+ * Resolve a stored anchor back to live editor positions. Returns `null`
+ * when:
+ *
+ * - the anchor bytes are not valid base64 / not a Yjs relative position,
+ * - the relative position cannot be mapped (the anchored content was
+ *   deleted entirely), or
+ * - the two ends collapse to the same offset (text between them was
+ *   deleted, effectively detaching the comment).
+ *
+ * Slice 5 surfaces detached comments in the side panel with a small
+ * "anchor lost" badge so editors can still resolve / discuss them.
+ */
+export function decodeAnchor(input: ResolveAnchorInput): ResolvedAnchor | null {
+  let relFromBytes: Uint8Array
+  let relToBytes: Uint8Array
+  try {
+    relFromBytes = decodeBase64(input.anchor.from)
+    relToBytes = decodeBase64(input.anchor.to)
+  } catch {
+    return null
+  }
+
+  let relFrom: Y.RelativePosition
+  let relTo: Y.RelativePosition
+  try {
+    relFrom = Y.decodeRelativePosition(relFromBytes)
+    relTo = Y.decodeRelativePosition(relToBytes)
+  } catch {
+    return null
+  }
+
+  const absFrom = Y.createAbsolutePositionFromRelativePosition(relFrom, input.doc)
+  const absTo = Y.createAbsolutePositionFromRelativePosition(relTo, input.doc)
+  if (absFrom === null || absTo === null) return null
+
+  // Both ends must land on the same text node — otherwise the user's
+  // original selection has been split across nodes and we cannot paint
+  // a clean highlight without further work in slice 5.
+  if (absFrom.type !== absTo.type) return null
+
+  if (absFrom.index >= absTo.index) return null
+
+  return {
+    yType: absFrom.type,
+    from: absFrom.index,
+    to: absTo.index,
+  }
+}
+
+/**
+ * Base64 encode without depending on Node's `Buffer` (the admin bundle
+ * is browser-first). We hand-roll the encode because both `btoa` and
+ * `Buffer` have ergonomic mis-fits for `Uint8Array` payloads.
+ */
+function encodeBase64(bytes: Uint8Array): string {
+  if (typeof btoa === 'function') {
+    let binary = ''
+    for (let i = 0; i < bytes.byteLength; i++) {
+      binary += String.fromCharCode(bytes[i]!)
+    }
+    return btoa(binary)
+  }
+  const BufferCtor = (
+    globalThis as {
+      Buffer?: { from(arr: Uint8Array): { toString(enc: string): string } }
+    }
+  ).Buffer
+  if (BufferCtor) return BufferCtor.from(bytes).toString('base64')
+  throw new Error('No base64 encoder available')
+}
+
+function decodeBase64(s: string): Uint8Array {
+  if (typeof atob === 'function') {
+    const binary = atob(s)
+    const out = new Uint8Array(binary.length)
+    for (let i = 0; i < binary.length; i++) {
+      out[i] = binary.charCodeAt(i)
+    }
+    return out
+  }
+  const BufferCtor = (globalThis as { Buffer?: { from(s: string, enc: string): Uint8Array } })
+    .Buffer
+  if (BufferCtor) return new Uint8Array(BufferCtor.from(s, 'base64'))
+  throw new Error('No base64 decoder available')
+}

package/src/lib/comments-client.ts

@@ -0,0 +1,208 @@
+/**
+ * Comments REST client — thin, typed wrapper around the
+ * `/documents/:id/comments` + `/comments/:id` endpoints shipped in slice 4
+ * of Phase 3 (see `packages/cms-core/src/realtime/comments.ts`).
+ *
+ * The client lives in `cms-admin` so the side panel, the bubble-menu
+ * "comment on selection" action, and any future MCP/AI hooks all share one
+ * request path, error model, and DTO shape.
+ *
+ * Mirrors the server contract:
+ *   POST   /documents/:documentId/comments     -> { body, anchor?, parentId? }
+ *   GET    /documents/:documentId/comments?…   -> { data: CommentDTO[] }
+ *   PATCH  /comments/:id                       -> { body }
+ *   POST   /comments/:id/resolve               -> 200 with updated DTO
+ *   POST   /comments/:id/reopen                -> 200 with updated DTO
+ *   DELETE /comments/:id                       -> 200 with soft-deleted DTO
+ */
+
+import { cmsApi } from './api.js'
+
+/**
+ * Yjs relative-position anchor returned by the server. The encoding is
+ * intentionally opaque on the wire (Base64 of `Y.encodeRelativePosition`);
+ * `lib/comment-anchor.ts` handles the round-trip when slice 5 paints a
+ * highlight in the editor.
+ */
+export interface CommentAnchor {
+  from: string
+  to: string
+}
+
+/**
+ * Public DTO returned by every comments endpoint. Mirrors `CommentDTO` in
+ * `@actuate-media/cms-core/realtime`; we duplicate the shape here so
+ * `cms-admin` doesn't take a hard dependency on the server-side service
+ * layer (which carries Prisma types we don't want pulled into the bundle).
+ */
+export interface Comment {
+  id: string
+  documentId: string
+  parentId: string | null
+  userId: string | null
+  body: string
+  anchor: CommentAnchor | null
+  resolvedAt: string | null
+  resolvedById: string | null
+  deletedAt: string | null
+  createdAt: string
+  updatedAt: string
+  isResolved: boolean
+}
+
+export type CommentOutcome<T> =
+  | { ok: true; result: T }
+  | { ok: false; error: string; status: number }
+
+export interface CreateCommentInput {
+  documentId: string
+  body: string
+  anchor?: CommentAnchor | null
+  parentId?: string | null
+}
+
+export interface ListCommentsOptions {
+  /** Default: false. Resolved threads are filtered out unless requested. */
+  includeResolved?: boolean
+  /** Default: false. Admin-only; the server rejects non-admin callers. */
+  includeDeleted?: boolean
+  /** Default: server-side cap (100). Hard upper bound is 200. */
+  pageSize?: number
+}
+
+function encodeOptions(opts: ListCommentsOptions = {}): string {
+  const params = new URLSearchParams()
+  if (opts.includeResolved) params.set('includeResolved', 'true')
+  if (opts.includeDeleted) params.set('includeDeleted', 'true')
+  if (opts.pageSize !== undefined) params.set('pageSize', String(opts.pageSize))
+  const qs = params.toString()
+  return qs ? `?${qs}` : ''
+}
+
+function failure(error: string, status: number): { ok: false; error: string; status: number } {
+  return { ok: false, error, status }
+}
+
+function envelope<T>(res: { data?: unknown; error?: string; status: number }): CommentOutcome<T> {
+  if (res.error || res.data === undefined) {
+    return failure(res.error ?? `Request failed (${res.status})`, res.status)
+  }
+  return { ok: true, result: res.data as T }
+}
+
+/**
+ * Create a top-level comment or a reply. Pass `parentId` to thread the
+ * comment under an existing one — the server enforces single-level
+ * threading (replies cannot themselves be parents).
+ */
+export async function createComment(input: CreateCommentInput): Promise<CommentOutcome<Comment>> {
+  if (typeof input.documentId !== 'string' || input.documentId.length === 0) {
+    return failure('documentId is required', 0)
+  }
+  if (typeof input.body !== 'string' || input.body.trim().length === 0) {
+    return failure('Comment cannot be empty', 0)
+  }
+
+  const body: Record<string, unknown> = { body: input.body.trim() }
+  if (input.anchor) body.anchor = input.anchor
+  if (input.parentId) body.parentId = input.parentId
+
+  const res = await cmsApi<Comment>(`/documents/${encodeURIComponent(input.documentId)}/comments`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * List comments for a document. Active comments (not resolved, not deleted)
+ * are returned by default; pass `includeResolved` to keep resolved threads
+ * in the response. The server rejects `includeDeleted` for non-admins.
+ */
+export async function listComments(
+  documentId: string,
+  opts: ListCommentsOptions = {},
+): Promise<CommentOutcome<Comment[]>> {
+  if (typeof documentId !== 'string' || documentId.length === 0) {
+    return failure('documentId is required', 0)
+  }
+  const path = `/documents/${encodeURIComponent(documentId)}/comments${encodeOptions(opts)}`
+  const res = await cmsApi<Comment[]>(path, { method: 'GET' })
+  return envelope<Comment[]>(res)
+}
+
+/** Edit a comment body. Only the author or an admin is permitted. */
+export async function updateComment(id: string, body: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  if (typeof body !== 'string' || body.trim().length === 0) {
+    return failure('Comment cannot be empty', 0)
+  }
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ body: body.trim() }),
+  })
+  return envelope<Comment>(res)
+}
+
+/** Resolve a thread. Write-role or the author may resolve. */
+export async function resolveComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}/resolve`, {
+    method: 'POST',
+    body: '{}',
+  })
+  return envelope<Comment>(res)
+}
+
+/** Re-open a resolved thread. Same permission as resolve. */
+export async function reopenComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}/reopen`, {
+    method: 'POST',
+    body: '{}',
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * Soft-delete a comment. The row is preserved so its replies don't lose
+ * their thread root — the server simply stops returning it from the list
+ * endpoint unless an admin asks for `includeDeleted`.
+ */
+export async function deleteComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * Sort comments into thread groups suitable for rendering. Roots are
+ * returned in chronological order; replies are ordered the same way and
+ * attached to their root. Replies whose root is missing (e.g. the root was
+ * filtered out by `includeResolved=false`) are dropped — the UI can fetch
+ * them explicitly if it needs to render orphaned replies.
+ */
+export interface CommentThread {
+  root: Comment
+  replies: Comment[]
+}
+
+export function groupCommentsIntoThreads(comments: readonly Comment[]): CommentThread[] {
+  const roots = new Map<string, CommentThread>()
+  const sorted = [...comments].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+
+  for (const c of sorted) {
+    if (c.parentId === null) {
+      roots.set(c.id, { root: c, replies: [] })
+    }
+  }
+  for (const c of sorted) {
+    if (c.parentId !== null) {
+      const root = roots.get(c.parentId)
+      if (root) root.replies.push(c)
+    }
+  }
+  return Array.from(roots.values())
+}