@blogmcp/community 0.0.0-stage → 0.1.0

package/src/core/panel.ts

@@ -0,0 +1,411 @@
+/**
+ * `<blogmcp-my-community>`'s brain (m1-contracts.md §7.4, §8.3, §10.4; community.md §5): the reader's
+ * „Moje komunita" — the statements of reasons about their content (the art. 17(3) fields, the appeal within
+ * its window, an open appeal's state), their reports, their notifications, the art. 9 consent's withdrawal,
+ * their blocks, the export (a JSON download) and the profile's deletion with its grace and cancel.
+ *
+ * With a decision id it shows that one statement (the host's statement page). With a notifier's receipt it
+ * shows that notice's status and appeal — `notices/status`, `notices/appeal`: no session needed for that.
+ */
+import { reactive } from 'vue'
+import {
+  COMMUNITY_APPEAL_MAX,
+  isKnownNotificationCode,
+  type AppealItem,
+  type BlockEntry,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type DecisionSummary,
+  type MemberExport,
+  type MyState,
+  type NoticeStatus,
+  type NotificationItem,
+  type OwnProfile,
+  type ReportItem,
+  type Statement,
+} from '@blogmcp/sdk/community'
+import type { TextRef } from './i18n'
+import { isDisplayNameOk, isHandleOk, normalizeHandle, normalizeName } from './names'
+import { codePointLength, normalizeBody } from './text'
+
+export type LoadPhase = 'idle' | 'loading' | 'ready' | 'failed'
+
+export interface AppealDraft {
+  body: string
+  sending: boolean
+  failure: CommunityFailure | null
+}
+
+export interface ProfileDraft {
+  displayName: string
+  handle: string
+  avatarPreset: string | null
+  sending: boolean
+  failure: CommunityFailure | null
+  fields: string[]
+}
+
+export interface PanelUi {
+  /** The member's part: `signIn` when the session cannot act as a member (or there is none). */
+  phase: LoadPhase | 'signIn'
+  failure: CommunityFailure | null
+  me: MyState | null
+  notifications: NotificationItem[]
+  decisions: DecisionSummary[]
+  appeals: AppealItem[]
+  reports: ReportItem[]
+  blocks: BlockEntry[]
+  /** The statement the page opens (`decision-id`). */
+  statement: { phase: LoadPhase | 'signIn'; value: Statement | null; failure: CommunityFailure | null; appeal: AppealDraft }
+  /** The notifier's part (`#t=` in the address). `missing`: a `#t=` that holds no receipt. */
+  notice: { phase: LoadPhase | 'missing'; value: NoticeStatus | null; failure: CommunityFailure | null; appeal: AppealDraft }
+  profile: ProfileDraft | null
+  /** The profile's deletion: its date once requested here (kb-api's MyState does not carry it). */
+  purgeAfter: string | null
+  exporting: boolean
+  busy: Record<string, boolean>
+  announcement: TextRef | null
+  announceId: number
+}
+
+export interface PanelController {
+  readonly state: PanelUi
+  /** The member's sections (me/get and the lists). */
+  loadMember(): Promise<void>
+  loadStatement(decisionId: string): Promise<void>
+  loadNotice(receipt: string | null): Promise<void>
+  unreadCount(): number
+  markAllRead(): Promise<void>
+  fileAppeal(): Promise<void>
+  withdrawAppeal(): Promise<void>
+  fileNoticeAppeal(): Promise<void>
+  withdrawNoticeAppeal(): Promise<void>
+  withdrawConsent(): Promise<boolean>
+  unblock(memberId: string): Promise<void>
+  editProfile(): void
+  cancelProfile(): void
+  saveProfile(): Promise<void>
+  /** `me/export` as a JSON file the browser saves (`save` does the download; tests pass their own). */
+  exportData(save: (data: MemberExport) => void): Promise<void>
+  erase(): Promise<boolean>
+  cancelErase(): Promise<void>
+  /** The member asked for the deletion (here or before). */
+  erasing(): boolean
+  appealLength(draft: AppealDraft): number
+  canAppealWith(draft: AppealDraft): boolean
+  dispose(): void
+}
+
+export interface PanelOptions {
+  client: CommunityClient
+  lang: string
+}
+
+const appealDraft = (): AppealDraft => ({ body: '', sending: false, failure: null })
+
+export function createPanel(o: PanelOptions): PanelController {
+  const { client } = o
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  const state = reactive<PanelUi>({
+    phase: 'idle',
+    failure: null,
+    me: null,
+    notifications: [],
+    decisions: [],
+    appeals: [],
+    reports: [],
+    blocks: [],
+    statement: { phase: 'idle', value: null, failure: null, appeal: appealDraft() },
+    notice: { phase: 'idle', value: null, failure: null, appeal: appealDraft() },
+    profile: null,
+    purgeAfter: null,
+    exporting: false,
+    busy: {},
+    announcement: null,
+    announceId: 0,
+  }) as PanelUi
+  let disposed = false
+
+  const announce = (text: TextRef): void => {
+    state.announcement = text
+    state.announceId += 1
+  }
+  const failureRef = (f: CommunityFailure): TextRef => ({ key: `error.${f.code}` as TextRef['key'] })
+
+  async function loadMember(): Promise<void> {
+    state.phase = 'loading'
+    state.failure = null
+    const me = await client.me.get(call)
+    if (disposed) return
+    if (!me.ok) {
+      if (me.code === 'signIn') {
+        state.phase = 'signIn'
+        return
+      }
+      state.phase = 'failed'
+      state.failure = me
+      return
+    }
+    state.me = me.value
+    if (me.value.needs.includes('sign_in')) {
+      state.phase = 'signIn'
+      return
+    }
+    if (!me.value.member) {
+      // Signed in, never joined: nothing of theirs to list yet.
+      state.phase = 'ready'
+      return
+    }
+    const [notifications, decisions, appeals, reports, blocks] = await Promise.all([
+      client.me.notifications.list({}, call),
+      client.me.decisions.list({}, call),
+      client.me.appeals.list(call),
+      client.me.reports.list(call),
+      client.blocks.list(call),
+    ])
+    if (disposed) return
+    if (notifications.ok) state.notifications = notifications.value.items.filter((n) => isKnownNotificationCode(n.code))
+    if (decisions.ok) state.decisions = [...decisions.value.items]
+    if (appeals.ok) state.appeals = [...appeals.value.items]
+    if (reports.ok) state.reports = [...reports.value.items]
+    if (blocks.ok) state.blocks = [...blocks.value.blocks]
+    const first = [notifications, decisions, appeals, reports, blocks].find((r) => !r.ok)
+    if (first && !first.ok) announce(failureRef(first))
+    state.phase = 'ready'
+  }
+
+  // The statement the page shows now, and its load: a host that reuses the element for another decision-id
+  // (client-side navigation) must never see the late answer for the one before (nor appeal that one there).
+  let statementId: string | null = null
+  let statementLoad = 0
+
+  async function loadStatement(decisionId: string): Promise<void> {
+    const ticket = ++statementLoad
+    if (decisionId !== statementId) {
+      // Another decision: nothing of the one before stays on its page — its text, the appeal typed under it.
+      statementId = decisionId
+      state.statement.value = null
+      state.statement.appeal = appealDraft()
+    }
+    state.statement.phase = 'loading'
+    state.statement.failure = null
+    const r = await client.me.decisions.get({ decisionId }, call)
+    if (disposed || ticket !== statementLoad) return
+    if (r.ok) {
+      state.statement.value = r.value
+      state.statement.phase = 'ready'
+      return
+    }
+    state.statement.failure = r
+    state.statement.phase = r.code === 'signIn' ? 'signIn' : 'failed'
+  }
+
+  async function loadNotice(receipt: string | null): Promise<void> {
+    if (receipt === null) {
+      state.notice.phase = 'missing'
+      return
+    }
+    state.notice.phase = 'loading'
+    state.notice.failure = null
+    const r = await client.notices.status({ receipt }, call)
+    if (disposed) return
+    if (r.ok) {
+      state.notice.value = r.value
+      state.notice.phase = 'ready'
+      return
+    }
+    state.notice.failure = r
+    state.notice.phase = 'failed'
+  }
+  // The receipt is the notifier's capability: kept in this closure only, never in the state a view renders.
+  let noticeReceipt: string | null = null
+
+  const appealLength = (d: AppealDraft): number => codePointLength(normalizeBody(d.body))
+  const canAppealWith = (d: AppealDraft): boolean => !d.sending && appealLength(d) > 0 && appealLength(d) <= COMMUNITY_APPEAL_MAX
+
+  return {
+    state,
+    loadMember,
+    loadStatement,
+    async loadNotice(receipt) {
+      noticeReceipt = receipt
+      await loadNotice(receipt)
+    },
+    unreadCount: () => state.notifications.filter((n) => n.readAt === null).length,
+    async markAllRead() {
+      const ids = state.notifications.filter((n) => n.readAt === null).map((n) => n.id)
+      if (ids.length === 0 || state.busy.markRead) return
+      state.busy.markRead = true
+      const r = await client.me.notifications.markRead({ ids }, call)
+      delete state.busy.markRead
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      const at = new Date().toISOString()
+      state.notifications = state.notifications.map((n) => (ids.includes(n.id) ? { ...n, readAt: at } : n))
+    },
+    async fileAppeal() {
+      const s = state.statement
+      const d = s.appeal
+      if (!s.value || !s.value.canAppeal || !canAppealWith(d)) return
+      const decisionId = s.value.decisionId
+      d.sending = true
+      d.failure = null
+      const r = await client.me.appeals.file({ decisionId, body: normalizeBody(d.body) }, call)
+      d.sending = false
+      // The page moved on to another statement meanwhile: the answer is that one's no more.
+      if (disposed || decisionId !== statementId) return
+      if (!r.ok) {
+        d.failure = r
+        return
+      }
+      d.body = ''
+      announce({ key: 'statement.appealSent' })
+      await loadStatement(decisionId)
+    },
+    async withdrawAppeal() {
+      const s = state.statement
+      const open = s.value?.appeal
+      if (!s.value || !open || open.status !== 'open' || state.busy.withdraw) return
+      const decisionId = s.value.decisionId
+      state.busy.withdraw = true
+      const r = await client.me.appeals.withdraw({ appealId: open.appealId }, call)
+      delete state.busy.withdraw
+      if (disposed || decisionId !== statementId) return
+      if (!r.ok) return announce(failureRef(r))
+      announce({ key: 'statement.appealWithdrawn' })
+      await loadStatement(decisionId)
+    },
+    async fileNoticeAppeal() {
+      const n = state.notice
+      const d = n.appeal
+      if (!n.value || !n.value.appeal.canAppeal || noticeReceipt === null || !canAppealWith(d)) return
+      d.sending = true
+      d.failure = null
+      const r = await client.notices.appeal({ receipt: noticeReceipt, body: normalizeBody(d.body) }, call)
+      d.sending = false
+      if (disposed) return
+      if (!r.ok) {
+        d.failure = r
+        return
+      }
+      d.body = ''
+      announce({ key: 'notice.appealSent' })
+      await loadNotice(noticeReceipt)
+    },
+    async withdrawNoticeAppeal() {
+      if (!state.notice.value?.appeal.open || noticeReceipt === null || state.busy.noticeWithdraw) return
+      state.busy.noticeWithdraw = true
+      const r = await client.notices.withdrawAppeal({ receipt: noticeReceipt }, call)
+      delete state.busy.noticeWithdraw
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      announce({ key: 'statement.appealWithdrawn' })
+      await loadNotice(noticeReceipt)
+    },
+    async withdrawConsent() {
+      if (state.busy.consent) return false
+      state.busy.consent = true
+      const r = await client.me.consents.withdraw({ kind: 'art9_consent' }, call)
+      delete state.busy.consent
+      if (disposed) return false
+      if (!r.ok) {
+        announce(failureRef(r))
+        return false
+      }
+      if (state.me) state.me = { ...state.me, acceptances: { ...state.me.acceptances, art9Consent: r.value.state as MyState['acceptances']['rules'] } }
+      announce({ key: 'panel.art9Withdrawn' })
+      return true
+    },
+    async unblock(memberId) {
+      const key = `block:${memberId}`
+      if (state.busy[key]) return
+      state.busy[key] = true
+      const r = await client.blocks.set({ memberId, blocked: false }, call)
+      delete state.busy[key]
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      state.blocks = state.blocks.filter((b) => b.memberId !== memberId)
+      announce({ key: 'discussion.unblocked' })
+    },
+    editProfile() {
+      const p: OwnProfile | null | undefined = state.me?.profile
+      if (!p) return
+      state.profile = { displayName: p.displayName, handle: p.handle, avatarPreset: p.avatarPreset, sending: false, failure: null, fields: [] }
+    },
+    cancelProfile() {
+      state.profile = null
+    },
+    async saveProfile() {
+      const d = state.profile
+      const current = state.me?.profile
+      if (!d || !current || d.sending || !isDisplayNameOk(d.displayName) || !isHandleOk(d.handle) || normalizeHandle(d.handle) === '') return
+      const input: { displayName?: string; handle?: string; avatarPreset?: string | null } = {}
+      const name = normalizeName(d.displayName)
+      const handle = normalizeHandle(d.handle)
+      if (name !== current.displayName) input.displayName = name
+      if (handle !== current.handle) input.handle = handle
+      if (d.avatarPreset !== current.avatarPreset) input.avatarPreset = d.avatarPreset
+      if (Object.keys(input).length === 0) {
+        state.profile = null
+        return
+      }
+      d.sending = true
+      d.failure = null
+      d.fields = []
+      const r = await client.me.updateProfile(input, call)
+      d.sending = false
+      if (disposed) return
+      if (!r.ok) {
+        d.failure = r
+        d.fields = r.code === 'handle' ? ['handle'] : r.code === 'name' ? ['displayName'] : (r.fields ?? [])
+        return
+      }
+      // The form closes on the new values (the catalogue has no sentence for a saved profile).
+      if (state.me) state.me = { ...state.me, profile: r.value.profile }
+      state.profile = null
+    },
+    async exportData(save) {
+      if (state.exporting) return
+      state.exporting = true
+      const r = await client.me.export(call)
+      state.exporting = false
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      save(r.value)
+    },
+    async erase() {
+      if (state.busy.erase) return false
+      state.busy.erase = true
+      const r = await client.me.erase(call)
+      delete state.busy.erase
+      if (disposed) return false
+      if (!r.ok) {
+        announce(failureRef(r))
+        return false
+      }
+      state.purgeAfter = r.value.purgeAfter
+      if (state.me?.member) state.me = { ...state.me, member: { ...state.me.member, status: r.value.status } }
+      return true
+    },
+    async cancelErase() {
+      if (state.busy.erase) return
+      state.busy.erase = true
+      const r = await client.me.cancelErase(call)
+      delete state.busy.erase
+      if (disposed) return
+      if (!r.ok) return announce(failureRef(r))
+      state.purgeAfter = null
+      if (state.me?.member) state.me = { ...state.me, member: { ...state.me.member, status: r.value.status } }
+      announce({ key: 'panel.eraseCancelled' })
+    },
+    erasing: () => state.me?.member?.status === 'deletion_requested',
+    appealLength,
+    canAppealWith,
+    dispose() {
+      disposed = true
+      abort.abort()
+    },
+  }
+}

package/src/core/receipt.ts

@@ -0,0 +1,28 @@
+/**
+ * A notifier's receipt as `<blogmcp-my-community>` takes it (m1-contracts.md §7.9, §10.2; community.md invariant 8):
+ * from its OWN page's address only — `#t=` in `location.hash` when it mounts —, and the address bar cleared at once
+ * (the SDK's readReceiptFromHash, which also clears the router's copy in `history.state`).
+ *
+ * That reader remembers the receipt for the whole window too (so a framework that mounts a page twice still gets
+ * it), and hands it back with no fragment in the address. An element never takes that for its page's: a later page
+ * of the same tab — a client-side navigation, the next person at a shared device — would ask for the notifier's
+ * case again and offer its appeal. What an element took it keeps for itself (the same element put back by its host
+ * shows it again); no other element sees it.
+ */
+import { readReceiptFromHash, receiptFromHash } from '@blogmcp/sdk/community'
+
+const taken = new WeakMap<object, string | null>()
+
+/**
+ * The receipt this element's page carries: a string; `null` for a `#t=` that holds none (a cut link — "incomplete",
+ * never an older receipt of the tab); `undefined` when the page carries none for it.
+ */
+export function receiptForElement(owner: object | null): string | null | undefined {
+  if (typeof location !== 'undefined' && location.hash.startsWith('#t=')) {
+    const receipt = receiptFromHash(location.hash)
+    readReceiptFromHash()
+    if (owner) taken.set(owner, receipt)
+    return receipt
+  }
+  return owner && taken.has(owner) ? (taken.get(owner) ?? null) : undefined
+}

package/src/core/text.ts

@@ -0,0 +1,142 @@
+/**
+ * Text, and only text (m1-contracts.md §10.4, community.md §7.7): what a member wrote is rendered as text
+ * nodes — never HTML, never markdown. A web address in it becomes a link only through @blogmcp/sanitize's
+ * `sanitizeUrl`, and the view gives every such link `rel="nofollow ugc noopener noreferrer"` and
+ * `target="_blank"`. test/text-only.spec.ts bans `v-html`, `innerHTML` and any HTML parser in src/.
+ */
+import { sanitizeUrl } from '@blogmcp/sanitize/url'
+
+export type TextSegment =
+  | { readonly kind: 'text'; readonly text: string }
+  | { readonly kind: 'link'; readonly text: string; readonly href: string }
+
+/** The rel every link to what a member wrote carries (user-generated, no referrer, no opener). */
+export const UGC_LINK_REL = 'nofollow ugc noopener noreferrer'
+
+/** A web address as people write it: `http(s)://` or `www.`, up to a blank or a character no address carries. */
+const URL_RE = /\b(?:https?:\/\/|www\.)[^\s<>"'`{}|\\^]+/gi
+/** Characters that end a sentence more often than an address. */
+const TRAILING = '.,;:!?…\'"»”’]'
+
+/** The address without the punctuation after it; a `)` stays when it closes a `(` inside the address. */
+function trimUrl(raw: string): string {
+  let url = raw
+  while (url.length > 0) {
+    const last = url[url.length - 1]!
+    if (last === ')') {
+      const opens = url.split('(').length - 1
+      const closes = url.split(')').length - 1
+      if (closes <= opens) break
+    } else if (!TRAILING.includes(last)) {
+      break
+    }
+    url = url.slice(0, -1)
+  }
+  return url
+}
+
+/** The link target of an address, or null: only http and https survive sanitizeUrl as a link. */
+function safeHref(url: string): string | null {
+  const candidate = /^www\./i.test(url) ? `https://${url}` : url
+  // A bare scheme is no address.
+  if (/^https?:\/\/$/i.test(candidate)) return null
+  const safe = sanitizeUrl(candidate)
+  return safe !== 'about:blank' && /^https?:\/\//i.test(safe) ? safe : null
+}
+
+/** A member's text as text runs and links. */
+export function linkify(text: string): TextSegment[] {
+  const out: TextSegment[] = []
+  if (typeof text !== 'string' || text === '') return out
+  let at = 0
+  for (const m of text.matchAll(URL_RE)) {
+    const start = m.index ?? 0
+    if (start < at) continue
+    const url = trimUrl(m[0])
+    const href = url ? safeHref(url) : null
+    if (!href) continue
+    if (start > at) out.push({ kind: 'text', text: text.slice(at, start) })
+    out.push({ kind: 'link', text: url, href })
+    at = start + url.length
+  }
+  if (at < text.length) out.push({ kind: 'text', text: text.slice(at) })
+  return out
+}
+
+/** Characters in code points, as kb-api counts a body (after NFC and trimming). */
+export function codePointLength(text: string): number {
+  let n = 0
+  for (const _ of text) n++
+  return n
+}
+
+/** A body as kb-api will measure it: NFC, trimmed. */
+export function normalizeBody(text: string): string {
+  return typeof text === 'string' ? text.normalize('NFC').trim() : ''
+}
+
+const ENTITIES: Readonly<Record<string, string>> = Object.freeze({
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  ndash: '–',
+  mdash: '—',
+  hellip: '…',
+  laquo: '«',
+  raquo: '»',
+  bdquo: '„',
+  ldquo: '“',
+  rdquo: '”',
+  lsquo: '‘',
+  rsquo: '’',
+  sbquo: '‚',
+  copy: '©',
+  reg: '®',
+  euro: '€',
+  shy: '',
+})
+
+function decodeEntities(text: string): string {
+  return text.replace(/&(#\d{1,7}|#x[0-9a-f]{1,6}|[a-z]{2,8});/gi, (match, entity: string) => {
+    if (entity[0] === '#') {
+      const hex = entity[1] === 'x' || entity[1] === 'X'
+      const cp = Number.parseInt(entity.slice(hex ? 2 : 1), hex ? 16 : 10)
+      return cp > 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff) ? String.fromCodePoint(cp) : match
+    }
+    return ENTITIES[entity.toLowerCase()] ?? match
+  })
+}
+
+/** Elements whose end closes a paragraph of the text. */
+const BLOCK_END = /<\/(?:p|div|li|h[1-6]|section|article|blockquote|tr|ul|ol|dl|dt|dd|header|footer|table|pre|figure)\s*>/gi
+/** Elements whose start opens one. */
+const BLOCK_START = /<(?:li|tr|dt|dd|h[1-6]|blockquote|pre|figure)\b[^>]*>/gi
+
+/**
+ * The paragraphs of the tenant's own legal text (`legal/current`'s `body` is HTML with anchors) as plain
+ * text, for the art. 9 consent step: tags are dropped and entities decoded AFTER that, so nothing in the
+ * text is ever parsed as markup again. String work only — no HTML parser, no live DOM.
+ */
+export function htmlToParagraphs(html: string): string[] {
+  if (typeof html !== 'string' || html === '') return []
+  const text = html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(script|style|template|noscript|svg|math)\b[\s\S]*?<\/\1\s*>/gi, '')
+    .replace(/[\t\n\r\f ]+/g, ' ')
+    .replace(/<br\b[^>]*>/gi, '\n')
+    .replace(BLOCK_END, '\n\n')
+    .replace(BLOCK_START, '\n\n')
+    .replace(/<[^>]*>/g, '')
+  return decodeEntities(text)
+    .split(/\n{2,}/)
+    .map((p) =>
+      p
+        .replace(/ *\n */g, '\n')
+        .replace(/[  ]{2,}/g, ' ')
+        .trim(),
+    )
+    .filter((p) => p !== '')
+}

package/src/core/turnstile.ts

@@ -0,0 +1,98 @@
+/**
+ * Cloudflare Turnstile for the notice form, by the storefront's TurnstileWidget rules: rendered explicitly,
+ * the script loaded only when a notice form mounts (no other page sends Cloudflare a byte), the token
+ * one-shot — kb-api spends it on siteverify whatever the answer, so the form asks for a new one after every
+ * failure — and a form whose script did not load cannot be sent.
+ *
+ * The widget is rendered into an element in the custom element's LIGHT DOM (projected through a slot):
+ * Turnstile's iframe then lives in the page's own document, as on any other site.
+ */
+import { COMMUNITY_NOTICE_TURNSTILE_ACTION } from '@blogmcp/sdk/community'
+
+export const TURNSTILE_SCRIPT_SRC = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit'
+
+interface TurnstileRenderOptions {
+  sitekey: string
+  action?: string
+  language?: string
+  appearance?: 'always' | 'execute' | 'interaction-only'
+  callback?: (token: string) => void
+  'expired-callback'?: () => void
+  'error-callback'?: () => void
+  'timeout-callback'?: () => void
+}
+
+export interface TurnstileApi {
+  render(el: HTMLElement, options: TurnstileRenderOptions): string
+  reset(widgetId: string): void
+  remove(widgetId: string): void
+}
+
+type TurnstileWindow = Window & { turnstile?: TurnstileApi }
+
+let scriptPromise: Promise<TurnstileApi> | null = null
+
+/** One `<script>` per page however many forms mount; a failed load may be tried again later. */
+export function loadTurnstile(nonce?: string): Promise<TurnstileApi> {
+  const w = window as TurnstileWindow
+  if (w.turnstile) return Promise.resolve(w.turnstile)
+  if (scriptPromise) return scriptPromise
+  scriptPromise = new Promise<TurnstileApi>((resolve, reject) => {
+    const script = document.createElement('script')
+    script.src = TURNSTILE_SCRIPT_SRC
+    script.async = true
+    script.defer = true
+    if (nonce) script.nonce = nonce
+    script.onload = () => (w.turnstile ? resolve(w.turnstile) : reject(new Error('[blogmcp-community] the Turnstile script loaded without its API')))
+    script.onerror = () => reject(new Error('[blogmcp-community] the Turnstile script failed to load'))
+    document.head.appendChild(script)
+  }).catch((err: unknown) => {
+    scriptPromise = null
+    throw err
+  })
+  return scriptPromise
+}
+
+export interface TurnstileWidget {
+  /** A fresh token (the last one is spent). */
+  reset(): void
+  remove(): void
+}
+
+export interface RenderTurnstileOptions {
+  siteKey: string
+  language: string
+  /** A new token, or null when it expired or failed (the form cannot be sent until a new one comes). */
+  onToken(token: string | null): void
+  nonce?: string
+}
+
+/** The widget in `container`; rejects when the script cannot load (an ad blocker, the network). */
+export async function renderTurnstile(container: HTMLElement, o: RenderTurnstileOptions): Promise<TurnstileWidget> {
+  const api = await loadTurnstile(o.nonce)
+  const id = api.render(container, {
+    sitekey: o.siteKey,
+    // kb-api refuses a token issued for any other action.
+    action: COMMUNITY_NOTICE_TURNSTILE_ACTION,
+    language: o.language,
+    // Visible only when Cloudflare really wants an interaction.
+    appearance: 'interaction-only',
+    callback: (token) => o.onToken(token),
+    'expired-callback': () => o.onToken(null),
+    'error-callback': () => o.onToken(null),
+    'timeout-callback': () => o.onToken(null),
+  })
+  let removed = false
+  return {
+    reset() {
+      if (removed) return
+      o.onToken(null)
+      api.reset(id)
+    },
+    remove() {
+      if (removed) return
+      removed = true
+      api.remove(id)
+    },
+  }
+}