@blogmcp/community 0.1.0 → 0.2.0

package/src/core/push.ts

@@ -0,0 +1,174 @@
+/**
+ * The browser's half of web push (m2-contracts.md §3.4): the one module of the elements that touches the service
+ * worker and the PushManager (test/closed-paths.spec.ts lets `serviceWorker` appear here and nowhere else).
+ *
+ * The worker is registered only from `<blogmcp-member-settings>`, on the member's click („Zapnout upozornění"),
+ * never on page load; the worker's script is the host's route (`sw-path`, default `<site-base>/sw.js`, served from
+ * `@blogmcp/sdk/community/sw`). The subscription's keys go to kb-api through the SDK client only.
+ *
+ * Feature checks read the browser's globals on call (never on import), so a server render and a test can swap them.
+ */
+import { isInAppBrowser, type PushUserAgentClass } from '@blogmcp/sdk/community'
+
+/** What the browser can do about push, in the order the settings element asks. */
+export type PushSupport =
+  /** Facebook's or Instagram's in-app browser: „Otevřít v prohlížeči" with the page's URL instead. */
+  | 'inApp'
+  /** iOS outside an installed web app (`navigator.standalone !== true`): the install guide instead. */
+  | 'iosInstall'
+  /** No service worker, PushManager or Notification: one sentence. */
+  | 'unsupported'
+  | 'supported'
+
+/** The navigator as far as push reads it (Safari's `standalone` included). */
+interface PushNavigator {
+  readonly userAgent?: string
+  readonly platform?: string
+  readonly maxTouchPoints?: number
+  readonly standalone?: boolean
+  readonly serviceWorker?: ServiceWorkerContainer
+}
+
+const nav = (): PushNavigator | null => (typeof navigator === 'undefined' ? null : (navigator as unknown as PushNavigator))
+
+/** The global Notification API, or null. */
+function notificationApi(): { permission: NotificationPermission; requestPermission(): Promise<NotificationPermission> } | null {
+  const g = globalThis as { Notification?: { permission: NotificationPermission; requestPermission(): Promise<NotificationPermission> } }
+  return g.Notification && typeof g.Notification.requestPermission === 'function' ? g.Notification : null
+}
+
+/**
+ * iOS (an iPhone, an iPod, an iPad — which reports itself as a Mac with a touch screen): its browsers take web push
+ * only from a website installed to the home screen. A layout hint, never sent anywhere but as `userAgentClass`.
+ */
+export function isIos(n: PushNavigator | null = nav()): boolean {
+  if (!n) return false
+  const ua = n.userAgent ?? ''
+  return /iPhone|iPad|iPod/.test(ua) || (n.platform === 'MacIntel' && (n.maxTouchPoints ?? 0) > 1)
+}
+
+/** What `me/push/subscribe` is told this browser is (a class, never the user agent itself). */
+export function userAgentClass(n: PushNavigator | null = nav()): PushUserAgentClass {
+  if (!n) return 'other'
+  if (isIos(n)) return 'ios'
+  const ua = n.userAgent ?? ''
+  if (/Android/.test(ua)) return 'android'
+  if (/Mobi|Tablet/.test(ua)) return 'other'
+  return ua === '' ? 'other' : 'desktop'
+}
+
+/** What this browser can do about push (the in-app browser first, then iOS outside the home screen). */
+export function pushSupport(): PushSupport {
+  const n = nav()
+  if (!n) return 'unsupported'
+  if (isInAppBrowser(n.userAgent ?? '')) return 'inApp'
+  if (isIos(n) && n.standalone !== true) return 'iosInstall'
+  const g = globalThis as { PushManager?: unknown }
+  if (!n.serviceWorker || typeof n.serviceWorker.register !== 'function' || typeof g.PushManager === 'undefined' || !notificationApi()) return 'unsupported'
+  return 'supported'
+}
+
+/** The browser's notification permission (`default` where there is no Notification API). */
+export function notificationPermission(): NotificationPermission {
+  return notificationApi()?.permission ?? 'default'
+}
+
+/** Ask for the permission (only on the member's click); `denied` where it cannot be asked. */
+export async function requestNotificationPermission(): Promise<NotificationPermission> {
+  const api = notificationApi()
+  if (!api) return 'denied'
+  if (api.permission !== 'default') return api.permission
+  try {
+    return await api.requestPermission()
+  } catch {
+    return 'denied'
+  }
+}
+
+/** The worker's registration for this page (null where none is registered or it cannot be asked). */
+export async function currentRegistration(): Promise<ServiceWorkerRegistration | null> {
+  const sw = nav()?.serviceWorker
+  if (!sw || typeof sw.getRegistration !== 'function') return null
+  try {
+    return (await sw.getRegistration()) ?? null
+  } catch {
+    return null
+  }
+}
+
+/** Register the host's worker script (the member's click). Throws what the browser throws. */
+export async function registerWorker(swPath: string): Promise<ServiceWorkerRegistration> {
+  const sw = nav()?.serviceWorker
+  if (!sw) throw new Error('[blogmcp-community] no service worker support')
+  return sw.register(swPath)
+}
+
+/** The browser's current subscription of a registration, or null. */
+export async function currentSubscription(reg: ServiceWorkerRegistration | null): Promise<PushSubscription | null> {
+  if (!reg?.pushManager || typeof reg.pushManager.getSubscription !== 'function') return null
+  try {
+    return (await reg.pushManager.getSubscription()) ?? null
+  } catch {
+    return null
+  }
+}
+
+/** base64url (the VAPID public key `me/push/vapid` sends) → the bytes `applicationServerKey` takes; null when malformed. */
+export function base64UrlBytes(value: string): Uint8Array | null {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+={0,2}$/.test(value)) return null
+  const b64 = value.replace(/=+$/, '').replace(/-/g, '+').replace(/_/g, '/')
+  const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4)
+  try {
+    const raw = atob(padded)
+    const out = new Uint8Array(raw.length)
+    for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i)
+    return out
+  } catch {
+    return null
+  }
+}
+
+/** A subscription as `me/push/subscribe` takes it (`toJSON()`'s endpoint and keys), or null when one is missing. */
+export function subscriptionInput(sub: PushSubscription): { endpoint: string; keys: { p256dh: string; auth: string } } | null {
+  const json = typeof sub.toJSON === 'function' ? sub.toJSON() : null
+  const endpoint = json?.endpoint ?? sub.endpoint
+  const p256dh = json?.keys?.p256dh
+  const auth = json?.keys?.auth
+  if (typeof endpoint !== 'string' || typeof p256dh !== 'string' || typeof auth !== 'string') return null
+  return { endpoint, keys: { p256dh, auth } }
+}
+
+/**
+ * Whose subscription this browser holds and the VAPID key id it was made for, kept per browser (a convenience):
+ * `{ memberId, keyId }` under one key. A subscription another member made here (a shared browser), or one without
+ * a record (blocked storage, made before), is not shown as this member's; one made for another key id is gone after
+ * a rotation (kb-api deleted it), so the switch asks to be turned on again. Every access is guarded: storage may be
+ * blocked.
+ */
+const PUSH_STORAGE = 'blogmcp-community:push-key-id'
+
+export interface StoredPush {
+  readonly memberId: string
+  readonly keyId: string
+}
+
+export function storedPush(): StoredPush | null {
+  try {
+    const raw = typeof localStorage === 'undefined' ? null : localStorage.getItem(PUSH_STORAGE)
+    if (raw === null) return null
+    const v = JSON.parse(raw) as { memberId?: unknown; keyId?: unknown } | null
+    return v && typeof v.memberId === 'string' && typeof v.keyId === 'string' ? { memberId: v.memberId, keyId: v.keyId } : null
+  } catch {
+    return null
+  }
+}
+
+export function storePush(value: StoredPush | null): void {
+  try {
+    if (typeof localStorage === 'undefined') return
+    if (value === null) localStorage.removeItem(PUSH_STORAGE)
+    else localStorage.setItem(PUSH_STORAGE, JSON.stringify({ memberId: value.memberId, keyId: value.keyId }))
+  } catch {
+    // Blocked storage: the next visit shows the switch off (whose it is cannot be told); kb-api's module_push_reset still tells a rotation.
+  }
+}

package/src/core/realtime.ts

@@ -0,0 +1,39 @@
+/**
+ * The discussion's live updates (m2-contracts.md §3.5, §3.10): `<blogmcp-discussion>` takes a `realtime` PROPERTY —
+ * the session factory of `@blogmcp/sdk/community/realtime`, which the HOST imports and passes:
+ *
+ *   import { createRealtimeSession } from '@blogmcp/sdk/community/realtime'
+ *   mountDiscussion({ articleId, realtime: createRealtimeSession })   // or el.realtime = createRealtimeSession
+ *
+ * The element calls it with its own client and discussion store after the first `discussions/list`, and `stop()`s
+ * the session when it unmounts. The element never imports the realtime entry (nor `centrifuge`): a site that passes no
+ * factory ships no socket code, and the discussion polls (`pollDiscussionHead`) as before.
+ *
+ * The types here are the factory's shape as far as the element uses it, so `createRealtimeSession` fits as it is.
+ */
+import type { CommunityClient, DiscussionStore } from '@blogmcp/sdk/community'
+
+/** `connecting`, `live`, `polling` (live updates are off or the server cut the socket for good), `stopped`. */
+export type DiscussionRealtimeMode = 'connecting' | 'live' | 'polling' | 'stopped' | (string & {})
+
+/** What the element calls the factory with. */
+export interface DiscussionRealtimeOptions {
+  client: CommunityClient
+  store: DiscussionStore
+  /** The discussion's language, for the session's re-reads. */
+  languageCode: string
+  /** Whether the discussion is seen now (the fallback polls only then). */
+  visible: () => boolean
+  /** The element's poll interval, for the session's fallback poller (absent: the SDK's default). */
+  pollIntervalMs?: number
+  onMode: (mode: DiscussionRealtimeMode) => void
+}
+
+/** A running session, as far as the element uses it. */
+export interface DiscussionRealtimeSession {
+  readonly mode: DiscussionRealtimeMode
+  stop(): void
+}
+
+/** `createRealtimeSession` of `@blogmcp/sdk/community/realtime`, or any function of its shape. */
+export type DiscussionRealtime = (options: DiscussionRealtimeOptions) => DiscussionRealtimeSession

package/src/core/settings.ts

@@ -0,0 +1,363 @@
+/**
+ * `<blogmcp-member-settings>`'s brain (m2-contracts.md §3.3, §3.4, §3.10):
+ *
+ *   - the six switches of `me/settings/get`, each saved on its own (`me/settings/update` with that one switch);
+ *   - this browser's push: shown only while `me/get`'s `module.features.push`; „Zapnout upozornění" (the member's
+ *     click, never on load) registers the host's worker (`swPath`), asks `me/push/vapid`, subscribes the PushManager
+ *     (`userVisibleOnly`, the VAPID key) and hands the subscription to `me/push/subscribe`; „Vypnout" ends the browser's
+ *     subscription and `me/push/unsubscribe`s it. A subscription made for another VAPID key id (a rotation), or an
+ *     unread `module_push_reset` notification, asks the member to switch it on again. The switch reads on only for a
+ *     subscription this member made here (another member's on a shared browser reads off), for the current key,
+ *     with the permission granted, that kb-api still holds: on load the page ASKS `me/push/status { endpoint }`
+ *     (M2 T10, D-M2-10) — no worker registered, no permission asked, nothing subscribed. kb-api drops a
+ *     subscription without telling the page (a revoked session, „Odhlásit všude", a dead endpoint): `subscribed:
+ *     false` reads off and stays off until the member presses „Zapnout upozornění" (the subscribe flow below) — a
+ *     sign-out everywhere never brings push back on its own. A status kb-api cannot give (unavailable, a refusal)
+ *     reads off too, without a sentence;
+ *   - a signed-in reader who has not joined yet sees the switches too (kb-api answers the defaults, the first save
+ *     makes the member); this browser's push waits for the member;
+ *   - the digest's unsubscribe link: the `#u=<token>` the e-mail's link carries is read once and cleared from the
+ *     address bar (the SDK's readDigestTokenFromHash); it is POSTed only on the member's click — a mail scanner that
+ *     opens the link must not unsubscribe anyone — and it needs no session.
+ */
+import { reactive } from 'vue'
+import {
+  isKnownModuleState,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type MemberSettings,
+  type ModuleInfo,
+} from '@blogmcp/sdk/community'
+import type { TextRef } from './i18n'
+import {
+  base64UrlBytes,
+  currentRegistration,
+  currentSubscription,
+  notificationPermission,
+  pushSupport,
+  registerWorker,
+  requestNotificationPermission,
+  storedPush,
+  storePush,
+  subscriptionInput,
+  userAgentClass,
+  type PushSupport,
+} from './push'
+
+/** The six switches, in the order the page shows them. */
+export const SETTING_KEYS = ['notifyReply', 'notifyMention', 'notifyTopic', 'pushEnabled', 'digestEmail', 'quietHours'] as const
+export type SettingKey = (typeof SETTING_KEYS)[number]
+
+export type SettingsPhase = 'idle' | 'loading' | 'ready' | 'failed' | 'signIn'
+
+/** This browser's push: off, on, or on its way (`busy`), and what the page tells the member about it. */
+export interface PushUi {
+  support: PushSupport
+  /** `checking` until the browser's own subscription was looked at. */
+  status: 'checking' | 'off' | 'on' | 'busy'
+  /** `denied` the browser's permission; `refused` kb-api's (pushRefused); `reset` switch it on again. */
+  note: 'denied' | 'refused' | 'reset' | null
+  failure: CommunityFailure | null
+}
+
+export interface DigestUi {
+  /** An unsubscribe link brought the member here: the button is offered. */
+  offered: boolean
+  sending: boolean
+  outcome: 'unsubscribed' | 'staleLink' | null
+  failure: CommunityFailure | null
+}
+
+export interface SettingsUi {
+  phase: SettingsPhase
+  failure: CommunityFailure | null
+  module: ModuleInfo | null
+  settings: MemberSettings | null
+  saving: Partial<Record<SettingKey, boolean>>
+  push: PushUi
+  digest: DigestUi
+  announcement: TextRef | null
+  announceId: number
+}
+
+export interface MemberSettingsController {
+  readonly state: SettingsUi
+  load(): Promise<void>
+  toggle(key: SettingKey, value: boolean): Promise<void>
+  /** Whether this browser's push block is shown (the module's feature; never for a visitor). */
+  pushShown(): boolean
+  enablePush(): Promise<void>
+  disablePush(): Promise<void>
+  unsubscribeDigest(): Promise<void>
+  dispose(): void
+}
+
+export interface MemberSettingsOptions {
+  client: CommunityClient
+  /** The host's worker script (`<site-base>/sw.js`). */
+  swPath: string
+  /** The digest's unsubscribe token this page's address carried (read and cleared by the element), or null. */
+  digestToken: string | null
+}
+
+export function createMemberSettings(o: MemberSettingsOptions): MemberSettingsController {
+  const { client, swPath } = o
+  // The token is the member's capability: kept in this closure only, never in the state a view renders.
+  const digestToken = o.digestToken
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  let disposed = false
+  /** The member viewing (me/get), or null for a reader who has not joined yet. */
+  let memberId: string | null = null
+  /** Unread module_push_reset notifications: marked read once push is on again. */
+  let resetNotices: string[] = []
+
+  const state = reactive<SettingsUi>({
+    phase: 'idle',
+    failure: null,
+    module: null,
+    settings: null,
+    saving: {},
+    push: { support: pushSupport(), status: 'checking', note: null, failure: null },
+    digest: { offered: digestToken !== null, sending: false, outcome: null, failure: null },
+    announcement: null,
+    announceId: 0,
+  }) as SettingsUi
+
+  const announce = (text: TextRef): void => {
+    state.announcement = text
+    state.announceId += 1
+  }
+  const failureRef = (f: CommunityFailure): TextRef => ({ key: `error.${f.code}` as TextRef['key'] })
+
+  const moduleOn = (): boolean => {
+    const s = state.module?.state
+    return s === undefined || (isKnownModuleState(s) && s !== 'dark')
+  }
+  const pushShown = (): boolean => state.phase === 'ready' && memberId !== null && state.module?.features.push === true
+
+  /** me/get: who is viewing and what the module switches on (`reader`: signed in, not a member yet). */
+  async function readMe(): Promise<'member' | 'reader' | 'signIn' | CommunityFailure> {
+    const me = await client.me.get(call)
+    if (!me.ok) return me.code === 'signIn' ? 'signIn' : me
+    state.module = me.value.module ?? null
+    if (me.value.needs.includes('sign_in')) return 'signIn'
+    memberId = me.value.member?.memberId ?? null
+    return memberId === null ? 'reader' : 'member'
+  }
+
+  /**
+   * Whether kb-api still holds this member's subscription of the browser's endpoint (`me/push/status`, D-M2-10): a
+   * read — nothing is subscribed again. Any answer but `subscribed: true` (false, a refusal, no answer) reads off.
+   */
+  async function pushHeld(sub: PushSubscription): Promise<boolean> {
+    const endpoint = subscriptionInput(sub)?.endpoint
+    if (!endpoint || memberId === null) return false
+    const r = await client.me.push.status({ endpoint }, call)
+    return r.ok && r.value.subscribed === true
+  }
+
+  /** The browser's own subscription, whose it is and the key it was made for, and a pending reset notice. */
+  async function checkPush(): Promise<void> {
+    if (!pushShown() || state.push.support !== 'supported') {
+      state.push.status = 'off'
+      return
+    }
+    const sub = await currentSubscription(await currentRegistration())
+    if (disposed) return
+    const notices = await client.me.notifications.list({ unreadOnly: true, codes: ['module_push_reset'] }, call)
+    if (disposed) return
+    resetNotices = notices.ok ? notices.value.items.filter((n) => n.code === 'module_push_reset' && n.readAt === null).map((n) => n.id) : []
+    const stored = storedPush()
+    // Only a subscription this member made here counts as theirs (a shared browser keeps another member's).
+    const mine = sub !== null && stored !== null && stored.memberId === memberId
+    let rotated = false
+    // D-M2-10: the stored keyId must be confirmed current before kb-api is asked; me/push/vapid unanswered → off, no
+    // sentence (as a failed status read), and nothing is asked or posted until the member presses the button.
+    let keyCurrent = false
+    if (mine) {
+      const vapid = await client.me.push.vapid(call)
+      if (disposed) return
+      rotated = vapid.ok && vapid.value.keyId !== stored.keyId
+      keyCurrent = vapid.ok && !rotated
+    }
+    const permission = notificationPermission()
+    let on = mine && keyCurrent && permission === 'granted'
+    if (on && sub) {
+      on = await pushHeld(sub)
+      if (disposed) return
+    }
+    state.push.status = on ? 'on' : 'off'
+    state.push.note = rotated || resetNotices.length > 0 ? 'reset' : permission === 'denied' ? 'denied' : null
+  }
+
+  async function load(): Promise<void> {
+    state.phase = 'loading'
+    state.failure = null
+    const who = await readMe()
+    if (disposed) return
+    if (who === 'signIn') {
+      state.phase = 'signIn'
+      return
+    }
+    if (who !== 'member' && who !== 'reader') {
+      state.phase = 'failed'
+      state.failure = who
+      return
+    }
+    if (!moduleOn()) {
+      // The module is dark: the settings answer MODULE_DARK (`unavailable`) — say so without asking.
+      state.phase = 'failed'
+      state.failure = { ok: false, code: 'unavailable' }
+      return
+    }
+    const r = await client.me.settings.get(call)
+    if (disposed) return
+    if (!r.ok) {
+      state.phase = r.code === 'signIn' ? 'signIn' : 'failed'
+      state.failure = r
+      return
+    }
+    state.settings = { ...r.value.settings }
+    state.phase = 'ready'
+    await checkPush()
+  }
+
+  async function toggle(key: SettingKey, value: boolean): Promise<void> {
+    const s = state.settings
+    if (!s || state.saving[key] || s[key] === value) return
+    state.saving[key] = true
+    const before = s[key]
+    state.settings = { ...s, [key]: value }
+    const r = await client.me.settings.update({ [key]: value }, call)
+    delete state.saving[key]
+    if (disposed) return
+    if (!r.ok) {
+      if (state.settings) state.settings = { ...state.settings, [key]: before }
+      return announce(failureRef(r))
+    }
+    state.settings = { ...r.value.settings }
+    announce({ key: 'settings.saved' })
+    // The master switch decides `module.features.push`: read it again, so the browser's block shows or goes.
+    if (key === 'pushEnabled') {
+      const who = await readMe()
+      if (disposed || (who !== 'member' && who !== 'reader')) return
+      await checkPush()
+    }
+  }
+
+  async function enablePush(): Promise<void> {
+    const p = state.push
+    if (!pushShown() || p.support !== 'supported' || p.status === 'busy' || memberId === null) return
+    const me = memberId
+    p.status = 'busy'
+    p.failure = null
+    p.note = null
+    const fail = (note: PushUi['note'], failure: CommunityFailure | null = null): void => {
+      p.status = 'off'
+      p.note = note
+      p.failure = failure
+    }
+    try {
+      if ((await requestNotificationPermission()) !== 'granted') return fail('denied')
+      if (disposed) return
+      const reg = await registerWorker(swPath)
+      if (disposed) return
+      const vapid = await client.me.push.vapid(call)
+      if (disposed) return
+      if (!vapid.ok) return fail(vapid.code === 'pushRefused' ? 'refused' : null, vapid)
+      const applicationServerKey = base64UrlBytes(vapid.value.publicKey)
+      if (!applicationServerKey) return fail(null, { ok: false, code: 'unavailable' })
+      // A subscription made for another key cannot be changed in place: end it first.
+      const old = await currentSubscription(reg)
+      if (old) await old.unsubscribe().catch(() => false)
+      const sub = await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: applicationServerKey as BufferSource })
+      if (disposed) return
+      const input = subscriptionInput(sub)
+      if (!input) {
+        await sub.unsubscribe().catch(() => false)
+        return fail('refused')
+      }
+      const r = await client.me.push.subscribe({ ...input, userAgentClass: userAgentClass() }, call)
+      if (disposed) return
+      if (!r.ok) {
+        // kb-api keeps nothing of a refused subscription: the browser's goes too.
+        await sub.unsubscribe().catch(() => false)
+        return fail(r.code === 'pushRefused' ? 'refused' : null, r)
+      }
+      storePush({ memberId: me, keyId: r.value.keyId })
+      p.status = 'on'
+      announce({ key: 'settings.saved' })
+      if (resetNotices.length > 0) {
+        const ids = resetNotices
+        resetNotices = []
+        void client.me.notifications.markRead({ ids }, call)
+      }
+    } catch {
+      // The browser refused (a permission it withdrew, no push service, the worker's script missing).
+      if (!disposed) fail(notificationPermission() === 'denied' ? 'denied' : 'refused')
+    }
+  }
+
+  async function disablePush(): Promise<void> {
+    const p = state.push
+    if (p.status === 'busy') return
+    p.status = 'busy'
+    p.failure = null
+    p.note = null
+    let endpoint: string | null = null
+    try {
+      const sub = await currentSubscription(await currentRegistration())
+      endpoint = sub?.endpoint ?? null
+      await sub?.unsubscribe()
+    } catch {
+      // The browser's subscription could not be ended: kb-api forgets it anyway.
+    }
+    if (disposed) return
+    if (endpoint) {
+      const r = await client.me.push.unsubscribe({ endpoint }, call)
+      if (disposed) return
+      if (!r.ok) p.failure = r
+    }
+    storePush(null)
+    p.status = 'off'
+    if (!p.failure) announce({ key: 'settings.saved' })
+  }
+
+  async function unsubscribeDigest(): Promise<void> {
+    const d = state.digest
+    if (!digestToken || d.sending || d.outcome === 'unsubscribed') return
+    d.sending = true
+    d.failure = null
+    const r = await client.me.settings.unsubscribeDigest({ token: digestToken }, call)
+    d.sending = false
+    if (disposed) return
+    if (r.ok) {
+      d.outcome = 'unsubscribed'
+      if (state.settings) state.settings = { ...state.settings, digestEmail: false }
+      announce({ key: 'settings.digest.unsubscribed' })
+      return
+    }
+    // DIGEST_UNSUBSCRIBE_INVALID reads `invalid`: a forged, cut or stale link.
+    if (r.code === 'invalid') {
+      d.outcome = 'staleLink'
+      return
+    }
+    d.failure = r
+  }
+
+  return {
+    state,
+    load,
+    toggle,
+    pushShown,
+    enablePush,
+    disablePush,
+    unsubscribeDigest,
+    dispose() {
+      disposed = true
+      abort.abort()
+    },
+  }
+}

package/src/core/text.ts

@@ -5,10 +5,13 @@
  * `target="_blank"`. test/text-only.spec.ts bans `v-html`, `innerHTML` and any HTML parser in src/.
  */
 import { sanitizeUrl } from '@blogmcp/sanitize/url'
+import { communityMentionSpans } from '@blogmcp/sdk/community'
 
 export type TextSegment =
   | { readonly kind: 'text'; readonly text: string }
   | { readonly kind: 'link'; readonly text: string; readonly href: string }
+  /** M2: an `@handle` with the link to the member's profile page on the host's own site (never a member's URL). */
+  | { readonly kind: 'mention'; 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'
@@ -63,6 +66,35 @@ export function linkify(text: string): TextSegment[] {
   return out
 }
 
+/**
+ * A member's text as text runs, web-address links and `@handle` mentions (m2-contracts.md §3.3: „the element renders
+ * `@handle` as text with a link to `/u/{handle}`"). The mentions are the SDK's (kb-api's token rule), found only in the
+ * text between addresses — an address's `/@x` stays part of its link; `profileHref` builds the host's profile page
+ * (profilePath) and a handle it gives no page for stays text. Joining every segment's `text` gives the body back.
+ */
+export function linkifyWithMentions(text: string, profileHref: ((handle: string) => string | null) | null): TextSegment[] {
+  const segments = linkify(text)
+  if (!profileHref) return segments
+  const out: TextSegment[] = []
+  for (const s of segments) {
+    if (s.kind !== 'text' || !s.text.includes('@')) {
+      out.push(s)
+      continue
+    }
+    for (const span of communityMentionSpans(s.text)) {
+      const href = span.kind === 'mention' ? profileHref(span.handle) : null
+      if (span.kind === 'mention' && href) out.push({ kind: 'mention', text: span.text, href })
+      else {
+        const last = out[out.length - 1]
+        // Text next to text stays one run (a handle without a page, between two runs).
+        if (last && last.kind === 'text') out[out.length - 1] = { kind: 'text', text: last.text + span.text }
+        else out.push({ kind: 'text', text: span.text })
+      }
+    }
+  }
+  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