@blogmcp/community 0.2.0 → 0.3.0

package/src/core/discussion.ts

@@ -4,6 +4,15 @@
  * 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'
@@ -14,14 +23,22 @@ import {
   communityMentionHandles,
   communityRulesOf,
   createDiscussionStore,
+  createTopicStore,
   findMessage,
+  forumTopicTitleOf,
   isOwnMessage,
+  isTopicOpen,
   loadMoreDiscussion,
+  loadMoreTopic,
   newClientMsgId,
   pollDiscussionHead,
+  pollTopicHead,
   reactionAfter,
   reactionsFor,
   refreshDiscussion,
+  refreshTopic,
+  settleTopicFailure,
+  surfaceInfoOf,
   viewerNeeds,
   type CaseCategory,
   type CommunityCallOptions,
@@ -33,19 +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 } from './realtime'
+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 {
@@ -69,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 {
@@ -95,20 +156,38 @@ export interface ReportDraft {
  * 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' | 'braked' | '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, none for this member, or a pause (BRAKED). */
-  block: 'notMoved' | 'restricted' | 'braked' | 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
@@ -136,9 +215,12 @@ export interface DiscussionUi {
   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
@@ -149,6 +231,10 @@ export interface DiscussionControllerOptions {
   refusedAge?: number | null
   /** The onboarding's age band was refused: the element keeps it for its next discussions. */
   onAgeRefused?(minAge: number): void
+}
+
+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.
@@ -156,9 +242,16 @@ export interface DiscussionControllerOptions {
   realtime?: DiscussionRealtime | null
 }
 
-export interface DiscussionController {
-  readonly state: DiscussionUi
-  readonly store: DiscussionStore
+/** 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>
@@ -196,9 +289,10 @@ export interface DiscussionController {
   submitReport(): Promise<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.
+   * 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?: { offerArt9?: boolean }): void
+  beginOnboarding(options?: OnboardingStart): void
   cancelOnboarding(): void
   /** Seconds a draft still waits (0 when it may go). */
   waitLeft(draft: Draft): number
@@ -207,22 +301,71 @@ export interface DiscussionController {
    * 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(),
@@ -241,7 +384,7 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     refusedAge: o.refusedAge ?? null,
     art9RefusedNote: false,
     realtimeOff: false,
-  }) as DiscussionUi
+  }) as ThreadUi<ThreadState>
   const unsubscribe = store.subscribe((s) => {
     state.thread = s
   })
@@ -290,13 +433,22 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     return mePromise
   }
 
-  /** The end of a brake as me/get states it (`module.brake.until`, or `module.until` of a braked module), epoch ms. */
+  /** 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
-    return Number.isFinite(at) ? at : null
+    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
   }
 
   /**
@@ -343,15 +495,25 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
   function decideBlock(): void {
     const s = store.getState()
     if (s.viewer.canPost || viewerNeeds(s).any || s.viewer.restrictions.length > 0) return
+    // 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()
     // A braked discussion asks me/get again on every refresh: the brake may be over (kb-api's canPost does not know it).
@@ -366,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()
@@ -377,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()
@@ -402,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
@@ -428,15 +617,18 @@ 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)
   }
 
   /**
@@ -445,7 +637,7 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
    * `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: DiscussionRealtime): Promise<void> {
+  async function startRealtime(factory: AnyRealtime): Promise<void> {
     if (session || disposed || state.phase === 'hidden') return
     if (viewerNeeds(store.getState()).signIn) return startPolling()
     await ensureMe()
@@ -453,9 +645,9 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     if (disposed || session || (state.phase as DiscussionPhase) === 'hidden') return
     if (state.me?.module && state.me.module.features.realtime !== true) return startPolling()
     try {
-      session = factory({
+      session = (factory as unknown as DiscussionRealtime)({
         client,
-        store,
+        store: (discussionStore ?? topicStore) as unknown as DiscussionStore,
         languageCode: lang,
         visible: () => documentVisible() && inView,
         ...(interval > 0 ? { pollIntervalMs: interval } : {}),
@@ -473,11 +665,15 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     }
   }
 
-  /** The member's community is paused (`me/get`'s module.brake or state, M2 §3.1): every member write is refused. */
+  /**
+   * 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')
+    return m.brake !== undefined || (isKnownModuleState(m.state) && m.state === 'braked') || surfaceBrakeOf(state.me) !== null
   }
 
   // ───────────────────────── who may do what ─────────────────────────
@@ -486,6 +682,12 @@ 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'
@@ -555,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: [] }
@@ -576,7 +799,8 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
         }
         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':
@@ -610,6 +834,14 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
       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
@@ -619,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
@@ -679,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))
@@ -751,15 +999,18 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
 
   // ───────────────────────── onboarding ─────────────────────────
 
-  function beginOnboarding(options: { offerArt9?: boolean } = {}): 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)
@@ -784,13 +1035,25 @@ 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()
-      if (o.realtime && state.phase === 'ready') await startRealtime(o.realtime)
+      if (realtime && state.phase === 'ready') await startRealtime(realtime)
       else startPolling()
     },
     refresh,
@@ -807,8 +1070,9 @@ export function createDiscussionController(o: DiscussionControllerOptions): Disc
     canEdit: (m) => canWrite() && isOwn(m) && settled(m) && m.body !== null && (m.state === 'visible' || m.state === 'held'),
     // 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: canWrite,
+    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) =>
@@ -828,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