@blogmcp/community 0.0.0-stage → 0.2.0

package/src/core/onboarding.ts

@@ -0,0 +1,492 @@
+/**
+ * The light onboarding inside the discussion (m1-contracts.md §7.4.2, §10.4; community.md §4.4–§4.6): what a
+ * reader does once before their first comment, and again when the tenant's rules change or it starts to ask
+ * for the art. 9 consent. In order, only the steps still missing:
+ *
+ *   age      the age band, asked once and never offered again (`16_17`, `18_plus`); below the tenant's
+ *            minimum kb-api stores nothing and the reader is told from what age the discussion is open;
+ *   rules    the rules' summary (`legal/current` → `bodyJson`, text only) with a link to the full text, and
+ *            the acceptance;
+ *   art9     the art. 9 consent's text and the acceptance, when the tenant asks for it (M2 T9, m2-contracts.md §3.8:
+ *            the layout from me/get's `settings.art9ConsentLayout` — `joint` one consent, `split` one per controller of
+ *            the text's `bodyJson.controllers` when it names two, all of them required, the text itself shown once —
+ *            and, where `settings.art9Refusal` is `public_write`, a refusal that joins without the consent: kb-api then
+ *            opens the public discussion to the member, so `art9Refused` goes instead of the text id; under `read_only`
+ *            no refusal is offered and a reader who closes the step keeps reading);
+ *   profile  the display name, the handle (kb-api makes one when none is given; the element shows what it
+ *            would be), an avatar preset.
+ *
+ * One `me/onboard` at the end carries them all; kb-api records only what is still missing, so a member who
+ * comes back for a newer rules text sends the band and the profile they already have untouched.
+ *
+ * kb-api records the acceptance of whatever CURRENT text id it is sent (§7.4.2), so a text id goes only for a text
+ * this model showed and the reader ticked: the rules text when the rules are a step, else none. A text published
+ * meanwhile, or the art. 9 consent switched on meanwhile, is kb-api's VALIDATION on that id: the steps are read
+ * again from me/get (a step may be new), the reader goes to the first one left, nothing goes until it is answered.
+ */
+import { reactive } from 'vue'
+import {
+  art9ConsentLayoutOf,
+  art9ControllersOf,
+  art9RefusalOf,
+  communityRulesOf,
+  isKnownNeed,
+  type AgeBand,
+  type Art9ConsentLayout,
+  type Art9Refusal,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type CommunityRule,
+  type CurrentLegalText,
+  type MyState,
+  type OnboardInput,
+} from '@blogmcp/sdk/community'
+import type { Lang, TextRef } from './i18n'
+import { failureText } from './outcomes'
+import { isDisplayNameOk, isHandleOk, normalizeHandle, normalizeName, suggestedHandle } from './names'
+import { htmlToParagraphs } from './text'
+
+export type OnboardingStep = 'age' | 'rules' | 'art9' | 'profile'
+
+export type OnboardingPhase = 'loading' | 'ready' | 'sending' | 'done' | 'failed' | 'refused'
+
+/** One consent of the art. 9 step: a controller the text names (or the tenant, when it names none) and its tick. */
+export interface Art9Consent {
+  /** The controller's registry ref from the text's `bodyJson`; empty for the tenant of a text that names none. */
+  readonly entity: string
+  /** The name the reader sees; empty for the tenant of a text that names none (the step's own sentence then). */
+  readonly label: string
+  accepted: boolean
+}
+
+export interface OnboardingState {
+  /** `refused`: the age band is below the minimum — nothing was stored, the reader may go on reading. */
+  phase: OnboardingPhase
+  steps: OnboardingStep[]
+  index: number
+  me: MyState | null
+  rulesText: CurrentLegalText | null
+  rules: CommunityRule[]
+  art9Text: CurrentLegalText | null
+  art9Paragraphs: string[]
+  /** me/get's `settings.art9ConsentLayout` (absent: `joint`). */
+  art9Layout: Art9ConsentLayout
+  /** me/get's `settings.art9Refusal` (absent: `read_only`). */
+  art9Refusal: Art9Refusal
+  /**
+   * The consents the step asks for, each ticked on its own: one under `joint` (or a text naming fewer than two
+   * controllers), the text's two controllers under `split`. Empty while there is no art. 9 text.
+   */
+  art9Controllers: Art9Consent[]
+  /** The reader chose „Nesouhlasím" (only where the refusal is offered). */
+  art9Refused: boolean
+  /** The me/onboard kb-api took carried the refusal (the done note says what it leaves). */
+  art9RefusedSent: boolean
+  /** The member accepted an older rules text; this one asks again. */
+  reconsent: boolean
+  ageBand: AgeBand | null
+  rulesAccepted: boolean
+  /** Every consent of the step ticked (setting it ticks or unticks them all). */
+  art9Accepted: boolean
+  displayName: string
+  handle: string
+  avatarPreset: string | null
+  failure: CommunityFailure | null
+  /** The fields a refusal named (`displayName`, `handle`, …). */
+  fields: string[]
+  /** The minimum age, once a refusal told it (a refused `16_17` means 18). */
+  minAge: number | null
+}
+
+export interface OnboardingModel {
+  readonly state: OnboardingState
+  load(): Promise<void>
+  step(): OnboardingStep | null
+  isLast(): boolean
+  canContinue(): boolean
+  /** The next step, or — on the last one — `me/onboard`. */
+  next(): Promise<void>
+  back(): void
+  suggestedHandle(): string | null
+  hasFieldError(field: string): boolean
+  /**
+   * The tenant takes a refusal of the art. 9 consent here (`art9Refusal = public_write`, not the give-consent flow): the
+   * step's lede then does not make writing depend on the consent (community.md §9.8 q8, art. 9(2)(a) — freely given).
+   */
+  refusalOffered(): boolean
+  /** The art. 9 step offers „Nesouhlasím" (`art9Refusal = public_write`, never in the give-consent flow). */
+  canRefuse(): boolean
+  /** „Nesouhlasím": the step is answered without the consent; the next step, or — on the last one — `me/onboard`. */
+  refuse(): Promise<void>
+}
+
+export interface OnboardingOptions {
+  client: Pick<CommunityClient, 'me' | 'legal'>
+  lang: Lang
+  /** Called with the member's state once kb-api took the onboarding. */
+  onDone(state: MyState): void
+  /** The session cannot act as a member any more (signed out meanwhile). */
+  onSignIn(): void
+  /** The age band was below the tenant's minimum (AGE_BELOW_MINIMUM): kb-api kept nothing, the element keeps this. */
+  onRefused?(minAge: number): void
+  /**
+   * The give-consent flow („Moje komunita", M2 T9): the art. 9 step is asked also when `needs` does not name it — a
+   * member who refused it, or has not given it, where the tenant asks for it — and no refusal is offered.
+   */
+  offerArt9?: boolean
+  signal?: AbortSignal
+}
+
+const PROFILE_FIELDS = new Set(['displayName', 'handle', 'avatarPreset'])
+const TEXT_FIELDS = new Set(['rulesTextId', 'art9TextId'])
+/** kb-api's issue code for a refusal the tenant does not take (`art9Refusal = read_only`, §3.8). */
+export const ART9_REFUSAL_READ_ONLY = 'art9_refusal_read_only'
+
+/**
+ * A refusal of the art. 9 refusal itself: the tenant's setting is `read_only` (changed meanwhile, or a stale page) —
+ * kb-api's issue code, never the path alone. A path-only `art9Refused` is kb-api's „a consent is already in force"
+ * (given in another tab): a plain reread with the generic sentence.
+ */
+const refusalRefused = (f: Pick<CommunityFailure, 'code' | 'issueCodes'>): boolean =>
+  f.code === 'invalid' && f.issueCodes?.includes(ART9_REFUSAL_READ_ONLY) === true
+
+/** The sentence a refusal of the onboarding shows: a refused refusal says the consent is needed to write. */
+export function onboardingFailureText(failure: Pick<CommunityFailure, 'code' | 'until' | 'fields' | 'issueCodes'>, lang: Lang): TextRef {
+  return refusalRefused(failure) ? { key: 'onboarding.art9RequiredToWrite' } : failureText(failure, lang)
+}
+
+/** What is still missing for this member, in order (MyState and its known needs). */
+function stepsOf(me: MyState, needs: readonly string[], offerArt9: boolean): OnboardingStep[] {
+  const steps: OnboardingStep[] = []
+  if (!me.member?.ageBand) steps.push('age')
+  if (me.acceptances.rules !== 'accepted') steps.push('rules')
+  const art9 = me.acceptances.art9Consent
+  if (needs.includes('art9_consent') || (offerArt9 && art9 !== null && art9 !== 'accepted')) steps.push('art9')
+  if (!me.profile) steps.push('profile')
+  return steps
+}
+
+/** The consents the step asks for: the text's two controllers under `split`, else one (its first, or the tenant). */
+function consentsOf(text: CurrentLegalText | null, layout: Art9ConsentLayout): Array<{ entity: string; label: string }> {
+  if (!text) return []
+  const listed = art9ControllersOf(text.bodyJson)
+  if (layout === 'split' && listed.length > 1) return listed.map((c) => ({ entity: c.entity, label: c.label }))
+  return [{ entity: listed[0]?.entity ?? '', label: listed.length > 1 ? '' : (listed[0]?.label ?? '') }]
+}
+
+/** The texts of the steps shown. */
+interface Texts {
+  rules: CurrentLegalText | null
+  art9: CurrentLegalText | null
+}
+
+/** One reading of what is left to ask: me/get, its steps, their texts. */
+interface Read {
+  me: MyState
+  steps: OnboardingStep[]
+  texts: Texts
+}
+
+export function createOnboarding(o: OnboardingOptions): OnboardingModel {
+  const call: CommunityCallOptions = o.signal ? { signal: o.signal } : {}
+  const offerArt9 = o.offerArt9 === true
+  const state = reactive<OnboardingState>({
+    phase: 'loading',
+    steps: [],
+    index: 0,
+    me: null,
+    rulesText: null,
+    rules: [],
+    art9Text: null,
+    art9Paragraphs: [],
+    art9Layout: 'joint',
+    art9Refusal: 'read_only',
+    art9Controllers: [],
+    art9Refused: false,
+    art9RefusedSent: false,
+    reconsent: false,
+    ageBand: null,
+    rulesAccepted: false,
+    // Read through the reactive proxy (`this`), so a view's v-model ticks every consent and the guard sees them all.
+    get art9Accepted(): boolean {
+      return this.art9Controllers.length > 0 && this.art9Controllers.every((c) => c.accepted)
+    },
+    set art9Accepted(value: boolean) {
+      for (const c of this.art9Controllers) c.accepted = value
+    },
+    displayName: '',
+    handle: '',
+    avatarPreset: null,
+    failure: null,
+    fields: [],
+    minAge: null,
+  }) as OnboardingState
+
+  const fail = (failure: CommunityFailure): void => {
+    state.failure = failure
+    state.phase = 'failed'
+  }
+
+  /** The texts of these steps — none for a step that is not one, so its id can never be sent; null when one fails. */
+  async function textsFor(steps: OnboardingStep[]): Promise<Texts | null> {
+    const [rules, art9] = await Promise.all([
+      steps.includes('rules') ? o.client.legal.current({ kind: 'rules', locale: o.lang }, call) : null,
+      steps.includes('art9') ? o.client.legal.current({ kind: 'art9_consent', locale: o.lang }, call) : null,
+    ])
+    for (const r of [rules, art9]) {
+      if (r && !r.ok) {
+        fail(r)
+        return null
+      }
+    }
+    return { rules: rules?.ok ? rules.value : null, art9: art9?.ok ? art9.value : null }
+  }
+
+  /** me/get and what it leaves to ask, with the texts; null when it went elsewhere (a failure, a signed-out session). */
+  async function read(): Promise<Read | null> {
+    const me = await o.client.me.get(call)
+    if (!me.ok) {
+      fail(me)
+      return null
+    }
+    const needs = me.value.needs.filter(isKnownNeed)
+    if (needs.includes('sign_in')) {
+      o.onSignIn()
+      return null
+    }
+    const steps = stepsOf(me.value, needs, offerArt9)
+    const texts = await textsFor(steps)
+    return texts ? { me: me.value, steps, texts } : null
+  }
+
+  /** The refusal is offered: the tenant takes it (`public_write`), and this is not the give-consent flow. */
+  const refusalOffered = (): boolean => !offerArt9 && state.art9Refusal === 'public_write'
+
+  /** What was read, shown at once; an acceptance holds only for the very text it was given to. */
+  function apply(r: Read): void {
+    if (r.texts.rules?.textId !== state.rulesText?.textId) state.rulesAccepted = false
+    const layout = art9ConsentLayoutOf(r.me.settings?.art9ConsentLayout)
+    const sameText = r.texts.art9 !== null && r.texts.art9.textId === state.art9Text?.textId
+    // A tick holds for the same controller of the same text; anything else is asked again.
+    state.art9Controllers = consentsOf(r.texts.art9, layout).map((c, i) => {
+      const before = state.art9Controllers[i]
+      return { ...c, accepted: sameText && before?.entity === c.entity && before.accepted === true }
+    })
+    state.art9Layout = layout
+    state.art9Refusal = art9RefusalOf(r.me.settings?.art9Refusal)
+    if (!sameText || !refusalOffered()) state.art9Refused = false
+    state.me = r.me
+    state.steps = r.steps
+    state.reconsent = r.me.acceptances.rules === 'reconsent_required'
+    state.rulesText = r.texts.rules
+    state.rules = r.texts.rules ? communityRulesOf(r.texts.rules.bodyJson) : []
+    state.art9Text = r.texts.art9
+    state.art9Paragraphs = r.texts.art9 ? htmlToParagraphs(r.texts.art9.body) : []
+  }
+
+  async function load(): Promise<void> {
+    state.phase = 'loading'
+    state.failure = null
+    const r = await read()
+    if (!r) return
+    apply(r)
+    state.index = 0
+    if (r.steps.length === 0) {
+      // The give-consent flow with no consent left to ask (given in another tab, or the tenant stopped asking for it):
+      // nothing is sent — an empty me/onboard would be no consent — and the caller reads the state it is handed.
+      if (offerArt9) {
+        state.phase = 'done'
+        o.onDone(r.me)
+        return
+      }
+      // Nothing left to ask (another tab finished it): kb-api's answer settles the needs.
+      return submit()
+    }
+    state.phase = 'ready'
+  }
+
+  const step = (): OnboardingStep | null => state.steps[state.index] ?? null
+
+  /** Whether a step has its answer (a text accepted is the text shown). */
+  function answered(s: OnboardingStep): boolean {
+    switch (s) {
+      case 'age':
+        return state.ageBand !== null
+      case 'rules':
+        return state.rulesAccepted && state.rulesText !== null
+      case 'art9':
+        return state.art9Text !== null && (state.art9Accepted || (state.art9Refused && refusalOffered()))
+      case 'profile':
+        return isDisplayNameOk(state.displayName) && isHandleOk(state.handle)
+    }
+  }
+
+  function canContinue(): boolean {
+    const s = step()
+    if (state.phase !== 'ready' || s === null) return false
+    // „Pokračovat" on the art. 9 step means the consent: a refusal goes only through „Nesouhlasím" (refuse()), never
+    // silently through the primary button.
+    if (s === 'art9') return state.art9Text !== null && state.art9Accepted
+    return answered(s)
+  }
+
+  function goTo(s: OnboardingStep): void {
+    const i = state.steps.indexOf(s)
+    if (i >= 0) state.index = i
+  }
+
+  /** The first step without its answer, or -1. */
+  const firstOpen = (): number => state.steps.findIndex((s) => !answered(s))
+
+  async function submit(): Promise<void> {
+    // Every step shown has its answer before anything goes (a step a refusal added is still open).
+    const open = firstOpen()
+    if (open >= 0) {
+      state.index = open
+      return
+    }
+    state.phase = 'sending'
+    state.failure = null
+    state.fields = []
+    // kb-api records whatever current text id it gets: only the ones shown and ticked here go. The field itself is
+    // kb-api's schema's; empty is no text (checked only while the rules are still to accept, and then refused).
+    const input: OnboardInput = {
+      ageBand: state.ageBand ?? state.me?.member?.ageBand ?? '18_plus',
+      rulesTextId: state.steps.includes('rules') && state.rulesText ? state.rulesText.textId : '',
+    }
+    // A consent ticked wins over a refusal chosen before (the reader came back and ticked it).
+    let refusing = false
+    if (state.steps.includes('art9') && state.art9Text) {
+      if (state.art9Accepted) input.art9TextId = state.art9Text.textId
+      else if (state.art9Refused && refusalOffered()) {
+        input.art9Refused = true
+        refusing = true
+      }
+    }
+    if (state.steps.includes('profile')) {
+      input.displayName = normalizeName(state.displayName)
+      const handle = normalizeHandle(state.handle)
+      if (handle !== '') input.handle = handle
+      input.avatarPreset = state.avatarPreset
+    }
+    const r = await o.client.me.onboard(input, call)
+    if (r.ok) {
+      state.art9RefusedSent = refusing
+      state.phase = 'done'
+      o.onDone(r.value)
+      return
+    }
+    state.failure = r
+    state.phase = 'ready'
+    switch (r.code) {
+      case 'age':
+        // Two bands only: a refused band is 16–17 under an 18 minimum.
+        state.minAge = 18
+        state.phase = 'refused'
+        o.onRefused?.(state.minAge)
+        return
+      case 'name':
+        state.fields = normalizeHandle(state.handle) !== '' ? ['displayName', 'handle'] : ['displayName']
+        return goTo('profile')
+      case 'handle':
+        state.fields = ['handle']
+        return goTo('profile')
+      case 'invalid': {
+        state.fields = r.fields ?? []
+        // The tenant takes no refusal (now): the settings are read again, the consent asked, the reader told why.
+        if (refusalRefused(r)) {
+          state.art9Refused = false
+          return reread(r)
+        }
+        // A refusal kb-api did not take because a consent is in force already (another tab): read again.
+        if (state.fields.includes('art9Refused')) {
+          state.art9Refused = false
+          return reread(r)
+        }
+        if (state.fields.some((f) => PROFILE_FIELDS.has(f))) return goTo('profile')
+        if (state.fields.some((f) => TEXT_FIELDS.has(f))) return reread(r)
+        if (state.fields.includes('ageBand')) return goTo('age')
+        return
+      }
+      case 'signIn':
+        return o.onSignIn()
+      default:
+        return
+    }
+  }
+
+  /**
+   * kb-api refused a text id: a newer text was published meanwhile, or the art. 9 consent was switched on. What is
+   * left is read again from me/get — a step may be new, with its text —, the acceptance of a text kb-api named is
+   * asked again, and the reader goes to the first step left. Nothing is sent again by itself.
+   */
+  async function reread(refusal: CommunityFailure): Promise<void> {
+    const named = [...state.fields]
+    // The form stays as it is (disabled) while the steps are read again.
+    state.phase = 'sending'
+    const r = await read()
+    if (!r) return
+    apply(r)
+    if (named.includes('rulesTextId')) state.rulesAccepted = false
+    if (named.includes('art9TextId')) state.art9Accepted = false
+    state.failure = refusal
+    state.fields = named
+    const open = firstOpen()
+    if (open >= 0) {
+      state.index = open
+      state.phase = 'ready'
+      return
+    }
+    // Nothing this model can still ask: finished elsewhere (no need left), or a refusal it cannot answer — shown.
+    if (r.me.needs.filter(isKnownNeed).length === 0) {
+      state.phase = 'done'
+      o.onDone(r.me)
+      return
+    }
+    fail(refusal)
+  }
+
+  /** On to the next step, or — on the last one — `me/onboard`. */
+  async function advance(): Promise<void> {
+    state.failure = null
+    if (state.index < state.steps.length - 1) {
+      state.index += 1
+      return
+    }
+    await submit()
+  }
+
+  const canRefuse = (): boolean => state.phase === 'ready' && step() === 'art9' && state.art9Text !== null && refusalOffered()
+
+  return {
+    state,
+    load,
+    step,
+    isLast: () => state.index >= state.steps.length - 1,
+    canContinue,
+    async next() {
+      if (!canContinue()) return
+      // The consent given: a refusal chosen before on this step no longer stands.
+      if (step() === 'art9' && state.art9Accepted) state.art9Refused = false
+      await advance()
+    },
+    canRefuse,
+    async refuse() {
+      if (!canRefuse()) return
+      state.art9Accepted = false
+      state.art9Refused = true
+      await advance()
+    },
+    refusalOffered,
+    back() {
+      if (state.phase !== 'ready' || state.index === 0) return
+      state.failure = null
+      state.index -= 1
+      // Back on the art. 9 step: the reader chooses again — a refusal chosen before does not stand unseen.
+      if (step() === 'art9') state.art9Refused = false
+    },
+    suggestedHandle: () => (normalizeHandle(state.handle) === '' ? suggestedHandle(state.displayName) : null),
+    hasFieldError: (field) => state.fields.includes(field),
+  }
+}

package/src/core/outcomes.ts

@@ -0,0 +1,86 @@
+/**
+ * How a refusal reads (m1-contracts.md §10.2, §10.4): the client turns every kb-api and host code into one
+ * of COMMUNITY_UI_CODES; this turns that into the catalogue's sentence — `error.<code>`, or a sanction's
+ * own sentence with its end date — and says what the element does about it besides showing it.
+ */
+import type { CommunityFailure, CommunityMessageKey, CommunityUiCode } from '@blogmcp/sdk/community'
+import { formatDate } from './format'
+import type { Lang, TextRef } from './i18n'
+
+/** The sentence a refusal shows. Total over COMMUNITY_UI_CODES (test/outcomes.spec.ts). */
+export function failureText(failure: Pick<CommunityFailure, 'code' | 'until'>, lang: Lang): TextRef {
+  const until = failure.until ? formatDate(lang, failure.until) : ''
+  if (failure.code === 'restricted' && until) return { key: 'sanction.restrictionUntil', params: { date: until } }
+  if (failure.code === 'suspended' && until) return { key: 'sanction.suspensionUntil', params: { date: until } }
+  return { key: `error.${failure.code}` as CommunityMessageKey }
+}
+
+/** Seconds a refusal asks to wait before the same write may go (the burst, a quota, the limiter). */
+export const DEFAULT_WAIT_S: Partial<Record<CommunityUiCode, number>> = Object.freeze({ fast: 3, quota: 60 })
+
+/** The epoch milliseconds until which a write waits after `failure`, or null when it may go again at once. */
+export function waitUntilOf(failure: Pick<CommunityFailure, 'code' | 'retryAfterS'>, now: number): number | null {
+  const fallback = DEFAULT_WAIT_S[failure.code]
+  if (fallback === undefined) return null
+  const seconds = typeof failure.retryAfterS === 'number' && failure.retryAfterS > 0 ? failure.retryAfterS : fallback
+  return now + seconds * 1000
+}
+
+/** A countdown shows only for a short wait (a quota until midnight reads `error.quota` alone). */
+export const COUNTDOWN_MAX_S = 120
+
+/**
+ * What the element does with a refusal of a write, besides showing its sentence:
+ *   - `confirm`  the author confirms the codes and sends again (the Russmedia confirmation);
+ *   - `wait`     the write waits (a cooldown);
+ *   - `onboard`  the inline onboarding opens (ONBOARDING_REQUIRED);
+ *   - `reload`   the discussion is read again (the viewer's state changed: a sanction, a session);
+ *   - `notMoved` the discussion does not take writes yet: one sentence instead of the composer;
+ *   - `hide`     discussions are switched off: the element renders nothing (`realtimeOff`: only live updates are —
+ *                the element keeps polling and never hides the discussion for it);
+ *   - `retry`    nothing was decided (no answer, the ledger): the same write may go again as it is;
+ *   - `show`     anything else: the sentence, the text stays for the author to change.
+ */
+export type FailureEffect = 'confirm' | 'wait' | 'onboard' | 'reload' | 'notMoved' | 'hide' | 'retry' | 'show'
+
+const EFFECTS: Readonly<Record<CommunityUiCode, FailureEffect>> = Object.freeze({
+  method: 'show',
+  origin: 'show',
+  unavailable: 'retry',
+  invalid: 'show',
+  signIn: 'reload',
+  onboarding: 'onboard',
+  age: 'show',
+  name: 'show',
+  handle: 'show',
+  restricted: 'reload',
+  suspended: 'reload',
+  terminated: 'reload',
+  links: 'show',
+  fast: 'wait',
+  blocked: 'show',
+  confirm: 'confirm',
+  removed: 'reload',
+  quota: 'wait',
+  captcha: 'show',
+  notFound: 'reload',
+  surfaceOff: 'hide',
+  notMoved: 'notMoved',
+  ledger: 'retry',
+  // M2 (m2-contracts.md §3.1): a pause refuses every member write until it ends (`until`) — the write waits and the
+  // composer gives way to `state.braked`, and me/get is read again for the brake's end (reads go on).
+  braked: 'wait',
+  // A Pro feature of a module that went read_only: the member's state changed under the page — read it again.
+  readOnly: 'reload',
+  // Too many @mentions for the member's level: the sentence, and the text stays for the author to trim.
+  mentionLimit: 'show',
+  // A browser whose push service kb-api will not send to: the sentence; the switch stays off (the settings element).
+  pushRefused: 'show',
+  // Live updates are off here: nothing to show the reader — the discussion keeps polling (the realtime session's fallback).
+  realtimeOff: 'hide',
+  submit: 'show',
+} satisfies Record<CommunityUiCode, FailureEffect>)
+
+export function failureEffect(code: CommunityUiCode): FailureEffect {
+  return EFFECTS[code] ?? 'show'
+}