@blogmcp/community 0.2.0 → 0.3.0

package/src/ui/TopicView.vue

@@ -0,0 +1,395 @@
+<script lang="ts">
+/** A refused age band, per element (as the discussion's: kb-api keeps nothing of it, §7.4.2). */
+const refusedAges = new WeakMap<object, number>()
+</script>
+
+<script setup lang="ts">
+/**
+ * `<blogmcp-topic conversation-id>` (m3-contracts.md §3.1–§3.5, §5.3): one forum topic — the discussion's view reused
+ * over the topic's thread (its messages, replies two levels deep, reactions, the composer, edits, reports, blocks, the
+ * onboarding with the art. 9 consent a forum write needs, live updates through the `realtime` property or the head
+ * poll), read with the forum's words, under the topic's header: its title (a deleted opening post reads „Smazané
+ * téma", a title withheld from this viewer its own words), closed, archived or pinned, its category, the follow button
+ * and, for a moderator of its category, the moderator's menu (close or reopen, pin, move; on a message: remove, pass to
+ * the team). A closed topic says so where the composer was; away mode and the forum's pause read one sentence each. The
+ * forum is for its members: anyone else reads one sentence and the way in; a topic the viewer may not see reads as
+ * not found; a forum switched off renders nothing. Dispatches `bcm-posted` as the discussion does.
+ */
+import { computed, nextTick, onBeforeUnmount, onMounted, reactive, ref, shallowRef, useHost, watch } from 'vue'
+import {
+  categoryPath,
+  communityMessageAnchor,
+  communityMessageSeqFromHash,
+  statementPath,
+  topicTitleOf,
+  type CommunityTransport,
+  type DiscussionMessage,
+  type DiscussionRestriction,
+} from '@blogmcp/sdk/community'
+import { parseRoutes, routesWithDefaults } from '../core/attrs'
+import { communityClientFor, siteBaseFor, warnOnce } from '../core/client'
+import { formatDate } from '../core/format'
+import { forumNoticesOf, pausedKey } from '../core/forum-state'
+import { FORUM_WORDS } from '../core/forum-words'
+import { documentLang, pickLang, type Lang } from '../core/i18n'
+import { failureText } from '../core/outcomes'
+import type { TopicRealtime } from '../core/realtime'
+import { createTopicController, type TopicController } from '../core/topic'
+import ConfirmDialog from './ConfirmDialog.vue'
+import FollowToggle from './FollowToggle.vue'
+import ForumNotices from './ForumNotices.vue'
+import MembersOnly from './MembersOnly.vue'
+import MessageComposer from './MessageComposer.vue'
+import MessageItem from './MessageItem.vue'
+import MessageMenu from './MessageMenu.vue'
+import ModeratorDialog from './ModeratorDialog.vue'
+import OnboardingSteps from './OnboardingSteps.vue'
+import ReportDialog from './ReportDialog.vue'
+import { provideText, uid } from './context'
+import { provideDiscussion } from './discussion-context'
+import type { MenuItem } from './types'
+
+defineOptions({ inheritAttrs: false })
+
+const props = defineProps<{
+  /** The topic's conversation id. */
+  conversationId?: string
+  apiBase?: string
+  siteBase?: string
+  lang?: string
+  signInHref?: string
+  /** JSON (or an object): the host's pages — `forumPath`, `categoryPath`, `topicPath`, `rulesPath`, `myCommunityPath`, … */
+  routes?: string | Record<string, unknown>
+  /** Head poll interval in ms (default 20 000; 0 = off). */
+  pollMs?: number
+  transport?: CommunityTransport
+  /** Live updates — `createRealtimeSession` of `@blogmcp/sdk/community/realtime`, a property. Absent: the head poll. */
+  realtime?: TopicRealtime
+}>()
+
+const host = useHost()
+const lang = ref<Lang>(pickLang(props.lang, documentLang()))
+const { t, text } = provideText(lang, FORUM_WORDS)
+watch(
+  () => props.lang,
+  (v) => {
+    lang.value = pickLang(v, documentLang())
+  },
+)
+
+const headingId = uid('bcm-topic')
+const heading = ref<HTMLElement | null>(null)
+const generation = ref(0)
+const current = shallowRef<TopicController | null>(null)
+const siteBase = computed(() => siteBaseFor(props.siteBase))
+const client = computed(() => (siteBase.value === null ? null : communityClientFor(props.apiBase, props.transport, siteBase.value)))
+
+function create(): TopicController | null {
+  const conversationId = props.conversationId?.trim()
+  if (!conversationId) {
+    warnOnce('conversation-id', '[blogmcp-community] <blogmcp-topic> needs a conversation-id')
+    return null
+  }
+  if (!client.value) return null
+  return createTopicController({
+    client: client.value,
+    conversationId,
+    lang: lang.value,
+    pollMs: props.pollMs,
+    realtime: typeof props.realtime === 'function' ? props.realtime : null,
+    refusedAge: (host && refusedAges.get(host)) ?? null,
+    onAgeRefused: (minAge) => {
+      if (host) refusedAges.set(host, minAge)
+    },
+    onPosted: (state) => host?.dispatchEvent(new CustomEvent('bcm-posted', { detail: { state }, bubbles: true, composed: true })),
+  })
+}
+
+const opened = reactive(new Set<number>())
+const originals = reactive(new Set<number>())
+const allReplies = reactive(new Set<number>())
+const deleting = ref<number | null>(null)
+
+const ctl = computed(() => current.value)
+const thread = computed(() => current.value?.thread ?? null)
+const state = computed(() => current.value?.thread.state ?? null)
+const routes = computed(() => routesWithDefaults(parseRoutes(props.routes), state.value?.me?.links, siteBase.value ?? ''))
+
+/** A moderator's items of a message's menu (another member's live message in this topic). */
+function extraMenu(m: DiscussionMessage): MenuItem[] {
+  if (!current.value?.canModerate(m)) return []
+  return [
+    { id: 'mod-remove', label: t('moderation.remove'), danger: true },
+    { id: 'mod-escalate', label: t('moderation.escalate') },
+  ]
+}
+
+provideDiscussion({
+  get ctl() {
+    return current.value!.thread
+  },
+  routes,
+  opened,
+  originals,
+  allReplies,
+  focusHeading: () => heading.value,
+  deleteMessage: (seq) => {
+    deleting.value = seq
+  },
+  extraMenu,
+  onExtraMenu: (id, m) => {
+    if (id === 'mod-remove') current.value?.openDialog('remove', m.seq)
+    else if (id === 'mod-escalate') current.value?.openDialog('escalate', m.seq)
+  },
+})
+
+let observer: IntersectionObserver | null = null
+const section = ref<HTMLElement | null>(null)
+let anchored = false
+
+/** A link to one message (`#bcm-msg-<seq>`, topicMessageLink): scrolled into view once the first page is in. */
+async function scrollToAnchor(): Promise<void> {
+  if (anchored || typeof location === 'undefined') return
+  anchored = true
+  const seq = communityMessageSeqFromHash(location.hash)
+  const anchor = seq === null ? null : communityMessageAnchor(seq)
+  if (seq === null || anchor === null) return
+  const parent = state.value?.thread.messages.find((m) => m.replies.some((r) => r.seq === seq))
+  if (parent) allReplies.add(parent.seq)
+  await nextTick()
+  const row = section.value?.querySelector<HTMLElement>(`#${anchor}`)
+  if (typeof row?.scrollIntoView === 'function') row.scrollIntoView({ block: 'start' })
+}
+
+function start(): void {
+  anchored = false
+  current.value?.dispose()
+  opened.clear()
+  originals.clear()
+  allReplies.clear()
+  deleting.value = null
+  current.value = create()
+  generation.value += 1
+  void current.value?.start()
+}
+
+onMounted(() => {
+  start()
+  if (host && typeof IntersectionObserver !== 'undefined') {
+    observer = new IntersectionObserver((entries) => {
+      const e = entries[entries.length - 1]
+      if (e) current.value?.thread.setInView(e.isIntersecting)
+    }, { rootMargin: '200px' })
+    observer.observe(host)
+  }
+})
+watch(() => [props.conversationId, props.apiBase, siteBase.value, props.transport, props.realtime, props.pollMs, lang.value] as const, () => start())
+onBeforeUnmount(() => {
+  observer?.disconnect()
+  current.value?.dispose()
+  current.value = null
+})
+
+watch(
+  () => state.value?.phase,
+  (phase) => {
+    if (phase === 'ready') void scrollToAnchor()
+  },
+)
+
+const topic = computed(() => state.value?.thread.topic ?? null)
+const title = computed(() => (state.value ? topicTitleOf(state.value.thread) : null))
+const titleText = computed(() => {
+  const ti = title.value
+  if (!ti) return ''
+  return ti.kind === 'shown' ? ti.text : t(ti.kind === 'deleted' ? 'topic.deleted' : 'topic.withheld')
+})
+const categoryHref = computed(() => (topic.value?.category ? categoryPath(routes.value.categoryPath, topic.value.category.slug) : null))
+const mode = computed(() => thread.value?.mode() ?? 'pending')
+/** The pause's sentence where the composer was: the module's, or the forum's own (never the article discussions'). */
+const pausedText = computed(() => {
+  const notices = forumNoticesOf(state.value?.me ?? null)
+  return pausedKey(notices.paused ?? 'forum')
+})
+const composer = ref<InstanceType<typeof MessageComposer> | null>(null)
+watch(mode, (now, before) => {
+  if (now === 'write' && before === 'onboarding') void nextTick(() => composer.value?.focus())
+  if (now === 'ageRefused' && before === 'onboarding') void nextTick(() => heading.value?.focus())
+})
+const needKey = computed(() => {
+  const n = thread.value?.needs()
+  return n?.onboarding ? 'need.onboarding' : n?.rules ? 'need.reconsent_rules' : 'need.art9_consent'
+})
+
+/** The topic's moderator menu (close or reopen, pin or unpin, move). */
+const moderatorItems = computed<MenuItem[]>(() => {
+  const c = current.value
+  const tp = topic.value
+  if (!c || !tp || !c.isModerator()) return []
+  const items: MenuItem[] = []
+  if (tp.state === 'open') items.push({ id: 'lock', label: t('moderation.lock') })
+  else if (tp.state === 'locked') items.push({ id: 'unlock', label: t('moderation.unlock') })
+  items.push(tp.pinned ? { id: 'unpin', label: t('moderation.unpin') } : { id: 'pin', label: t('moderation.pin') })
+  items.push({ id: 'move', label: t('moderation.move') })
+  return items
+})
+function onModerator(id: string): void {
+  const c = current.value
+  if (!c) return
+  if (id === 'lock' || id === 'unlock') void c.setState(id === 'lock' ? 'locked' : 'open')
+  else if (id === 'pin' || id === 'unpin') void c.setPinned(id === 'pin')
+  else if (id === 'move') c.openDialog('move')
+}
+
+function sanctionText(r: DiscussionRestriction): string {
+  const date = r.endsAt ? formatDate(lang.value, r.endsAt) : ''
+  if (r.kind === 'ban') return t('sanction.ban')
+  if (r.kind === 'suspension') return date ? t('sanction.suspensionUntil', { date }) : t('sanction.suspension')
+  return date ? t('sanction.restrictionUntil', { date }) : t('sanction.restriction')
+}
+
+const loadFailure = computed(() => {
+  const f = state.value?.failure
+  if (!f) return ''
+  const r = failureText(f, lang.value)
+  return t(r.key, r.params)
+})
+
+// One live region for the thread's and the topic's outcomes; the same outcome twice is announced twice.
+const liveText = ref('')
+function announceNow(next: string): void {
+  liveText.value = ''
+  void nextTick(() => {
+    liveText.value = next
+  })
+}
+watch(
+  () => state.value?.announceId,
+  () => announceNow(text(state.value?.announcement)),
+)
+watch(
+  () => current.value?.extras.announceId,
+  () => announceNow(text(current.value?.extras.announcement)),
+)
+
+async function confirmDelete(): Promise<void> {
+  const seq = deleting.value
+  if (seq === null || !thread.value) return
+  await thread.value.remove(seq)
+  deleting.value = null
+}
+</script>
+
+<template>
+  <section v-if="ctl && thread && state && state.phase !== 'hidden'" ref="section" :key="generation" class="bcm bcm-topic" :lang="lang" :aria-labelledby="headingId">
+    <nav class="bcm-row">
+      <a v-if="categoryHref && topic?.category" :href="categoryHref">{{ topic.category.name }}</a>
+      <a v-else :href="routes.forumPath">{{ t('forum.back') }}</a>
+    </nav>
+
+    <p v-if="state.phase === 'loading'" :id="headingId" class="bcm-muted" role="status">{{ t('topic.loading') }}</p>
+
+    <div v-else-if="state.phase === 'membersOnly' && client" :id="headingId">
+      <MembersOnly :failure="state.failure" :client="client" :lang="lang" :sign-in-href="signInHref" :rules-href="routes.rulesPath" @joined="thread.refresh()" />
+    </div>
+
+    <p v-else-if="state.phase === 'notFound'" :id="headingId" class="bcm-note">{{ t('topic.notFound') }}</p>
+
+    <div v-else-if="state.phase === 'failed'" class="bcm-banner" role="alert">
+      <span :id="headingId">{{ loadFailure }}</span>
+      <button type="button" class="bcm-btn" @click="thread.refresh()">{{ t('common.retry') }}</button>
+    </div>
+
+    <template v-else>
+      <header class="bcm-head">
+        <h2 :id="headingId" ref="heading" tabindex="-1" :class="{ 'bcm-placeholder': title?.kind !== 'shown' }">{{ titleText }}</h2>
+        <span v-if="topic?.pinned" class="bcm-badge">{{ t('topic.pinned') }}</span>
+        <span v-if="topic?.state === 'locked'" class="bcm-badge">{{ t('topic.locked') }}</span>
+        <span v-else-if="topic?.state === 'archived'" class="bcm-badge">{{ t('topic.archived') }}</span>
+        <span class="bcm-count">{{ t('topic.count', { count: state.thread.count }) }}</span>
+        <span class="bcm-spacer" />
+        <FollowToggle v-if="ctl.follow && state.thread.viewer.memberId !== null" :ctl="ctl.follow" />
+        <MessageMenu v-if="moderatorItems.length" :items="moderatorItems" :label="t('moderation.title')" @select="onModerator" />
+      </header>
+
+      <ForumNotices :me="state.me" />
+
+      <div v-if="state.newMessages" class="bcm-banner" role="status">
+        <span>{{ t('discussion.newMessages') }}</span>
+        <button type="button" class="bcm-btn" :disabled="state.refreshing" @click="thread.refresh()">{{ t('discussion.refresh') }}</button>
+      </div>
+
+      <p v-if="state.realtimeOff" class="bcm-hint" role="status">{{ t('realtime.off') }}</p>
+
+      <ol class="bcm-thread">
+        <MessageItem v-for="m in state.thread.messages" :key="m.id" :message="m" />
+      </ol>
+      <p v-if="state.thread.messages.length <= 1" class="bcm-muted">{{ t('discussion.empty') }}</p>
+
+      <div v-if="state.thread.nextCursor !== null" class="bcm-row">
+        <button type="button" class="bcm-btn" :disabled="state.loadingMore" @click="thread.loadMore()">{{ t('discussion.loadMore') }}</button>
+      </div>
+
+      <div class="bcm-section">
+        <p v-if="mode === 'write' && state.art9RefusedNote" class="bcm-hint">{{ t('onboarding.art9RefusedDone') }}</p>
+        <MessageComposer
+          v-if="mode === 'write'"
+          ref="composer"
+          kind="new"
+          :draft="state.composer"
+          :wait="thread.waitLeft(state.composer)"
+          :rules-href="routes.rulesPath"
+          :mentions-max="thread.mentionCap()"
+          @submit="thread.submit()"
+          @confirm="(code: string, checked: boolean) => thread && thread.setConfirmed(state!.composer, code, checked)"
+          @confirmed="thread.sendConfirmed(state.composer)"
+        />
+        <p v-else-if="mode === 'locked'" class="bcm-note">{{ t('error.topicLocked') }}</p>
+        <p v-else-if="mode === 'readOnly'" class="bcm-note">{{ t('error.readOnly') }}</p>
+        <template v-else-if="mode === 'onboarding'">
+          <OnboardingSteps v-if="thread.onboarding.value" :model="thread.onboarding.value" :rules-href="routes.rulesPath" @cancel="thread.cancelOnboarding()" />
+          <div v-else class="bcm-row">
+            <p>{{ t(needKey) }}</p>
+            <button type="button" class="bcm-btn bcm-primary" @click="thread.beginOnboarding()">{{ t('onboarding.continue') }}</button>
+          </div>
+        </template>
+        <p v-else-if="mode === 'ageRefused'" class="bcm-note">{{ t('onboarding.ageBelow', { min: state.refusedAge ?? 18 }) }}</p>
+        <div v-else-if="mode === 'sanction'" class="bcm-section">
+          <p v-for="r in state.thread.viewer.restrictions" :key="r.decisionId" class="bcm-note">
+            {{ sanctionText(r) }}
+            <a v-if="statementPath(routes.statementPath, r.decisionId)" :href="statementPath(routes.statementPath, r.decisionId) ?? undefined">{{ t('sanction.statement') }}</a>
+          </p>
+        </div>
+        <p v-else-if="mode === 'braked' && pausedText" class="bcm-note" role="status">{{ t(pausedText) }}</p>
+        <p v-else-if="mode === 'restricted'" class="bcm-note">
+          {{ t('error.restricted') }}
+          <a :href="routes.myCommunityPath">{{ t('panel.title') }}</a>
+        </p>
+      </div>
+    </template>
+
+    <p class="bcm-sr" aria-live="polite">{{ liveText }}</p>
+
+    <ReportDialog
+      v-if="state.report"
+      :report="state.report"
+      :my-community-href="routes.myCommunityPath"
+      :rules-href="routes.rulesPath"
+      :fallback-focus="() => heading"
+      @submit="thread.submitReport()"
+      @close="thread.closeReport()"
+    />
+    <ConfirmDialog
+      v-if="deleting !== null"
+      title="discussion.deleteTitle"
+      explain="discussion.deleteExplain"
+      confirm="discussion.deleteConfirm"
+      danger
+      :busy="!!state.busy[`delete:${deleting}`]"
+      :fallback-focus="() => heading"
+      @confirm="confirmDelete()"
+      @cancel="deleting = null"
+    />
+    <ModeratorDialog v-if="ctl.extras.dialog" :ctl="ctl" :fallback-focus="() => heading" @close="ctl.closeDialog()" />
+  </section>
+</template>

package/src/ui/context.ts

@@ -3,7 +3,7 @@
  * `communityMessage` and nothing else), ids unique to the element, and the dialog's focus handling.
  */
 import { inject, nextTick, onBeforeUnmount, onMounted, provide, type InjectionKey, type Ref } from 'vue'
-import { communityMessage } from '@blogmcp/sdk/community'
+import { communityMessage, type CommunityMessageKey } from '@blogmcp/sdk/community'
 import type { Lang, TextRef, Translate } from '../core/i18n'
 
 export interface TextContext {
@@ -15,9 +15,14 @@ export interface TextContext {
 
 const TEXT: InjectionKey<TextContext> = Symbol('bcm-text')
 
-export function provideText(lang: Ref<Lang>): TextContext {
+/**
+ * The element's texts. `words` (M3) maps a key the shared components name to another key of the catalogue — a topic's
+ * thread reads the discussion's components with the forum's words (`composer.label` → `forumText.composer.label`, a
+ * post, not a comment) — and a plural key maps by its name without the suffix.
+ */
+export function provideText(lang: Ref<Lang>, words?: Readonly<Partial<Record<CommunityMessageKey, CommunityMessageKey>>>): TextContext {
   // Reads lang.value on every call, so a view that renders a text re-renders when the language changes.
-  const t: Translate = (key, params) => communityMessage(lang.value, key, params)
+  const t: Translate = (key, params) => communityMessage(lang.value, words?.[key] ?? key, params)
   const ctx: TextContext = { lang, t, text: (ref) => (ref ? t(ref.key, ref.params) : '') }
   provide(TEXT, ctx)
   return ctx

package/src/ui/discussion-context.ts

@@ -1,10 +1,15 @@
-/** What the discussion's components share: the controller, the host's routes, what the reader opened. */
+/**
+ * What the discussion's components share: the controller, the host's routes, what the reader opened — M3: under a
+ * topic too (`<blogmcp-topic>` provides its thread's controller, and the moderator's items of a message's menu).
+ */
 import { inject, provide, type ComputedRef, type InjectionKey } from 'vue'
-import type { DiscussionController } from '../core/discussion'
+import type { DiscussionMessage } from '@blogmcp/sdk/community'
+import type { ThreadController } from '../core/discussion'
 import type { routesWithDefaults } from '../core/attrs'
+import type { MenuItem } from './types'
 
 export interface DiscussionContext {
-  ctl: DiscussionController
+  ctl: ThreadController
   routes: ComputedRef<ReturnType<typeof routesWithDefaults>>
   /** Messages of a blocked author the reader opened anyway. */
   opened: Set<number>
@@ -15,6 +20,9 @@ export interface DiscussionContext {
   /** Where the focus goes when the element it came from is gone (a deleted message). */
   focusHeading(): HTMLElement | null
   deleteMessage(seq: number): void
+  /** M3: more items of a message's menu (a category moderator's), and what picking one does. */
+  extraMenu?(m: DiscussionMessage): MenuItem[]
+  onExtraMenu?(id: string, m: DiscussionMessage): void
 }
 
 const KEY: InjectionKey<DiscussionContext> = Symbol('bcm-discussion')

package/src/ui/styles.css

@@ -257,3 +257,17 @@ span.bcm-react { cursor: default; }
   .bcm-dialog[open] { animation: bcm-in 140ms ease-out; }
   @keyframes bcm-in { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
 }
+
+/* ── M3: the forum (its index, a category, a topic, search, the follow button, the moderator's queue) ── */
+:host(blogmcp-follow-button) { display: inline-block; }
+.bcm-follow-host { display: inline-flex; }
+.bcm-follow { display: inline-flex; align-items: center; gap: 6px; }
+/* Following: a thicker border and bold, not colour alone. */
+.bcm-follow .bcm-btn[aria-pressed='true'] { border: 2px solid var(--bcm-accent); font-weight: 650; }
+.bcm-grow { flex: 1; min-width: 0; }
+.bcm-select { width: auto; max-width: 100%; }
+.bcm-category { gap: 8px; }
+.bcm-topics { list-style: none; display: flex; flex-direction: column; }
+.bcm-topic-row { border-bottom: 1px solid var(--bcm-line); padding: 8px 0; display: flex; flex-direction: column; gap: 4px; }
+.bcm-topic-row:last-child { border-bottom: 0; }
+.bcm-topic-title { font-weight: 650; }

package/src/vue.ts

@@ -1,6 +1,7 @@
 /**
- * `<KbDiscussion>`, `<KbNoticeForm>`, `<KbMyCommunity>` and (M2) `<KbNotificationCentre>`, `<KbBadge>`,
- * `<KbMemberSettings>`, `<KbProfile>`, `<KbWelcome>` for Vue / Nuxt: each mounts its element on the
+ * `<KbDiscussion>`, `<KbNoticeForm>`, `<KbMyCommunity>`, (M2) `<KbNotificationCentre>`, `<KbBadge>`,
+ * `<KbMemberSettings>`, `<KbProfile>`, `<KbWelcome>` and (M3) `<KbForum>`, `<KbForumCategory>`, `<KbTopic>`,
+ * `<KbForumSearch>`, `<KbFollowButton>`, `<KbForumModeration>` for Vue / Nuxt: each mounts its element on the
  * client, after hydration, and removes it on unmount. Each renders one empty `<div>` as the mount point —
  * nothing else, on the server or the client — so the element sits where the component does and the page's
  * markup is otherwise the site's alone.
@@ -13,15 +14,21 @@
 import { defineComponent, h, onBeforeUnmount, onMounted, ref, watch, type PropType } from 'vue'
 import type { CommunityTransport } from '@blogmcp/sdk/community'
 import type { CommunityRoutes } from './core/attrs'
-import type { DiscussionRealtime } from './core/realtime'
+import type { DiscussionRealtime, TopicRealtime } from './core/realtime'
 import type {
   MountBadgeOptions,
   MountDiscussionOptions,
+  MountFollowButtonOptions,
+  MountForumCategoryOptions,
+  MountForumModerationOptions,
+  MountForumOptions,
+  MountForumSearchOptions,
   MountMemberSettingsOptions,
   MountMyCommunityOptions,
   MountNoticeFormOptions,
   MountNotificationCentreOptions,
   MountProfileOptions,
+  MountTopicOptions,
   MountWelcomeOptions,
 } from './mount'
 
@@ -228,6 +235,134 @@ export const KbWelcome = defineComponent({
   },
 })
 
+// ───────────────────────── M3: the forum (m3-contracts.md §5.3) ─────────────────────────
+
+export const KbForum = defineComponent({
+  name: 'KbForum',
+  props: {
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    signInHref: String,
+    routes: Object as PropType<CommunityRoutes>,
+    nonce: String,
+    transport: Function as PropType<CommunityTransport>,
+  },
+  setup(props) {
+    return useMount<MountForumOptions>(
+      'forum',
+      () => defined({ ...props }) as MountForumOptions,
+      async () => (await import('./mount')).mountForum as Mounter<MountForumOptions>,
+    )
+  },
+})
+
+export const KbForumCategory = defineComponent({
+  name: 'KbForumCategory',
+  props: {
+    slug: { type: String, required: true },
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    signInHref: String,
+    routes: Object as PropType<CommunityRoutes>,
+    nonce: String,
+    transport: Function as PropType<CommunityTransport>,
+  },
+  setup(props) {
+    return useMount<MountForumCategoryOptions>(
+      'forum-category',
+      () => defined({ ...props }) as MountForumCategoryOptions,
+      async () => (await import('./mount')).mountForumCategory as Mounter<MountForumCategoryOptions>,
+    )
+  },
+})
+
+export const KbTopic = defineComponent({
+  name: 'KbTopic',
+  props: {
+    conversationId: { type: String, required: true },
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    signInHref: String,
+    routes: Object as PropType<CommunityRoutes>,
+    pollMs: Number,
+    nonce: String,
+    transport: Function as PropType<CommunityTransport>,
+    /** `createRealtimeSession` of `@blogmcp/sdk/community/realtime`. */
+    realtime: Function as PropType<TopicRealtime>,
+  },
+  setup(props) {
+    return useMount<MountTopicOptions>(
+      'topic',
+      () => defined({ ...props }) as MountTopicOptions,
+      async () => (await import('./mount')).mountTopic as Mounter<MountTopicOptions>,
+    )
+  },
+})
+
+export const KbForumSearch = defineComponent({
+  name: 'KbForumSearch',
+  props: {
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    signInHref: String,
+    routes: Object as PropType<CommunityRoutes>,
+    nonce: String,
+    transport: Function as PropType<CommunityTransport>,
+  },
+  setup(props) {
+    return useMount<MountForumSearchOptions>(
+      'forum-search',
+      () => defined({ ...props }) as MountForumSearchOptions,
+      async () => (await import('./mount')).mountForumSearch as Mounter<MountForumSearchOptions>,
+    )
+  },
+})
+
+export const KbFollowButton = defineComponent({
+  name: 'KbFollowButton',
+  props: {
+    targetKind: { type: String as PropType<'conversation' | 'category'>, required: true },
+    targetId: { type: String, required: true },
+    following: { type: Boolean, default: undefined },
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    nonce: String,
+    transport: Function as PropType<CommunityTransport>,
+  },
+  setup(props) {
+    return useMount<MountFollowButtonOptions>(
+      'follow-button',
+      () => defined({ ...props }) as MountFollowButtonOptions,
+      async () => (await import('./mount')).mountFollowButton as Mounter<MountFollowButtonOptions>,
+    )
+  },
+})
+
+export const KbForumModeration = defineComponent({
+  name: 'KbForumModeration',
+  props: {
+    categoryId: String,
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    routes: Object as PropType<CommunityRoutes>,
+    nonce: String,
+    transport: Function as PropType<CommunityTransport>,
+  },
+  setup(props) {
+    return useMount<MountForumModerationOptions>(
+      'forum-moderation',
+      () => defined({ ...props }) as MountForumModerationOptions,
+      async () => (await import('./mount')).mountForumModeration as Mounter<MountForumModerationOptions>,
+    )
+  },
+})
+
 export type {
   MountDiscussionOptions,
   MountNoticeFormOptions,
@@ -237,6 +372,13 @@ export type {
   MountMemberSettingsOptions,
   MountProfileOptions,
   MountWelcomeOptions,
+  MountForumOptions,
+  MountForumCategoryOptions,
+  MountTopicOptions,
+  MountForumSearchOptions,
+  MountFollowButtonOptions,
+  MountForumModerationOptions,
   CommunityRoutes,
   DiscussionRealtime,
+  TopicRealtime,
 }