@blogmcp/community 0.1.0 → 0.3.0

package/src/core/discussion.ts

@@ -4,22 +4,41 @@
  * with its optimistic rows, the Russmedia confirmation and the cooldowns, reactions, blocks, reports, and the
  * inline onboarding. The element renders `controller.state`; tests drive it directly over a fake transport.
  *
+ * M3 (m3-contracts.md §5.3): the same brain under `<blogmcp-topic>` — a forum topic IS a discussion (its opening post is
+ * seq 1, its replies two levels deep), so createTopicThreadController runs every rule above over the SDK's topic store,
+ * `forum/topics/get` and `forum/topics/head`, posts by the topic's conversation id, and adds what a topic has of its
+ * own: a viewer the forum is not open to (`membersOnly`, with its `needs`) and a topic the viewer may not see
+ * (`notFound`) as states of the element, a write's `notFound` read again (settleTopicFailure: the forum's gate answers
+ * every refusal of a topic's id that way, A11), a closed topic, the forum's own brake beside the module's, the title of
+ * the opening post in its edit, and the art. 9 consent every forum write needs (U14). The article's own reactions are
+ * an article's only.
+ *
  * Every request goes through the SDK client (the host's relative base); nothing here builds a path.
  */
 import { reactive, shallowRef, type ShallowRef } from 'vue'
 import {
+  isKnownModuleState,
   COMMUNITY_MESSAGE_MAX,
   COMMUNITY_REPORT_NOTE_MAX,
+  communityMentionHandles,
   communityRulesOf,
   createDiscussionStore,
+  createTopicStore,
   findMessage,
+  forumTopicTitleOf,
   isOwnMessage,
+  isTopicOpen,
   loadMoreDiscussion,
+  loadMoreTopic,
   newClientMsgId,
   pollDiscussionHead,
+  pollTopicHead,
   reactionAfter,
   reactionsFor,
   refreshDiscussion,
+  refreshTopic,
+  settleTopicFailure,
+  surfaceInfoOf,
   viewerNeeds,
   type CaseCategory,
   type CommunityCallOptions,
@@ -31,18 +50,58 @@ import {
   type DiscussionMessage,
   type DiscussionState,
   type DiscussionStore,
+  type DiscussionViewer,
   type KnownAuthor,
+  type KnownBrakeSurface,
+  type MessageChange,
   type MyState,
+  type ReactionSummary,
   type ReactionTarget,
+  type RealtimeEvent,
+  type RealtimeEventOutcome,
+  type Topic,
+  type TopicHead,
+  type TopicStore,
+  type TopicStoreState,
   type ViewerNeeds,
 } from '@blogmcp/sdk/community'
 import { warnOnce } from './client'
 import type { Lang, TextRef } from './i18n'
 import { createOnboarding, type OnboardingModel } from './onboarding'
 import { failureEffect, failureText, waitUntilOf } from './outcomes'
+import type { DiscussionRealtime, DiscussionRealtimeSession, TopicRealtime } from './realtime'
 import { codePointLength, normalizeBody } from './text'
 
-export type DiscussionPhase = 'loading' | 'ready' | 'failed' | 'hidden'
+/**
+ * `membersOnly` (M3, a topic): the forum is not open to this viewer — `state.failure.needs` says what a member session
+ * still lacks (none: a visitor, sign in); `notFound` (M3, a topic): the topic is not there for this viewer.
+ */
+export type DiscussionPhase = 'loading' | 'ready' | 'failed' | 'hidden' | 'membersOnly' | 'notFound'
+
+/** What a discussion and a topic have in common, as the controller and the views read them (the SDK's two states). */
+export interface ThreadState {
+  readonly conversationId: string | null
+  readonly count: number
+  readonly lastSeq: number
+  readonly lastChangeAt: string | null
+  readonly messages: readonly DiscussionMessage[]
+  readonly nextCursor: number | null
+  readonly reactionSet: readonly string[]
+  readonly preset: string | null
+  readonly viewer: DiscussionViewer
+  readonly loaded: boolean
+  readonly stale: boolean
+}
+
+/** The store under a thread, as far as the controller uses it: a discussion's, or a topic's. */
+interface ThreadStore<S extends ThreadState> {
+  getState(): S
+  subscribe(listener: (state: S) => void): () => void
+  applyMessage(change: MessageChange): void
+  applyReaction(target: ReactionTarget, reactions: ReactionSummary): void
+  collapse(memberId: string, blocked: boolean): void
+  applyEvent(event: RealtimeEvent): RealtimeEventOutcome
+}
 
 /** One composer's text and what happened to it. */
 export interface Draft {
@@ -66,6 +125,11 @@ export interface InlineDraft extends Draft {
   seq: number
   /** A reply to a reply names whom it answers. */
   replyingTo: string | null
+  /**
+   * M3: the topic's title, on its author's edit of the opening post (seq 1) — sent with the body when it changed (one
+   * edit of the opening post, §2.5); null everywhere else.
+   */
+  title: string | null
 }
 
 export interface ReportDraft {
@@ -86,22 +150,44 @@ export interface ReportDraft {
  * onboarding waits); `ageRefused` (the age band declared in it was below the minimum: reading only, the
  * onboarding is not offered again); `sanction` (a restriction, suspension or ban in effect); `notMoved` (the
  * discussion takes no writes yet — one sentence); `restricted` (the member is read-only or deleting their
- * profile); `pending` (being decided).
+ * profile); `braked` (M2: the community is paused — `me/get`'s `module.brake`, or a write refused BRAKED: reading
+ * goes on, every member write waits — one sentence); `pending` (being decided).
+ *
+ * A module that is `read_only` changes nothing here (m2-contracts.md §3.1: the discussions under articles keep
+ * taking writes; only live updates, push and the Pro surfaces stop) — the discussion polls instead of a socket.
  */
-export type ComposerMode = 'write' | 'signIn' | 'onboarding' | 'ageRefused' | 'sanction' | 'notMoved' | 'restricted' | 'pending'
+export type ComposerMode =
+  | 'write'
+  | 'signIn'
+  | 'onboarding'
+  | 'ageRefused'
+  | 'sanction'
+  | 'notMoved'
+  | 'restricted'
+  | 'braked'
+  | 'pending'
+  /** M3, a topic: closed (`locked`, `archived`, or a state this SDK does not know) — the composer gives way to a sentence. */
+  | 'locked'
+  /** M3, a topic: the module is `read_only` — the forum is one of its features and takes no writes meanwhile. */
+  | 'readOnly'
+  /** M3, a topic: the viewer reads only (the team at the keyboard: it writes through the KB admin) — nothing is shown. */
+  | 'none'
 
-export interface DiscussionUi {
+export interface ThreadUi<S extends ThreadState> {
   phase: DiscussionPhase
-  /** Why the first load failed (`failed`). */
+  /** Why the first load failed (`failed`), or why the topic is not shown (`membersOnly`, `notFound`). */
   failure: CommunityFailure | null
-  thread: DiscussionState
+  thread: S
   loadingMore: boolean
   refreshing: boolean
   /** A head poll saw messages the page does not show yet. */
   newMessages: boolean
   me: MyState | null
-  /** What a write or the member's state taught: no writes yet, or none for this member. */
-  block: 'notMoved' | 'restricted' | null
+  /**
+   * What a write or the member's state taught: no writes yet, none for this member, or a pause (BRAKED); M3, a topic:
+   * the module is `read_only` (the forum is a Pro surface).
+   */
+  block: 'notMoved' | 'restricted' | 'braked' | 'readOnly' | null
   composer: Draft
   inline: InlineDraft | null
   report: ReportDraft | null
@@ -117,11 +203,24 @@ export interface DiscussionUi {
    * (§7.4.2), so the element does: the onboarding is not offered again while it lives.
    */
   refusedAge: number | null
+  /**
+   * M2 T9: the onboarding just finished with the art. 9 consent refused (`public_write`): the composer says once,
+   * in view, what the refusal leaves (writing in the public discussion). Not kept beyond this element.
+   */
+  art9RefusedNote: boolean
+  /**
+   * M2 (§3.5): the live updates' session fell back to polling (live updates are off here, or the server cut the
+   * socket for good — 4501): the discussion says so once and keeps polling; it never opens the socket again itself.
+   */
+  realtimeOff: boolean
 }
 
-export interface DiscussionControllerOptions {
+/** `<blogmcp-discussion>`'s state: an article's discussion. */
+export type DiscussionUi = ThreadUi<DiscussionState>
+
+/** What both controllers take besides what their thread is (an article, a topic). */
+interface ThreadControllerOptions {
   client: CommunityClient
-  articleId: string
   lang: Lang
   /** Head poll interval (default 20 s; 0 = no polling). */
   pollMs?: number
@@ -134,9 +233,25 @@ export interface DiscussionControllerOptions {
   onAgeRefused?(minAge: number): void
 }
 
-export interface DiscussionController {
-  readonly state: DiscussionUi
-  readonly store: DiscussionStore
+export interface DiscussionControllerOptions extends ThreadControllerOptions {
+  articleId: string
+  /**
+   * M2 (§3.5, §3.10): the host's live-updates session factory (`createRealtimeSession` of
+   * `@blogmcp/sdk/community/realtime`). Absent: the head poll, as before.
+   */
+  realtime?: DiscussionRealtime | null
+}
+
+/** M3: `<blogmcp-topic>`'s thread — a forum topic by its conversation id. */
+export interface TopicThreadControllerOptions extends ThreadControllerOptions {
+  conversationId: string
+  /** The host's live-updates session factory over the topic's store (`createRealtimeSession`). Absent: the head poll. */
+  realtime?: TopicRealtime | null
+}
+
+/** What a thread's controller does — the article's discussion's and a topic's alike; the views read it. */
+export interface ThreadController<S extends ThreadState = ThreadState> {
+  readonly state: ThreadUi<S>
   readonly onboarding: ShallowRef<OnboardingModel | null>
   /** The first load, then the poll. */
   start(): Promise<void>
@@ -172,26 +287,85 @@ export interface DiscussionController {
   openReport(m: DiscussionMessage): void
   closeReport(): void
   submitReport(): Promise<void>
-  beginOnboarding(): void
+  /**
+   * The onboarding inline; `offerArt9` asks the art. 9 consent also of a member who refused it (`public_write`, M2 T9) —
+   * the give-consent link on their own message held until the consent. M3, a topic: the art. 9 step is asked before a
+   * write whatever the tenant asks elsewhere (`forceArt9`, implied), but not to read the forum (`toRead`).
+   */
+  beginOnboarding(options?: OnboardingStart): void
   cancelOnboarding(): void
   /** Seconds a draft still waits (0 when it may go). */
   waitLeft(draft: Draft): number
+  /**
+   * M2 T10: the distinct `@handle`s one message of the viewer may carry (me/get's `caps.mentionsPerMessage`), or null
+   * when nothing is known to limit it (no member yet, an older kb-api, a module whose mentions notify nobody).
+   */
+  mentionCap(): number | null
+  /** M3: the edit of this message carries the topic's title (its author's opening post of a topic). */
+  editsTitle(m: Pick<DiscussionMessage, 'seq' | 'author'>): boolean
   dispose(): void
 }
 
+/** `<blogmcp-discussion>`'s controller: an article's discussion over the SDK's discussion store. */
+export interface DiscussionController extends ThreadController<DiscussionState> {
+  readonly store: DiscussionStore
+}
+
+/** M3: `<blogmcp-topic>`'s thread over the SDK's topic store (its header is `state.thread.topic`). */
+export interface TopicThreadController extends ThreadController<TopicStoreState> {
+  readonly store: TopicStore
+}
+
 const emptyDraft = (body = ''): Draft => ({ body, sending: false, failure: null, confirm: null, waitUntil: null, clientMsgId: null })
 
+const NO_REACTIONS: ReactionSummary = Object.freeze({ counts: Object.freeze({}), mine: null })
+
 const documentVisible = (): boolean => typeof document === 'undefined' || document.visibilityState !== 'hidden'
 
+/** The opening post of a topic (its title travels with it). */
+const OPENING_SEQ = 1
+
+/** How the inline onboarding starts (beginOnboarding). */
+export interface OnboardingStart {
+  /** The give-consent flow (M2 T9): the art. 9 step for a member who refused it, no refusal offered. */
+  offerArt9?: boolean
+  /** M3: the art. 9 step whatever the tenant asks elsewhere — a forum write's refusal named it (U14). */
+  forceArt9?: boolean
+  /** M3, a topic: the onboarding the forum asks only to be read (the members-only state) — no art. 9 step forced. */
+  toRead?: boolean
+}
+
+/** What the thread is: an article's discussion, or a forum topic. */
+type Subject = { readonly kind: 'article'; readonly id: string } | { readonly kind: 'topic'; readonly id: string }
+
+/** `<blogmcp-discussion>`'s controller over one article's discussion. */
 export function createDiscussionController(o: DiscussionControllerOptions): DiscussionController {
+  return createThread(o, { kind: 'article', id: o.articleId.toLowerCase() }, o.realtime ?? null) as unknown as DiscussionController
+}
+
+/** M3: `<blogmcp-topic>`'s thread over one forum topic (m3-contracts.md §3.1–§3.3, §5.3). */
+export function createTopicThreadController(o: TopicThreadControllerOptions): TopicThreadController {
+  return createThread(o, { kind: 'topic', id: o.conversationId.toLowerCase() }, o.realtime ?? null) as unknown as TopicThreadController
+}
+
+/** A session factory of either kind, as the thread calls it (the public options type each one). */
+type AnyRealtime = (options: never) => DiscussionRealtimeSession
+
+function createThread(o: ThreadControllerOptions, subject: Subject, realtime: AnyRealtime | null): ThreadController<ThreadState> & { store: ThreadStore<ThreadState> } {
   const { client, lang } = o
-  const articleId = o.articleId.toLowerCase()
+  const topicMode = subject.kind === 'topic'
+  /** An article's id or a topic's conversation id, lower case: what the heads and the posts name. */
+  const threadKey = subject.id
+  /** The surface whose own brake pauses this thread's writes (beside the module's, which pauses both). */
+  const surface: KnownBrakeSurface = topicMode ? 'forum' : 'article_discussions'
   const now = o.now ?? Date.now
-  const store = createDiscussionStore()
+  const discussionStore = topicMode ? null : createDiscussionStore()
+  const topicStore = topicMode ? createTopicStore() : null
+  const store = (discussionStore ?? topicStore) as unknown as ThreadStore<ThreadState>
   const abort = new AbortController()
   const call: CommunityCallOptions = { signal: abort.signal }
 
-  const state = reactive<DiscussionUi>({
+  const state = reactive<ThreadUi<ThreadState>>({
     phase: 'loading',
     failure: null,
     thread: store.getState(),
@@ -208,19 +382,28 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     clock: now(),
     busy: {},
     refusedAge: o.refusedAge ?? null,
-  }) as DiscussionUi
+    art9RefusedNote: false,
+    realtimeOff: false,
+  }) as ThreadUi<ThreadState>
   const unsubscribe = store.subscribe((s) => {
     state.thread = s
   })
   const onboarding = shallowRef<OnboardingModel | null>(null)
+  /** The open onboarding is the give-consent flow (read with `onboarding`, which it is set beside). */
+  let consentFlow = false
 
   let poller: DiscussionHeadPoller | null = null
+  let session: DiscussionRealtimeSession | null = null
   let inView = true
   let disposed = false
   let lastSync = 0
   let refreshing: Promise<void> | null = null
   let mePromise: Promise<void> | null = null
   let ticker: ReturnType<typeof setInterval> | null = null
+  /** The brake's end (its `until`, or a BRAKED refusal's): me/get is read again then. */
+  let brakeTimer: ReturnType<typeof setTimeout> | null = null
+  /** A BRAKED refusal's own end (epoch ms), while `state.block` is `braked` because of it; null: none given. */
+  let refusedBrakeUntil: number | null = null
   const interval = o.pollMs ?? 20_000
 
   function announce(text: TextRef): void {
@@ -232,35 +415,112 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     state.phase = 'hidden'
     poller?.stop()
     poller = null
+    session?.stop()
+    session = null
   }
 
   // ───────────────────────── loading ─────────────────────────
 
-  function ensureMe(): Promise<void> {
-    if (state.me) return Promise.resolve()
+  /** me/get once (`fresh`: again, keeping what is shown until the answer is in — the composer does not flicker). */
+  function ensureMe(fresh = false): Promise<void> {
+    if (state.me && !fresh) return Promise.resolve()
     mePromise ??= client.me.get(call).then((r) => {
       mePromise = null
-      if (r.ok && !disposed) state.me = r.value
+      if (!r.ok || disposed) return
+      state.me = r.value
+      scheduleBrakeEnd()
     })
     return mePromise
   }
 
-  /** canPost is false, nothing is needed and no sanction applies: the member's status says whether it is the cutover. */
+  /** This thread's surface's own brake as me/get states it (M3, §4.9: it always ends), or null. */
+  const surfaceBrakeOf = (me: MyState | null) => surfaceInfoOf(me?.module, surface)?.brake ?? null
+
+  /**
+   * The end of a brake as me/get states it (`module.brake.until`, or `module.until` of a braked module — and M3 this
+   * thread's surface's own brake, the later of the two), epoch ms.
+   */
+  function brakeEndOf(me: MyState | null): number | null {
+    const m = me?.module
+    if (!m) return null
+    const until = m.brake ? m.brake.until : isKnownModuleState(m.state) && m.state === 'braked' ? m.until : undefined
+    const at = typeof until === 'string' ? Date.parse(until) : NaN
+    const own = surfaceBrakeOf(me)
+    const ownAt = own ? Date.parse(own.until) : NaN
+    const ends = [at, ownAt].filter((x) => Number.isFinite(x))
+    return ends.length > 0 ? Math.max(...ends) : null
+  }
+
+  /**
+   * While the discussion is braked, a timer at the brake's end (the later of me/get's `until` and a refusal's): then
+   * me/get is read again and the composer comes back when the brake is over. A brake without an end waits for the
+   * next refresh (afterLoad reads me/get again while braked).
+   */
+  function scheduleBrakeEnd(): void {
+    if (brakeTimer) clearTimeout(brakeTimer)
+    brakeTimer = null
+    if (disposed) return
+    const ends: number[] = []
+    if (brakedNow()) {
+      const at = brakeEndOf(state.me)
+      if (at !== null) ends.push(at)
+    }
+    if (state.block === 'braked' && refusedBrakeUntil !== null) ends.push(refusedBrakeUntil)
+    if (ends.length === 0) return
+    // A second after the end (clocks differ by a little), within setTimeout's range; an end me/get still reports
+    // after it passed (the brake not lifted yet on kb-api's side) is asked again every 30 s, never in a tight loop.
+    const left = Math.max(...ends) - now()
+    const delay = left > 0 ? Math.min(left + 1000, 2_147_000_000) : 30_000
+    brakeTimer = setTimeout(() => {
+      brakeTimer = null
+      if (disposed) return
+      liftRefusedBrake()
+      void ensureMe(true)
+    }, delay)
+  }
+
+  /** A BRAKED refusal's block ends once its own end has passed (or it gave none): me/get decides from then on. */
+  function liftRefusedBrake(): void {
+    if (state.block !== 'braked') return
+    if (refusedBrakeUntil !== null && refusedBrakeUntil > now()) return
+    state.block = null
+    refusedBrakeUntil = null
+  }
+
+  /**
+   * canPost is false, nothing is needed and no sanction applies: a brake (M2 T10: kb-api's canPost is false while one
+   * is in effect — me/get, read again, names it, and the composer gives way to the brake's sentence), else the
+   * member's status says whether it is the cutover.
+   */
   function decideBlock(): void {
     const s = store.getState()
     if (s.viewer.canPost || viewerNeeds(s).any || s.viewer.restrictions.length > 0) return
-    void ensureMe().then(() => {
+    // M3, a topic: a closed topic or a reader who writes elsewhere (the team) says so by itself (mode()).
+    if (topicMode && (s.viewer.memberId === null || !topicIsOpen())) return
+    void ensureMe(state.block === null).then(() => {
       const me = state.me
       if (disposed || !me || store.getState().viewer.canPost) return
+      if (brakedNow()) return
+      if (topicMode) {
+        // The forum is a feature of the module: `read_only` closes it (§3.1 step 5); else the member is read-only.
+        state.block = isKnownModuleState(me.module?.state) && me.module?.state === 'read_only' ? 'readOnly' : me.member && me.member.status !== 'active' ? 'restricted' : null
+        return
+      }
       // An active member who may not post: the discussion takes no writes yet (the cutover).
       state.block = !me.member || me.member.status === 'active' ? 'notMoved' : 'restricted'
     })
   }
 
+  /** M3, a topic: it takes new messages (`open`; a closed or unknown state does not). Always for an article. */
+  const topicIsOpen = (): boolean => !topicMode || isTopicOpen(topicStore!.getState().topic)
+
   function afterLoad(): void {
     const s = store.getState()
-    if (s.viewer.canPost) state.block = null
-    if (s.viewer.memberId !== null) void ensureMe()
+    // A braked discussion asks me/get again on every refresh: the brake may be over (kb-api's canPost does not know it).
+    const wasBraked = state.block === 'braked' || brakedNow()
+    if (s.viewer.canPost && state.block !== 'braked') state.block = null
+    if (wasBraked) liftRefusedBrake()
+    if (s.viewer.memberId !== null) void ensureMe(wasBraked)
     decideBlock()
     // Finished elsewhere (another tab): nothing left to onboard.
     if (onboarding.value && !viewerNeeds(s).any && onboarding.value.state.phase !== 'sending') onboarding.value = null
@@ -268,6 +528,17 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   function loadFailed(f: CommunityFailure): void {
     if (f.code === 'surfaceOff') return hide()
+    if (topicMode && (f.code === 'membersOnly' || f.code === 'notFound')) {
+      // M3: the forum is not open to this viewer (the members-only sentence, with its sign-in or onboarding), or the
+      // topic is not there for them — whatever was shown before (a topic can stop being readable while it is open).
+      poller?.stop()
+      poller = null
+      session?.stop()
+      session = null
+      state.phase = f.code
+      state.failure = f
+      return
+    }
     if (f.code === 'notFound' && state.phase !== 'ready') {
       warnOnce('not-found', '[blogmcp-community] the discussion of this article-id was not found (no such live article, or it is not readable here)')
       return hide()
@@ -279,11 +550,17 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     // A loaded discussion keeps what it shows; the poll tries again.
   }
 
+  /** The thread's pages, from the first (refresh) or after the loaded ones (load more). */
+  const readPages = (more: boolean) =>
+    topicMode
+      ? (more ? loadMoreTopic : refreshTopic)(topicStore!, client, { conversationId: threadKey, languageCode: lang }, call)
+      : (more ? loadMoreDiscussion : refreshDiscussion)(discussionStore!, client, { articleId: threadKey, languageCode: lang }, call)
+
   function refresh(): Promise<void> {
     if (disposed) return Promise.resolve()
     refreshing ??= (async () => {
       state.refreshing = true
-      const r = await refreshDiscussion(store, client, { articleId, languageCode: lang }, call)
+      const r = await readPages(false)
       state.refreshing = false
       if (disposed) return
       lastSync = now()
@@ -304,23 +581,33 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
   async function loadMore(): Promise<void> {
     if (state.loadingMore || state.thread.nextCursor === null) return
     state.loadingMore = true
-    const r = await loadMoreDiscussion(store, client, { articleId, languageCode: lang }, call)
+    const r = await readPages(true)
     state.loadingMore = false
     if (disposed || r.ok) return
     if (r.code === 'surfaceOff') return hide()
+    if (topicMode && (r.code === 'membersOnly' || r.code === 'notFound')) return loadFailed(r)
     announce(failureText(r, lang))
   }
 
-  function onHeads(heads: DiscussionHead[]): void {
+  /** A head's thread (an article's id, or a topic's conversation id), lower case; null for none. */
+  const headKey = (head: DiscussionHead | TopicHead | null | undefined): string | null => {
+    const id = topicMode ? (head as TopicHead | null | undefined)?.conversationId : (head as DiscussionHead | null | undefined)?.articleId
+    return typeof id === 'string' ? id.toLowerCase() : null
+  }
+
+  const applyHead = (head: DiscussionHead | TopicHead): boolean =>
+    topicMode ? topicStore!.applyHead(head as TopicHead) : discussionStore!.applyHead(head as DiscussionHead)
+
+  function onHeads(heads: ReadonlyArray<DiscussionHead | TopicHead>): void {
     for (const head of heads) {
-      if (typeof head?.articleId !== 'string' || head.articleId.toLowerCase() !== articleId) continue
+      if (headKey(head) !== threadKey) continue
       if (state.phase === 'failed') {
         void refresh()
         continue
       }
       const before = store.getState()
       const newer = typeof head.lastSeq === 'number' && head.lastSeq > before.lastSeq
-      if (!store.applyHead(head)) continue
+      if (!applyHead(head)) continue
       // New messages wait for the reader (the page does not move under them); an edit, a reaction or the
       // reader's own post are folded in at once.
       if (newer && before.loaded) state.newMessages = true
@@ -330,15 +617,63 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   function startPolling(): void {
     if (poller || interval === 0 || disposed || state.phase === 'hidden') return
-    poller = pollDiscussionHead(client, [articleId], {
+    const options = {
       intervalMs: interval,
       visible: () => documentVisible() && inView,
       onChange: onHeads,
-      onFailure: (f) => {
+      onFailure: (f: CommunityFailure) => {
         if (f.code === 'surfaceOff') hide()
+        // M3: the forum closed to this viewer meanwhile (pollTopicHead stops on it): the members-only sentence.
+        else if (topicMode && f.code === 'membersOnly') loadFailed(f)
       },
       signal: abort.signal,
-    })
+    }
+    poller = topicMode ? pollTopicHead(client, [threadKey], options) : pollDiscussionHead(client, [threadKey], options)
+  }
+
+  /**
+   * Live updates (M2, §3.5): the host's session over this element's store, after the first list. Not for an anonymous
+   * reader (no host session: the token route refuses it) nor while `me/get` says the module offers none (`read_only`,
+   * `dark`, live updates not configured) — the head poll then, and no socket. The session falls back to polling by
+   * itself (`realtimeOff`, the server's terminal 4501) and the element never starts it again.
+   */
+  async function startRealtime(factory: AnyRealtime): Promise<void> {
+    if (session || disposed || state.phase === 'hidden') return
+    if (viewerNeeds(store.getState()).signIn) return startPolling()
+    await ensureMe()
+    // The discussion may have been hidden (SURFACE_OFF) while me/get was on its way.
+    if (disposed || session || (state.phase as DiscussionPhase) === 'hidden') return
+    if (state.me?.module && state.me.module.features.realtime !== true) return startPolling()
+    try {
+      session = (factory as unknown as DiscussionRealtime)({
+        client,
+        store: (discussionStore ?? topicStore) as unknown as DiscussionStore,
+        languageCode: lang,
+        visible: () => documentVisible() && inView,
+        ...(interval > 0 ? { pollIntervalMs: interval } : {}),
+        onMode: (mode) => {
+          if (disposed) return
+          // Said once per fallback: live again (the SDK session reconnected) takes the sentence away.
+          if (mode === 'polling' && !state.realtimeOff) state.realtimeOff = true
+          else if (mode === 'live' && state.realtimeOff) state.realtimeOff = false
+        },
+      })
+    } catch {
+      warnOnce('realtime', '[blogmcp-community] the realtime property is not a session factory (createRealtimeSession of @blogmcp/sdk/community/realtime): the discussion polls')
+      session = null
+      startPolling()
+    }
+  }
+
+  /**
+   * The member's community is paused (`me/get`'s module.brake or state, M2 §3.1): every member write is refused — and
+   * M3 (§4.9) this thread's surface's own brake pauses its writes too (the forum's for a topic, the article
+   * discussions' for an article), never the other surface's.
+   */
+  function brakedNow(): boolean {
+    const m = state.me?.module
+    if (!m) return false
+    return m.brake !== undefined || (isKnownModuleState(m.state) && m.state === 'braked') || surfaceBrakeOf(state.me) !== null
   }
 
   // ───────────────────────── who may do what ─────────────────────────
@@ -347,14 +682,37 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     const s = state.thread
     const n = viewerNeeds(s)
     if (n.signIn) return 'signIn'
+    if (topicMode) {
+      // M3: the team at the keyboard reads and writes through the KB admin; a closed topic takes no message (§1.1).
+      if (s.viewer.memberId === null) return 'none'
+      if (!topicIsOpen()) return 'locked'
+      if (state.block === 'readOnly') return 'readOnly'
+    }
     if (state.block === 'notMoved') return 'notMoved'
+    if (state.block === 'braked' || brakedNow()) return 'braked'
     if (!s.viewer.canPost && s.viewer.restrictions.length > 0) return 'sanction'
     // A refused age band: the refusal stays where the composer was once the reader closed it.
     if (n.any) return state.refusedAge !== null && !onboarding.value ? 'ageRefused' : 'onboarding'
+    // The give-consent flow of a member who refused the consent (needs name none): its step where the composer was.
+    if (onboarding.value && consentFlow) return 'onboarding'
     if (state.block === 'restricted') return 'restricted'
     return s.viewer.canPost ? 'write' : 'pending'
   }
 
+  /** me/get's per-message mention cap, where kb-api applies it (a member, the module live or braked: §3.3). */
+  function mentionCap(): number | null {
+    const me = state.me
+    const cap = me?.caps?.mentionsPerMessage
+    const m = me?.module?.state
+    if (!me?.member || typeof cap !== 'number' || !Number.isSafeInteger(cap) || cap < 0) return null
+    return m === 'live' || m === 'braked' ? cap : null
+  }
+  /** The draft mentions more distinct handles than the cap (kb-api's count: as typed, whether they exist or not). */
+  const overMentionCap = (body: string): boolean => {
+    const cap = mentionCap()
+    return cap !== null && communityMentionHandles(body).length > cap
+  }
+
   const isOwn = (m: Pick<DiscussionMessage, 'author'>): boolean => isOwnMessage(state.thread, m)
   const settled = (m: DiscussionMessage): boolean => !m.pending && m.seq > 0
   const canWrite = (): boolean => mode() === 'write'
@@ -399,9 +757,30 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   const waitLeft = (d: Draft): number => (d.waitUntil === null ? 0 : Math.max(0, Math.ceil((d.waitUntil - Math.max(state.clock, now())) / 1000)))
 
+  /**
+   * M3 (§3.1, A11): a write addressed by the topic's id that comes back `notFound` may be any refusal of the forum's
+   * gate — the topic is read again (settleTopicFailure), and a refusal of that read is the element's state (the
+   * members-only sentence, the topic gone, nothing for SURFACE_OFF); a topic that reads fine leaves the write's own
+   * `notFound` with its draft (the message it named is gone).
+   */
+  async function settleTopicWrite(d: Draft | null, f: CommunityFailure): Promise<void> {
+    const settled = await settleTopicFailure(topicStore!, client, { conversationId: threadKey, languageCode: lang }, f, call)
+    if (disposed) return
+    if (settled === f) {
+      afterLoad()
+      return
+    }
+    if (d && d.failure === f) d.failure = settled
+    loadFailed(settled)
+  }
+
   /** What a refused write does besides showing its sentence. */
   function refused(d: Draft | null, f: CommunityFailure): void {
     if (d) d.failure = f
+    if (topicMode && f.code === 'notFound') {
+      void settleTopicWrite(d, f)
+      return
+    }
     switch (failureEffect(f.code)) {
       case 'confirm':
         if (d && f.codes && f.codes.length > 0) d.confirm = { codes: [...f.codes], checked: [] }
@@ -409,11 +788,19 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       case 'wait':
         if (d) {
           d.waitUntil = waitUntilOf(f, now())
-          startClock()
+          if (d.waitUntil !== null) startClock()
+        }
+        if (f.code === 'braked') {
+          // Paused (BRAKED): the composer gives way to the sentence until the brake's end; me/get is read again.
+          state.block = 'braked'
+          refusedBrakeUntil = waitUntilOf(f, now())
+          scheduleBrakeEnd()
+          void ensureMe(true)
         }
         return
       case 'onboard':
-        beginOnboarding()
+        // M3: a forum write needs the art. 9 consent whatever the tenant asks elsewhere (U14): its refusal names it.
+        beginOnboarding(f.needs?.includes('art9_consent') ? { forceArt9: true } : {})
         void refresh()
         return
       case 'reload':
@@ -423,7 +810,8 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
         state.block = 'notMoved'
         return
       case 'hide':
-        return hide()
+        // Live updates switched off hide nothing: the discussion polls (no write answers it; a realtime route does).
+        return f.code === 'realtimeOff' ? undefined : hide()
       default:
         return
     }
@@ -440,6 +828,20 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     if (n.any) return beginOnboarding()
     const parent = target.kind === 'new' ? null : findMessage(state.thread, target.seq)
     if (target.kind !== 'new' && (!parent || !settled(parent))) return
+    // Too many mentions for the member's level: said before posting (the composer shows it as it is typed); kb-api's
+    // MENTION_LIMIT stays the rule.
+    if (overMentionCap(body)) {
+      d.failure = { ok: false, code: 'mentionLimit' }
+      return
+    }
+    // M3: the opening post's edit carries the title when it changed — one the schema takes (1..200 UTF-16 units).
+    let title: string | undefined
+    const inlineTitle = target.kind === 'edit' && state.inline === d ? state.inline.title : null
+    if (inlineTitle !== null) {
+      const next = forumTopicTitleOf(inlineTitle)
+      if (next === null) return
+      if (next !== topicStore?.getState().topic?.title) title = next
+    }
 
     d.sending = true
     d.failure = null
@@ -449,17 +851,23 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     if (target.kind === 'edit') store.applyMessage({ type: 'edit', clientMsgId: changeId, seq: target.seq, body })
     else if (author) store.applyMessage({ type: 'post', clientMsgId: changeId, body, replyToSeq: target.kind === 'reply' ? target.seq : null, author, languageCode: lang })
 
+    const where = topicMode ? { conversationId: threadKey } : { articleId: threadKey }
     const r =
       target.kind === 'edit'
-        ? await client.messages.edit({ conversationId: parent!.conversationId, seq: target.seq, body, ...(confirmations ? { confirmations } : {}) }, call)
+        ? await client.messages.edit(
+            { conversationId: parent!.conversationId, seq: target.seq, body, ...(title !== undefined ? { title } : {}), ...(confirmations ? { confirmations } : {}) },
+            call,
+          )
         : await client.messages.post(
-            { articleId, body, replyToSeq: target.kind === 'reply' ? target.seq : null, clientMsgId: changeId, languageCode: lang, ...(confirmations ? { confirmations } : {}) },
+            { ...where, body, replyToSeq: target.kind === 'reply' ? target.seq : null, clientMsgId: changeId, languageCode: lang, ...(confirmations ? { confirmations } : {}) },
             call,
           )
     if (disposed) return
     d.sending = false
     if (r.ok) {
       store.applyMessage({ type: 'confirm', clientMsgId: changeId, message: r.value.message, warnings: r.value.warnings })
+      // M3: a title edit answers the topic with its new title (§3.3).
+      if (r.value.topic && topicStore) topicStore.applyTopic(r.value.topic as Topic)
       const held = r.value.message.state === 'held'
       d.body = ''
       d.clientMsgId = null
@@ -509,10 +917,20 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   const reactionKey = (t: ReactionTarget): string => ('articleId' in t ? 'react:article' : `react:${t.seq}`)
 
+  /** A target's summary before a reaction: the article's own (an article's only), or a message's. */
+  const summaryOf = (target: ReactionTarget): ReactionSummary =>
+    topicMode
+      ? 'articleId' in target
+        ? NO_REACTIONS
+        : (findMessage(state.thread, target.seq)?.reactions ?? NO_REACTIONS)
+      : reactionsFor(state.thread as DiscussionState, target)
+
   async function react(target: ReactionTarget, emoji: string): Promise<void> {
     const key = reactionKey(target)
+    // A topic has no reactions of its own (the opening post's are seq 1's).
+    if (topicMode && 'articleId' in target) return
     if (!canWrite() || state.busy[key] || !state.thread.reactionSet.includes(emoji)) return
-    const before = reactionsFor(state.thread, target)
+    const before = summaryOf(target)
     const next = before.mine === emoji ? null : emoji
     state.busy[key] = true
     store.applyReaction(target, reactionAfter(before, next))
@@ -581,12 +999,18 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   // ───────────────────────── onboarding ─────────────────────────
 
-  function beginOnboarding(): void {
+  function beginOnboarding(options: OnboardingStart = {}): void {
     if (onboarding.value || disposed || state.refusedAge !== null) return
+    const offerArt9 = options.offerArt9 === true
+    // M3: before a forum write the art. 9 consent is asked whatever the tenant asks elsewhere (U14); not to read.
+    const forceArt9 = !offerArt9 && (options.forceArt9 === true || (topicMode && options.toRead !== true))
+    consentFlow = offerArt9
     const model = createOnboarding({
       client,
       lang,
       signal: abort.signal,
+      ...(offerArt9 ? { offerArt9: true } : {}),
+      ...(forceArt9 ? { forceArt9: true } : {}),
       onRefused: (minAge) => {
         state.refusedAge = minAge
         o.onAgeRefused?.(minAge)
@@ -594,7 +1018,12 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       onDone: (me) => {
         state.me = me
         onboarding.value = null
-        announce({ key: 'onboarding.done' })
+        // A refused art. 9 consent (`public_write`): the member joined, and is told what the refusal leaves.
+        state.art9RefusedNote = model.state.art9RefusedSent
+        if (offerArt9) {
+          // The give-consent flow: announced only when a consent is in force (it also closes with nothing left to ask).
+          if (me.acceptances.art9Consent === 'accepted') announce({ key: 'panel.art9Given' })
+        } else announce({ key: model.state.art9RefusedSent ? 'onboarding.art9RefusedDone' : 'onboarding.done' })
         void refresh()
       },
       onSignIn: () => {
@@ -606,13 +1035,26 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     void model.load()
   }
 
+  /** M3, a topic: reactions on the messages there go on in a closed topic (§1.1) — the write's other gates still apply. */
+  const canReactHere = (): boolean => {
+    const m = mode()
+    if (m === 'write') return true
+    if (!topicMode || m !== 'locked') return false
+    const s = state.thread
+    return s.viewer.memberId !== null && !viewerNeeds(s).any && s.viewer.restrictions.length === 0 && !brakedNow() && state.block === null
+  }
+
+  /** M3: the author's own opening post of a topic: its edit carries the title. */
+  const editsTitle = (m: Pick<DiscussionMessage, 'seq' | 'author'>): boolean => topicMode && m.seq === OPENING_SEQ && isOwn(m)
+
   return {
     state,
     store,
     onboarding,
     async start() {
       await refresh()
-      startPolling()
+      if (realtime && state.phase === 'ready') await startRealtime(realtime)
+      else startPolling()
     },
     refresh,
     loadMore,
@@ -626,8 +1068,11 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       return parent !== null && settled(parent) && parent.state === 'visible'
     },
     canEdit: (m) => canWrite() && isOwn(m) && settled(m) && m.body !== null && (m.state === 'visible' || m.state === 'held'),
-    canDelete: (m) => state.thread.viewer.memberId !== null && isOwn(m) && settled(m) && m.body !== null && m.state !== 'deleted',
-    canReact: canWrite,
+    // Not under a brake: kb-api refuses `messages/delete` BRAKED too (assertNotBraked).
+    canDelete: (m) => state.thread.viewer.memberId !== null && mode() !== 'braked' && isOwn(m) && settled(m) && m.body !== null && m.state !== 'deleted',
+    canReact: canReactHere,
+    mentionCap,
+    editsTitle,
     canReport: (m) => !viewerNeeds(state.thread).signIn && !isOwn(m) && settled(m) && m.body !== null && m.author.kind !== 'system',
     canReportAsNotifier: (m) => viewerNeeds(state.thread).signIn && settled(m) && m.body !== null && m.author.kind !== 'system',
     canBlock: (m) =>
@@ -647,12 +1092,14 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
         state.inline.replyingTo = replyingTo
         return
       }
-      state.inline = { ...emptyDraft(), kind: 'reply', seq: top, replyingTo }
+      state.inline = { ...emptyDraft(), kind: 'reply', seq: top, replyingTo, title: null }
     },
     openEdit(seq) {
       const m = findMessage(state.thread, seq)
       if (!m || m.body === null) return
-      state.inline = { ...emptyDraft(m.body), kind: 'edit', seq, replyingTo: null }
+      // M3: the opening post's edit carries the topic's title (as it is now; '' when it is withheld or gone).
+      const title = editsTitle(m) ? (topicStore?.getState().topic?.title ?? '') : null
+      state.inline = { ...emptyDraft(m.body), kind: 'edit', seq, replyingTo: null, title }
     },
     closeInline() {
       state.inline = null
@@ -682,9 +1129,13 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       abort.abort()
       poller?.stop()
       poller = null
+      session?.stop()
+      session = null
       unsubscribe()
       if (ticker) clearInterval(ticker)
       ticker = null
+      if (brakeTimer) clearTimeout(brakeTimer)
+      brakeTimer = null
       onboarding.value = null
     },
   }