@blogmcp/community 0.0.0-stage → 0.2.0

package/src/core/discussion.ts

@@ -0,0 +1,876 @@
+/**
+ * `<blogmcp-discussion>`'s brain, without any view (m1-contracts.md §10.4): the SDK's discussion store fed by
+ * `discussions/list` pages and the `discussions/head` poll, the composer (a new message, a reply, an edit)
+ * 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.
+ *
+ * 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,
+  findMessage,
+  isOwnMessage,
+  loadMoreDiscussion,
+  newClientMsgId,
+  pollDiscussionHead,
+  reactionAfter,
+  reactionsFor,
+  refreshDiscussion,
+  viewerNeeds,
+  type CaseCategory,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type CommunityRule,
+  type DiscussionHead,
+  type DiscussionHeadPoller,
+  type DiscussionMessage,
+  type DiscussionState,
+  type DiscussionStore,
+  type KnownAuthor,
+  type MyState,
+  type ReactionTarget,
+  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 { codePointLength, normalizeBody } from './text'
+
+export type DiscussionPhase = 'loading' | 'ready' | 'failed' | 'hidden'
+
+/** One composer's text and what happened to it. */
+export interface Draft {
+  body: string
+  sending: boolean
+  failure: CommunityFailure | null
+  /** CONFIRMATION_REQUIRED: the codes the author confirms before the same text goes again. */
+  confirm: { codes: string[]; checked: string[] } | null
+  /** A cooldown: the epoch milliseconds until which this write waits. */
+  waitUntil: number | null
+  /** A post's id, kept until kb-api took it: a retry of a write whose answer was lost cannot post twice. */
+  clientMsgId: string | null
+}
+
+export type InlineKind = 'reply' | 'edit'
+
+/** The one reply or edit open under a message (opening another closes it). */
+export interface InlineDraft extends Draft {
+  kind: InlineKind
+  /** The message edited, or the TOP-LEVEL message a reply goes under (two levels only). */
+  seq: number
+  /** A reply to a reply names whom it answers. */
+  replyingTo: string | null
+}
+
+export interface ReportDraft {
+  conversationId: string
+  seq: number
+  category: CaseCategory | ''
+  ruleId: string
+  note: string
+  rules: CommunityRule[] | null
+  rulesFailed: boolean
+  sending: boolean
+  failure: CommunityFailure | null
+  done: boolean
+}
+
+/**
+ * Where the composer stands: `write`; `signIn` (no session that can write); `onboarding` (the inline
+ * 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); `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' | 'braked' | 'pending'
+
+export interface DiscussionUi {
+  phase: DiscussionPhase
+  /** Why the first load failed (`failed`). */
+  failure: CommunityFailure | null
+  thread: DiscussionState
+  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
+  composer: Draft
+  inline: InlineDraft | null
+  report: ReportDraft | null
+  /** The last outcome to announce (aria-live), and a counter so the same text is announced again. */
+  announcement: TextRef | null
+  announceId: number
+  /** Now, ticking while a cooldown runs. */
+  clock: number
+  /** Actions on their way, by key (`react:…`, `delete:<seq>`, `block:<memberId>`). */
+  busy: Record<string, boolean>
+  /**
+   * The minimum age a declared band fell below (AGE_BELOW_MINIMUM). kb-api keeps nothing of a refused band
+   * (§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 {
+  client: CommunityClient
+  articleId: string
+  lang: Lang
+  /** Head poll interval (default 20 s; 0 = no polling). */
+  pollMs?: number
+  now?: () => number
+  /** The viewer's message was posted (`held`: it waits for review). */
+  onPosted?(state: 'visible' | 'held'): void
+  /** A refusal the element saw before (a discussion started again in another language keeps it). */
+  refusedAge?: number | null
+  /** The onboarding's age band was refused: the element keeps it for its next discussions. */
+  onAgeRefused?(minAge: number): void
+  /**
+   * 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
+}
+
+export interface DiscussionController {
+  readonly state: DiscussionUi
+  readonly store: DiscussionStore
+  readonly onboarding: ShallowRef<OnboardingModel | null>
+  /** The first load, then the poll. */
+  start(): Promise<void>
+  refresh(): Promise<void>
+  loadMore(): Promise<void>
+  mode(): ComposerMode
+  needs(): ViewerNeeds
+  isOwn(m: Pick<DiscussionMessage, 'author'>): boolean
+  canReply(m: DiscussionMessage): boolean
+  canEdit(m: DiscussionMessage): boolean
+  canDelete(m: DiscussionMessage): boolean
+  canReact(): boolean
+  /** A member's report (`messages/report`): any signed-in reader, on someone else's message. */
+  canReport(m: DiscussionMessage): boolean
+  /** A reader without a session reports through the host's notice page instead (reportLink). */
+  canReportAsNotifier(m: DiscussionMessage): boolean
+  canBlock(m: DiscussionMessage): boolean
+  /** The poll may run (the element is on screen). */
+  setInView(inView: boolean): void
+  submit(): Promise<void>
+  /** Reply under `seq`'s thread (a reply to a reply goes under its top-level message, naming its author). */
+  openReply(seq: number, replyingTo?: string | null): void
+  openEdit(seq: number): void
+  closeInline(): void
+  submitInline(): Promise<void>
+  /** Tick or untick one code of a draft's confirmation. */
+  setConfirmed(draft: Draft, code: string, checked: boolean): void
+  /** Send the draft again with every confirmed code (the Russmedia confirmation). */
+  sendConfirmed(draft: Draft): Promise<void>
+  remove(seq: number): Promise<boolean>
+  react(target: ReactionTarget, emoji: string): Promise<void>
+  setBlocked(memberId: string, blocked: boolean): Promise<void>
+  openReport(m: DiscussionMessage): void
+  closeReport(): void
+  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.
+   */
+  beginOnboarding(options?: { offerArt9?: boolean }): 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
+  dispose(): void
+}
+
+const emptyDraft = (body = ''): Draft => ({ body, sending: false, failure: null, confirm: null, waitUntil: null, clientMsgId: null })
+
+const documentVisible = (): boolean => typeof document === 'undefined' || document.visibilityState !== 'hidden'
+
+export function createDiscussionController(o: DiscussionControllerOptions): DiscussionController {
+  const { client, lang } = o
+  const articleId = o.articleId.toLowerCase()
+  const now = o.now ?? Date.now
+  const store = createDiscussionStore()
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+
+  const state = reactive<DiscussionUi>({
+    phase: 'loading',
+    failure: null,
+    thread: store.getState(),
+    loadingMore: false,
+    refreshing: false,
+    newMessages: false,
+    me: null,
+    block: null,
+    composer: emptyDraft(),
+    inline: null,
+    report: null,
+    announcement: null,
+    announceId: 0,
+    clock: now(),
+    busy: {},
+    refusedAge: o.refusedAge ?? null,
+    art9RefusedNote: false,
+    realtimeOff: false,
+  }) as DiscussionUi
+  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 {
+    state.announcement = text
+    state.announceId += 1
+  }
+
+  function hide(): void {
+    state.phase = 'hidden'
+    poller?.stop()
+    poller = null
+    session?.stop()
+    session = null
+  }
+
+  // ───────────────────────── loading ─────────────────────────
+
+  /** 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) return
+      state.me = r.value
+      scheduleBrakeEnd()
+    })
+    return mePromise
+  }
+
+  /** The end of a brake as me/get states it (`module.brake.until`, or `module.until` of a braked module), 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
+  }
+
+  /**
+   * 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(state.block === null).then(() => {
+      const me = state.me
+      if (disposed || !me || store.getState().viewer.canPost) return
+      if (brakedNow()) 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'
+    })
+  }
+
+  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).
+    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
+  }
+
+  function loadFailed(f: CommunityFailure): void {
+    if (f.code === 'surfaceOff') return hide()
+    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()
+    }
+    if (state.phase === 'loading' || state.phase === 'failed') {
+      state.phase = 'failed'
+      state.failure = f
+    }
+    // A loaded discussion keeps what it shows; the poll tries again.
+  }
+
+  function refresh(): Promise<void> {
+    if (disposed) return Promise.resolve()
+    refreshing ??= (async () => {
+      state.refreshing = true
+      const r = await refreshDiscussion(store, client, { articleId, languageCode: lang }, call)
+      state.refreshing = false
+      if (disposed) return
+      lastSync = now()
+      if (r.ok) {
+        state.phase = 'ready'
+        state.failure = null
+        state.newMessages = false
+        afterLoad()
+      } else {
+        loadFailed(r)
+      }
+    })().finally(() => {
+      refreshing = null
+    })
+    return refreshing
+  }
+
+  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)
+    state.loadingMore = false
+    if (disposed || r.ok) return
+    if (r.code === 'surfaceOff') return hide()
+    announce(failureText(r, lang))
+  }
+
+  function onHeads(heads: DiscussionHead[]): void {
+    for (const head of heads) {
+      if (typeof head?.articleId !== 'string' || head.articleId.toLowerCase() !== articleId) 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
+      // 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
+      else void refresh()
+    }
+  }
+
+  function startPolling(): void {
+    if (poller || interval === 0 || disposed || state.phase === 'hidden') return
+    poller = pollDiscussionHead(client, [articleId], {
+      intervalMs: interval,
+      visible: () => documentVisible() && inView,
+      onChange: onHeads,
+      onFailure: (f) => {
+        if (f.code === 'surfaceOff') hide()
+      },
+      signal: abort.signal,
+    })
+  }
+
+  /**
+   * 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: DiscussionRealtime): 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({
+        client,
+        store,
+        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. */
+  function brakedNow(): boolean {
+    const m = state.me?.module
+    if (!m) return false
+    return m.brake !== undefined || (isKnownModuleState(m.state) && m.state === 'braked')
+  }
+
+  // ───────────────────────── who may do what ─────────────────────────
+
+  function mode(): ComposerMode {
+    const s = state.thread
+    const n = viewerNeeds(s)
+    if (n.signIn) return 'signIn'
+    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'
+
+  // ───────────────────────── writes ─────────────────────────
+
+  /** The viewer as their own messages show them (for the optimistic row), or null when not known yet. */
+  function ownAuthor(): KnownAuthor | null {
+    const me = state.me
+    if (me?.member && me.profile) {
+      return { kind: 'member', memberId: me.member.memberId, handle: me.profile.handle, displayName: me.profile.displayName, avatarPreset: me.profile.avatarPreset }
+    }
+    const viewer = state.thread.viewer.memberId
+    if (viewer === null) return null
+    for (const m of state.thread.messages) {
+      for (const x of [m, ...m.replies]) if (x.author.kind === 'member' && x.author.memberId === viewer) return x.author
+    }
+    return null
+  }
+
+  function startClock(): void {
+    state.clock = now()
+    if (ticker) return
+    ticker = setInterval(() => {
+      state.clock = now()
+      let waiting = false
+      for (const d of [state.composer, state.inline]) {
+        if (!d || d.waitUntil === null) continue
+        if (d.waitUntil <= state.clock) {
+          d.waitUntil = null
+          if (d.failure && (d.failure.code === 'fast' || d.failure.code === 'quota')) d.failure = null
+        } else {
+          waiting = true
+        }
+      }
+      if (!waiting && ticker) {
+        clearInterval(ticker)
+        ticker = null
+      }
+    }, 1000)
+  }
+
+  const waitLeft = (d: Draft): number => (d.waitUntil === null ? 0 : Math.max(0, Math.ceil((d.waitUntil - Math.max(state.clock, now())) / 1000)))
+
+  /** What a refused write does besides showing its sentence. */
+  function refused(d: Draft | null, f: CommunityFailure): void {
+    if (d) d.failure = f
+    switch (failureEffect(f.code)) {
+      case 'confirm':
+        if (d && f.codes && f.codes.length > 0) d.confirm = { codes: [...f.codes], checked: [] }
+        return
+      case 'wait':
+        if (d) {
+          d.waitUntil = waitUntilOf(f, now())
+          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()
+        void refresh()
+        return
+      case 'reload':
+        void refresh()
+        return
+      case 'notMoved':
+        state.block = 'notMoved'
+        return
+      case '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
+    }
+  }
+
+  type Target = { kind: 'new' } | { kind: InlineKind; seq: number }
+
+  async function send(d: Draft, target: Target, confirmations?: string[]): Promise<void> {
+    if (d.sending || waitLeft(d) > 0 || disposed) return
+    const body = normalizeBody(d.body)
+    if (body === '' || codePointLength(body) > COMMUNITY_MESSAGE_MAX) return
+    const n = viewerNeeds(state.thread)
+    if (n.signIn) return
+    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
+    }
+
+    d.sending = true
+    d.failure = null
+    const author = target.kind === 'edit' ? null : ownAuthor()
+    // A post keeps its id until kb-api took it; an edit's id only names its optimistic change.
+    const changeId = target.kind === 'edit' ? newClientMsgId() : (d.clientMsgId ??= newClientMsgId())
+    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 r =
+      target.kind === 'edit'
+        ? await client.messages.edit({ conversationId: parent!.conversationId, seq: target.seq, body, ...(confirmations ? { confirmations } : {}) }, call)
+        : await client.messages.post(
+            { articleId, 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 })
+      const held = r.value.message.state === 'held'
+      d.body = ''
+      d.clientMsgId = null
+      d.confirm = null
+      d.failure = null
+      if (target.kind !== 'new' && state.inline === d) state.inline = null
+      announce({ key: held ? 'composer.held' : 'composer.posted' })
+      if (target.kind !== 'edit') o.onPosted?.(held ? 'held' : 'visible')
+      return
+    }
+    store.applyMessage({ type: 'rollback', clientMsgId: changeId })
+    refused(d, r)
+  }
+
+  function setConfirmed(d: Draft, code: string, checked: boolean): void {
+    if (!d.confirm || !d.confirm.codes.includes(code)) return
+    const rest = d.confirm.checked.filter((c) => c !== code)
+    d.confirm.checked = checked ? [...rest, code] : rest
+  }
+
+  async function sendConfirmed(d: Draft): Promise<void> {
+    const confirm = d.confirm
+    if (!confirm || !confirm.codes.every((c) => confirm.checked.includes(c))) return
+    const target: Target = d === state.composer ? { kind: 'new' } : state.inline === d ? { kind: state.inline.kind, seq: state.inline.seq } : { kind: 'new' }
+    await send(d, target, [...confirm.codes])
+  }
+
+  async function remove(seq: number): Promise<boolean> {
+    const m = findMessage(state.thread, seq)
+    const key = `delete:${seq}`
+    if (!m || !settled(m) || state.busy[key]) return false
+    state.busy[key] = true
+    const changeId = newClientMsgId()
+    store.applyMessage({ type: 'delete', clientMsgId: changeId, seq })
+    const r = await client.messages.delete({ conversationId: m.conversationId, seq }, call)
+    delete state.busy[key]
+    if (disposed) return false
+    if (r.ok) {
+      store.applyMessage({ type: 'confirm', clientMsgId: changeId, message: r.value.message })
+      return true
+    }
+    store.applyMessage({ type: 'rollback', clientMsgId: changeId })
+    announce(failureText(r, lang))
+    refused(null, r)
+    return false
+  }
+
+  const reactionKey = (t: ReactionTarget): string => ('articleId' in t ? 'react:article' : `react:${t.seq}`)
+
+  async function react(target: ReactionTarget, emoji: string): Promise<void> {
+    const key = reactionKey(target)
+    if (!canWrite() || state.busy[key] || !state.thread.reactionSet.includes(emoji)) return
+    const before = reactionsFor(state.thread, target)
+    const next = before.mine === emoji ? null : emoji
+    state.busy[key] = true
+    store.applyReaction(target, reactionAfter(before, next))
+    const r = await client.reactions.set({ target, emoji: next }, call)
+    delete state.busy[key]
+    if (disposed) return
+    if (r.ok) {
+      store.applyReaction(target, r.value.reactions)
+      return
+    }
+    store.applyReaction(target, before)
+    announce(failureText(r, lang))
+    refused(null, r)
+  }
+
+  async function setBlocked(memberId: string, blocked: boolean): Promise<void> {
+    const key = `block:${memberId}`
+    if (state.busy[key]) return
+    state.busy[key] = true
+    const r = await client.blocks.set({ memberId, blocked }, call)
+    delete state.busy[key]
+    if (disposed) return
+    if (r.ok) {
+      store.collapse(memberId, r.value.blocked)
+      announce({ key: r.value.blocked ? 'discussion.blocked' : 'discussion.unblocked' })
+      return
+    }
+    announce(failureText(r, lang))
+    refused(null, r)
+  }
+
+  // ───────────────────────── reports ─────────────────────────
+
+  function openReport(m: DiscussionMessage): void {
+    state.report = { conversationId: m.conversationId, seq: m.seq, category: '', ruleId: '', note: '', rules: null, rulesFailed: false, sending: false, failure: null, done: false }
+    const report = state.report
+    void client.legal.current({ kind: 'rules', locale: lang }, call).then((r) => {
+      if (state.report !== report) return
+      if (r.ok) report.rules = communityRulesOf(r.value.bodyJson)
+      else report.rulesFailed = true
+    })
+  }
+
+  async function submitReport(): Promise<void> {
+    const report = state.report
+    if (!report || report.sending || report.done || report.category === '') return
+    if (report.category === 'rules' && report.ruleId === '') return
+    const note = normalizeBody(report.note)
+    if (codePointLength(note) > COMMUNITY_REPORT_NOTE_MAX) return
+    report.sending = true
+    report.failure = null
+    const r = await client.messages.report(
+      { conversationId: report.conversationId, seq: report.seq, category: report.category, ruleId: report.category === 'rules' ? report.ruleId : null, note: note === '' ? null : note },
+      call,
+    )
+    report.sending = false
+    if (disposed) return
+    if (r.ok) {
+      report.done = true
+      announce({ key: 'report.done' })
+      return
+    }
+    report.failure = r
+    if (r.code === 'surfaceOff') hide()
+  }
+
+  // ───────────────────────── onboarding ─────────────────────────
+
+  function beginOnboarding(options: { offerArt9?: boolean } = {}): void {
+    if (onboarding.value || disposed || state.refusedAge !== null) return
+    const offerArt9 = options.offerArt9 === true
+    consentFlow = offerArt9
+    const model = createOnboarding({
+      client,
+      lang,
+      signal: abort.signal,
+      ...(offerArt9 ? { offerArt9: true } : {}),
+      onRefused: (minAge) => {
+        state.refusedAge = minAge
+        o.onAgeRefused?.(minAge)
+      },
+      onDone: (me) => {
+        state.me = me
+        onboarding.value = null
+        // 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: () => {
+        onboarding.value = null
+        void refresh()
+      },
+    })
+    onboarding.value = model
+    void model.load()
+  }
+
+  return {
+    state,
+    store,
+    onboarding,
+    async start() {
+      await refresh()
+      if (o.realtime && state.phase === 'ready') await startRealtime(o.realtime)
+      else startPolling()
+    },
+    refresh,
+    loadMore,
+    mode,
+    needs: () => viewerNeeds(state.thread),
+    isOwn,
+    canReply: (m) => {
+      if (!canWrite() || !settled(m) || m.state !== 'visible' || m.body === null) return false
+      if (m.replyToSeq === null) return true
+      const parent = findMessage(state.thread, m.replyToSeq)
+      return parent !== null && settled(parent) && parent.state === 'visible'
+    },
+    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,
+    mentionCap,
+    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) =>
+      !viewerNeeds(state.thread).signIn && !isOwn(m) && settled(m) && m.author.kind === 'member' && m.author.memberId !== null,
+    setInView(v) {
+      const was = inView
+      inView = v
+      if (v && !was && poller && now() - lastSync >= interval) poller.now()
+    },
+    submit: () => send(state.composer, { kind: 'new' }),
+    openReply(seq, replyingTo = null) {
+      const m = findMessage(state.thread, seq)
+      if (!m) return
+      // Two levels: a reply to a reply goes under the top-level message.
+      const top = m.replyToSeq ?? m.seq
+      if (state.inline?.kind === 'reply' && state.inline.seq === top) {
+        state.inline.replyingTo = replyingTo
+        return
+      }
+      state.inline = { ...emptyDraft(), kind: 'reply', seq: top, replyingTo }
+    },
+    openEdit(seq) {
+      const m = findMessage(state.thread, seq)
+      if (!m || m.body === null) return
+      state.inline = { ...emptyDraft(m.body), kind: 'edit', seq, replyingTo: null }
+    },
+    closeInline() {
+      state.inline = null
+    },
+    async submitInline() {
+      const d = state.inline
+      if (d) await send(d, { kind: d.kind, seq: d.seq })
+    },
+    setConfirmed,
+    sendConfirmed,
+    remove,
+    react,
+    setBlocked,
+    openReport,
+    closeReport() {
+      state.report = null
+    },
+    submitReport,
+    beginOnboarding,
+    cancelOnboarding() {
+      onboarding.value = null
+    },
+    waitLeft,
+    dispose() {
+      if (disposed) return
+      disposed = true
+      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
+    },
+  }
+}