@blogmcp/community 0.1.0 → 0.3.0

package/dist/core/attrs.d.ts

@@ -30,6 +30,36 @@ export interface CommunityRoutes {
      * becomes a link to it (m1-contracts.md §7.6). No default — without it the note stays text.
      */
     consultationPath?: string;
+    /**
+     * M2 (m2-contracts.md §3.10): a member's public profile; `{handle}` is the handle (`/komunita/u/{handle}`) — a
+     * template, as statementPath is. A mention in a message links to it.
+     */
+    profilePath?: string;
+    /** M2: the member's notification settings (where the digest's unsubscribe link lands with `#u=`). */
+    settingsPath?: string;
+    /** M2: the notification centre (the badge links to it). */
+    notificationsPath?: string;
+    /** M2: the welcome page after joining. */
+    welcomePath?: string;
+    /** M2: the discussions overview. */
+    discussionsPath?: string;
+    /**
+     * M2 T10: an article's page; `{slug}` is the article's slug (`/blog/articles/{slug}`, the storefront `/blog/{slug}`)
+     * — a template, as profilePath is. The notification centre links a reply's or a mention's message on it (the
+     * message's anchor in the fragment). No default: without it those rows stay unlinked.
+     */
+    articlePath?: string;
+    /** M3 (m3-contracts.md §5.1, D-M3-12): the forum — its categories, their latest topics, the search box. */
+    forumPath?: string;
+    /** M3: a category's page; `{slug}` is the category's slug (`/komunita/c/{slug}`) — a template, as profilePath is. */
+    categoryPath?: string;
+    /**
+     * M3: a topic's page; `{id}` is its conversation id (`/komunita/t/{id}`) — a template; a message's anchor goes in the
+     * fragment (`#bcm-msg-<seq>`, topicMessageLink).
+     */
+    topicPath?: string;
+    /** M3: the forum's search (the forum's search box goes there with the query in the fragment, `#q=…`). */
+    searchPath?: string;
 }
 /** A path on the host's own site (the SDK's links.ts rule). */
 export declare function isSitePath(path: unknown): path is string;
@@ -42,7 +72,8 @@ export declare function parseRoutes(value: unknown): CommunityRoutes;
  */
 export declare function siteBaseOf(value: unknown): string | null;
 /**
- * The pages with the managed blog's defaults filled in under the site's base (statementPath stays a template).
+ * The pages with the managed blog's defaults filled in under the site's base (statementPath, profilePath, M3's
+ * categoryPath and topicPath stay templates; articlePath, a template too, has no default).
  * A page the host or the tenant names is its own full path.
  */
 export declare function routesWithDefaults(routes: CommunityRoutes, tenant?: {
@@ -55,6 +86,16 @@ export declare function routesWithDefaults(routes: CommunityRoutes, tenant?: {
     reportPath: string;
     noticesPath: string;
     consultationPath: string | null;
+    profilePath: string;
+    settingsPath: string;
+    notificationsPath: string;
+    welcomePath: string;
+    discussionsPath: string;
+    articlePath: string | null;
+    forumPath: string;
+    categoryPath: string;
+    topicPath: string;
+    searchPath: string;
 };
 /** A notice target of one of kb-api's four shapes, or null (the form then has nothing to report). */
 export declare function parseTarget(value: unknown): NoticeTarget | null;

package/dist/core/badge.d.ts

@@ -0,0 +1,30 @@
+import { type CommunityClient } from '@blogmcp/sdk/community';
+/** The badge's poll (the contract's 60 s). */
+export declare const BADGE_INTERVAL_MS = 60000;
+/** A count above it reads `99+`. */
+export declare const BADGE_MAX = 99;
+export interface BadgeUi {
+    /** `hidden`: nothing to show (a visitor, no member, a dark module, or not decided yet). */
+    phase: 'pending' | 'hidden' | 'shown';
+    count: number;
+}
+export interface BadgeController {
+    readonly state: BadgeUi;
+    start(): Promise<void>;
+    /** Read the count now (coalesced with one on its way). */
+    refresh(): Promise<void>;
+    dispose(): void;
+}
+export interface BadgeOptions {
+    client: CommunityClient;
+    /**
+     * Default 60 s, and never more often (a smaller value above 0 reads as 60 s: the contract's rate per open tab);
+     * 0 or less = no poll (the count is read once and on visibility).
+     */
+    intervalMs?: number;
+    /** Whether the page is visible now (default: document.visibilityState). */
+    visible?: () => boolean;
+}
+/** The count as the badge shows it. */
+export declare const badgeText: (count: number) => string;
+export declare function createBadge(o: BadgeOptions): BadgeController;

package/dist/core/centre.d.ts

@@ -0,0 +1,28 @@
+import { type CommunityClient, type CommunityFailure, type NotificationItem } from '@blogmcp/sdk/community';
+import type { TextRef } from './i18n';
+export type CentrePhase = 'idle' | 'loading' | 'ready' | 'failed' | 'signIn';
+export interface CentreUi {
+    phase: CentrePhase;
+    failure: CommunityFailure | null;
+    /** Known codes only (a code a newer kb-api sends is skipped, never shown raw). */
+    items: NotificationItem[];
+    nextCursor: string | null;
+    unreadOnly: boolean;
+    loadingMore: boolean;
+    busy: Record<string, boolean>;
+    announcement: TextRef | null;
+    announceId: number;
+}
+export interface NotificationCentreController {
+    readonly state: CentreUi;
+    load(): Promise<void>;
+    loadMore(): Promise<void>;
+    setUnreadOnly(on: boolean): Promise<void>;
+    markRead(id: string): Promise<void>;
+    markAllRead(): Promise<void>;
+    unread(): number;
+    dispose(): void;
+}
+export declare function createNotificationCentre(o: {
+    client: CommunityClient;
+}): NotificationCentreController;

package/dist/core/digest-token.d.ts

@@ -0,0 +1,2 @@
+/** The token this element's page carries, or null (none, or a cut link). */
+export declare function digestTokenForElement(owner: object | null): string | null;

package/dist/core/discussion.d.ts

@@ -4,13 +4,41 @@
  * with its optimistic rows, the Russmedia confirmation and the cooldowns, reactions, blocks, reports, and the
  * inline onboarding. The element renders `controller.state`; tests drive it directly over a fake transport.
  *
+ * M3 (m3-contracts.md §5.3): the same brain under `<blogmcp-topic>` — a forum topic IS a discussion (its opening post is
+ * seq 1, its replies two levels deep), so createTopicThreadController runs every rule above over the SDK's topic store,
+ * `forum/topics/get` and `forum/topics/head`, posts by the topic's conversation id, and adds what a topic has of its
+ * own: a viewer the forum is not open to (`membersOnly`, with its `needs`) and a topic the viewer may not see
+ * (`notFound`) as states of the element, a write's `notFound` read again (settleTopicFailure: the forum's gate answers
+ * every refusal of a topic's id that way, A11), a closed topic, the forum's own brake beside the module's, the title of
+ * the opening post in its edit, and the art. 9 consent every forum write needs (U14). The article's own reactions are
+ * an article's only.
+ *
  * Every request goes through the SDK client (the host's relative base); nothing here builds a path.
  */
 import { type ShallowRef } from 'vue';
-import { type CaseCategory, type CommunityClient, type CommunityFailure, type CommunityRule, type DiscussionMessage, type DiscussionState, type DiscussionStore, type MyState, type ReactionTarget, type ViewerNeeds } from '@blogmcp/sdk/community';
+import { type CaseCategory, type CommunityClient, type CommunityFailure, type CommunityRule, type DiscussionMessage, type DiscussionState, type DiscussionStore, type DiscussionViewer, type MyState, type ReactionTarget, type TopicStore, type TopicStoreState, type ViewerNeeds } from '@blogmcp/sdk/community';
 import type { Lang, TextRef } from './i18n';
 import { type OnboardingModel } from './onboarding';
-export type DiscussionPhase = 'loading' | 'ready' | 'failed' | 'hidden';
+import type { DiscussionRealtime, TopicRealtime } from './realtime';
+/**
+ * `membersOnly` (M3, a topic): the forum is not open to this viewer — `state.failure.needs` says what a member session
+ * still lacks (none: a visitor, sign in); `notFound` (M3, a topic): the topic is not there for this viewer.
+ */
+export type DiscussionPhase = 'loading' | 'ready' | 'failed' | 'hidden' | 'membersOnly' | 'notFound';
+/** What a discussion and a topic have in common, as the controller and the views read them (the SDK's two states). */
+export interface ThreadState {
+    readonly conversationId: string | null;
+    readonly count: number;
+    readonly lastSeq: number;
+    readonly lastChangeAt: string | null;
+    readonly messages: readonly DiscussionMessage[];
+    readonly nextCursor: number | null;
+    readonly reactionSet: readonly string[];
+    readonly preset: string | null;
+    readonly viewer: DiscussionViewer;
+    readonly loaded: boolean;
+    readonly stale: boolean;
+}
 /** One composer's text and what happened to it. */
 export interface Draft {
     body: string;
@@ -34,6 +62,11 @@ export interface InlineDraft extends Draft {
     seq: number;
     /** A reply to a reply names whom it answers. */
     replyingTo: string | null;
+    /**
+     * M3: the topic's title, on its author's edit of the opening post (seq 1) — sent with the body when it changed (one
+     * edit of the opening post, §2.5); null everywhere else.
+     */
+    title: string | null;
 }
 export interface ReportDraft {
     conversationId: string;
@@ -52,21 +85,34 @@ export interface ReportDraft {
  * 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); `pending` (being decided).
+ * 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' | 'pending';
-export interface DiscussionUi {
+export type ComposerMode = 'write' | 'signIn' | 'onboarding' | 'ageRefused' | 'sanction' | 'notMoved' | 'restricted' | 'braked' | 'pending'
+/** M3, a topic: closed (`locked`, `archived`, or a state this SDK does not know) — the composer gives way to a sentence. */
+ | 'locked'
+/** M3, a topic: the module is `read_only` — the forum is one of its features and takes no writes meanwhile. */
+ | 'readOnly'
+/** M3, a topic: the viewer reads only (the team at the keyboard: it writes through the KB admin) — nothing is shown. */
+ | 'none';
+export interface ThreadUi<S extends ThreadState> {
     phase: DiscussionPhase;
-    /** Why the first load failed (`failed`). */
+    /** Why the first load failed (`failed`), or why the topic is not shown (`membersOnly`, `notFound`). */
     failure: CommunityFailure | null;
-    thread: DiscussionState;
+    thread: S;
     loadingMore: boolean;
     refreshing: boolean;
     /** A head poll saw messages the page does not show yet. */
     newMessages: boolean;
     me: MyState | null;
-    /** What a write or the member's state taught: no writes yet, or none for this member. */
-    block: 'notMoved' | 'restricted' | null;
+    /**
+     * What a write or the member's state taught: no writes yet, none for this member, or a pause (BRAKED); M3, a topic:
+     * the module is `read_only` (the forum is a Pro surface).
+     */
+    block: 'notMoved' | 'restricted' | 'braked' | 'readOnly' | null;
     composer: Draft;
     inline: InlineDraft | null;
     report: ReportDraft | null;
@@ -82,10 +128,22 @@ export interface DiscussionUi {
      * (§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 {
+/** `<blogmcp-discussion>`'s state: an article's discussion. */
+export type DiscussionUi = ThreadUi<DiscussionState>;
+/** What both controllers take besides what their thread is (an article, a topic). */
+interface ThreadControllerOptions {
     client: CommunityClient;
-    articleId: string;
     lang: Lang;
     /** Head poll interval (default 20 s; 0 = no polling). */
     pollMs?: number;
@@ -97,9 +155,23 @@ export interface DiscussionControllerOptions {
     /** The onboarding's age band was refused: the element keeps it for its next discussions. */
     onAgeRefused?(minAge: number): void;
 }
-export interface DiscussionController {
-    readonly state: DiscussionUi;
-    readonly store: DiscussionStore;
+export interface DiscussionControllerOptions extends ThreadControllerOptions {
+    articleId: string;
+    /**
+     * M2 (§3.5, §3.10): the host's live-updates session factory (`createRealtimeSession` of
+     * `@blogmcp/sdk/community/realtime`). Absent: the head poll, as before.
+     */
+    realtime?: DiscussionRealtime | null;
+}
+/** M3: `<blogmcp-topic>`'s thread — a forum topic by its conversation id. */
+export interface TopicThreadControllerOptions extends ThreadControllerOptions {
+    conversationId: string;
+    /** The host's live-updates session factory over the topic's store (`createRealtimeSession`). Absent: the head poll. */
+    realtime?: TopicRealtime | null;
+}
+/** What a thread's controller does — the article's discussion's and a topic's alike; the views read it. */
+export interface ThreadController<S extends ThreadState = ThreadState> {
+    readonly state: ThreadUi<S>;
     readonly onboarding: ShallowRef<OnboardingModel | null>;
     /** The first load, then the poll. */
     start(): Promise<void>;
@@ -135,10 +207,43 @@ export interface DiscussionController {
     openReport(m: DiscussionMessage): void;
     closeReport(): void;
     submitReport(): Promise<void>;
-    beginOnboarding(): 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. M3, a topic: the art. 9 step is asked before a
+     * write whatever the tenant asks elsewhere (`forceArt9`, implied), but not to read the forum (`toRead`).
+     */
+    beginOnboarding(options?: OnboardingStart): 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;
+    /** M3: the edit of this message carries the topic's title (its author's opening post of a topic). */
+    editsTitle(m: Pick<DiscussionMessage, 'seq' | 'author'>): boolean;
     dispose(): void;
 }
+/** `<blogmcp-discussion>`'s controller: an article's discussion over the SDK's discussion store. */
+export interface DiscussionController extends ThreadController<DiscussionState> {
+    readonly store: DiscussionStore;
+}
+/** M3: `<blogmcp-topic>`'s thread over the SDK's topic store (its header is `state.thread.topic`). */
+export interface TopicThreadController extends ThreadController<TopicStoreState> {
+    readonly store: TopicStore;
+}
+/** How the inline onboarding starts (beginOnboarding). */
+export interface OnboardingStart {
+    /** The give-consent flow (M2 T9): the art. 9 step for a member who refused it, no refusal offered. */
+    offerArt9?: boolean;
+    /** M3: the art. 9 step whatever the tenant asks elsewhere — a forum write's refusal named it (U14). */
+    forceArt9?: boolean;
+    /** M3, a topic: the onboarding the forum asks only to be read (the members-only state) — no art. 9 step forced. */
+    toRead?: boolean;
+}
+/** `<blogmcp-discussion>`'s controller over one article's discussion. */
 export declare function createDiscussionController(o: DiscussionControllerOptions): DiscussionController;
+/** M3: `<blogmcp-topic>`'s thread over one forum topic (m3-contracts.md §3.1–§3.3, §5.3). */
+export declare function createTopicThreadController(o: TopicThreadControllerOptions): TopicThreadController;
+export {};

package/dist/core/follow.d.ts

@@ -0,0 +1,26 @@
+import { type CommunityClient, type CommunityFailure, type FollowTarget } from '@blogmcp/sdk/community';
+import type { Lang, TextRef } from './i18n';
+export type FollowPhase = 'idle' | 'loading' | 'ready' | 'signIn' | 'unavailable' | 'failed';
+export interface FollowUi {
+    phase: FollowPhase;
+    following: boolean;
+    busy: boolean;
+    /** The last refusal of a click (the state stays as it was), or null. */
+    failure: CommunityFailure | null;
+    announcement: TextRef | null;
+    announceId: number;
+}
+export interface FollowController {
+    readonly state: FollowUi;
+    /** The state from what the page knows (`known`), else the member's follows. */
+    load(known?: boolean | null): Promise<void>;
+    /** A newer `following` the page learnt (a topic re-read): taken unless a click is on its way. */
+    sync(following: boolean): void;
+    toggle(): Promise<void>;
+    dispose(): void;
+}
+export declare function createFollow(o: {
+    client: CommunityClient;
+    target: FollowTarget;
+    lang: Lang;
+}): FollowController;

package/dist/core/format.d.ts

@@ -5,6 +5,13 @@
 import { type Lang } from './i18n';
 /** An ISO timestamp as a date (and time); '' for anything that is no date. */
 export declare function formatDate(lang: Lang, iso: string | null | undefined, withTime?: boolean): string;
+/**
+ * A month as `profile/get`'s `memberSince` gives it (`YYYY-MM`, UTC) in the reader's language, in the form a date
+ * takes inside a sentence („Členem od října 2026", "Member since October 2026"): Intl formats the first of the month
+ * and the day is left out — a month on its own would be the nominative („říjen"). The value as it came when Intl has
+ * no words, '' for anything that is no month.
+ */
+export declare function formatMonth(lang: Lang, ym: string | null | undefined): string;
 /** Whether an ISO timestamp lies in the past (an appeal window, a sanction's end). */
 export declare function isPast(iso: string | null | undefined, now?: number): boolean;
 /**

package/dist/core/forum-category.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `<blogmcp-forum-category slug>`'s brain (m3-contracts.md §3.2, §3.3, §5.3): one category — its row of
+ * `forum/categories/list` (its description, who opens topics there, its mode, whether the member follows it) and its
+ * topics (`forum/topics/list` by the slug, the activity or the newest order, the forum's keyset cursor) — and the
+ * new-topic composer where the category takes topics from members (`forum/topics/create`: the title and the opening
+ * post as one text; the Russmedia confirmation, the cooldowns, the onboarding with the art. 9 consent a forum write
+ * needs, a pre-moderated topic waiting for review). In „Články" (kind `article_discussions`) the rows are the article
+ * discussions, and nothing is created there.
+ */
+import { type ShallowRef } from 'vue';
+import { type CommunityClient, type CommunityFailure, type ForumCategory, type ForumSort, type KnownTopicItem, type MyState } from '@blogmcp/sdk/community';
+import type { Draft } from './discussion';
+import type { Lang, TextRef } from './i18n';
+import { type OnboardingModel } from './onboarding';
+export type CategoryPhase = 'loading' | 'ready' | 'failed' | 'hidden' | 'membersOnly' | 'notFound';
+/** The new topic's draft: the composer's, with its title. */
+export interface TopicDraft extends Draft {
+    title: string;
+}
+export interface CategoryUi {
+    phase: CategoryPhase;
+    failure: CommunityFailure | null;
+    me: MyState | null;
+    /** The category's row of the list (null when the list did not name it: the page header stays). */
+    category: ForumCategory | null;
+    /** The page's own header of the category (its id, slug, name, kind). */
+    header: {
+        id: string;
+        slug: string;
+        name: string;
+        kind: string;
+    } | null;
+    items: KnownTopicItem[];
+    nextCursor: string | null;
+    sort: ForumSort;
+    loadingMore: boolean;
+    /** The list is read again (another order). */
+    sorting: boolean;
+    composer: TopicDraft;
+    /** The topic the member just opened (its link), and whether it waits for review. */
+    created: {
+        conversationId: string;
+        held: boolean;
+    } | null;
+    /** kb-api said the category takes no topic from the member (TOPIC_CREATION_CLOSED). */
+    creationClosed: boolean;
+    /**
+     * A write was refused BRAKED — by the forum's own brake (`surface: 'forum'`) or the module's (none named): the composer
+     * gives way to the pause until the category is read again.
+     */
+    brakedBy: 'forum' | 'module' | null;
+    clock: number;
+    announcement: TextRef | null;
+    announceId: number;
+}
+export interface CategoryController {
+    readonly state: CategoryUi;
+    readonly onboarding: ShallowRef<OnboardingModel | null>;
+    load(): Promise<void>;
+    loadMore(): Promise<void>;
+    setSort(sort: ForumSort): Promise<void>;
+    /** The member may open a topic here now (the composer shows). */
+    canCreate(): boolean;
+    /** Why the composer does not show where it would: the team's category, a pause, read_only — or null. */
+    notCreating(): 'team' | 'paused' | 'readOnly' | null;
+    create(): Promise<void>;
+    setConfirmed(code: string, checked: boolean): void;
+    sendConfirmed(): Promise<void>;
+    beginOnboarding(options?: {
+        forceArt9?: boolean;
+    }): void;
+    cancelOnboarding(): void;
+    waitLeft(): number;
+    dispose(): void;
+}
+export declare function createCategory(o: {
+    client: CommunityClient;
+    slug: string;
+    lang: Lang;
+    now?: () => number;
+    onCreated?(topic: {
+        conversationId: string;
+        held: boolean;
+    }): void;
+}): CategoryController;

package/dist/core/forum-search.d.ts

@@ -0,0 +1,35 @@
+import { type CommunityClient, type CommunityFailure, type ForumCategory, type ForumSearchResult, type KnownForumSpace } from '@blogmcp/sdk/community';
+export type SearchPhase = 'idle' | 'searching' | 'ready' | 'failed' | 'hidden' | 'membersOnly';
+export interface SearchUi {
+    phase: SearchPhase;
+    failure: CommunityFailure | null;
+    query: string;
+    /** '' every space. */
+    space: KnownForumSpace | '';
+    /** '' every category. */
+    categoryId: string;
+    /** The categories to narrow by (read once). */
+    categories: ForumCategory[];
+    /** The query is too short or too long to ask (said, nothing sent). */
+    invalid: 'short' | 'long' | null;
+    results: ForumSearchResult[];
+    page: number;
+    hasMore: boolean;
+    loadingMore: boolean;
+}
+export interface SearchController {
+    readonly state: SearchUi;
+    /** The categories for the filter (and the forum's own refusals: a visitor learns the forum is for members). */
+    load(): Promise<void>;
+    search(): Promise<void>;
+    more(): Promise<void>;
+    dispose(): void;
+}
+/** The query a page's fragment carries (`#q=<encoded>`), or null. */
+export declare function queryFromHash(hash: string | null | undefined): string | null;
+/** The search page's link with the query in its fragment (the forum's search box), or null. */
+export declare function searchLink(searchPath: string, raw: string): string | null;
+export declare function createSearch(o: {
+    client: CommunityClient;
+    query?: string | null;
+}): SearchController;

package/dist/core/forum-state.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What every forum element reads out of `me/get` beside its own operation (m3-contracts.md §3.5, §4.8, §4.9, §5.3):
+ * the team's away mode (one sentence, `state.away`), the pause of the forum's writes — the module's brake (both
+ * surfaces: `state.braked`) or the forum's own (`state.forumBraked`; the article discussions go on) —, the module's
+ * `read_only` (the forum is one of its features), and what a `membersOnly` refusal asks of the viewer.
+ */
+import { type CommunityFailure, type CommunityMessageKey, type MyState } from '@blogmcp/sdk/community';
+export interface ForumNotices {
+    /** The team is away: new topics wait for review (`state.away`). */
+    away: boolean;
+    /** The forum's writes are paused — the module's brake, or the forum's own — or not. */
+    paused: 'module' | 'forum' | null;
+    /** The module is `read_only`: the forum takes no writes meanwhile (`error.readOnly`). */
+    readOnly: boolean;
+}
+/** The notices of `me/get`'s module block, at `now`. */
+export declare function forumNoticesOf(me: MyState | null | undefined, now?: number): ForumNotices;
+/** The sentence of a pause of the forum's writes. */
+export declare const pausedKey: (paused: ForumNotices["paused"]) => CommunityMessageKey | null;
+/**
+ * What a `membersOnly` refusal asks of the viewer (§3.1 step 3): to join — a member session that has not finished its
+ * onboarding (`needs` `onboarding` or `reconsent_rules`) — or to sign in (a visitor, or a session the tenant does not
+ * admit as a member: `sign_in`, or no needs at all).
+ */
+export declare function membersOnlyAsk(failure: Pick<CommunityFailure, 'needs'> | null | undefined): 'join' | 'signIn';
+/**
+ * Whether the viewer is a member who may take part (an onboarded member's session): me/get names a member and no
+ * need to sign in. The team at the keyboard reads the forum but writes through the KB admin.
+ */
+export declare const isForumMember: (me: MyState | null | undefined) => boolean;

package/dist/core/forum-words.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The forum's words for the discussion's components (m3-contracts.md §5.3): a topic's thread reuses the discussion's
+ * view — the same messages, composer, dialogs and refusals — and reads it with these keys in place of the
+ * discussion's, so a forum reads „příspěvek" (a post) where an article's discussion reads „komentář" (a comment). Every
+ * key is the SDK catalogue's in both languages; a plural maps by its name (test/forum-elements.spec.ts checks both).
+ */
+import type { CommunityMessageKey } from '@blogmcp/sdk/community';
+export declare const FORUM_WORDS: Readonly<Partial<Record<CommunityMessageKey, CommunityMessageKey>>>;

package/dist/core/forum.d.ts

@@ -0,0 +1,21 @@
+import { type CommunityClient, type CommunityFailure, type ForumCategory, type KnownTopicItem, type MyState } from '@blogmcp/sdk/community';
+export type ForumPhase = 'loading' | 'ready' | 'failed' | 'hidden' | 'membersOnly';
+/** The categories whose latest topics the index shows, and how many of each (one request a category). */
+export declare const FORUM_LATEST_CATEGORIES = 10;
+export declare const FORUM_LATEST_PER_CATEGORY = 3;
+export interface ForumUi {
+    phase: ForumPhase;
+    failure: CommunityFailure | null;
+    me: MyState | null;
+    categories: ForumCategory[];
+    /** The latest rows of a category, by its id (a category whose list failed has none). */
+    latest: Record<string, KnownTopicItem[]>;
+}
+export interface ForumController {
+    readonly state: ForumUi;
+    load(): Promise<void>;
+    dispose(): void;
+}
+export declare function createForum(o: {
+    client: CommunityClient;
+}): ForumController;

package/dist/core/moderation.d.ts

@@ -0,0 +1,80 @@
+import { type CaseCategory, type CommunityClient, type CommunityFailure, type CommunityRule, type ForumCategory, type ModerationCase, type ModerationItem, type ModerationRestriction, type MyState } from '@blogmcp/sdk/community';
+import type { Lang, TextRef } from './i18n';
+export type ModerationPhase = 'loading' | 'ready' | 'none' | 'failed' | 'hidden' | 'membersOnly';
+/** A case opened from the queue: its package and the decision being made. */
+export interface OpenCase {
+    item: ModerationItem;
+    kase: ModerationCase | null;
+    loading: boolean;
+    restriction: ModerationRestriction | '';
+    facts: string;
+    /** The rule the restriction rests on ('' the case's own). */
+    ground: string;
+    /** kb-api asked for the rule (`invalid` on `contractualGround`): the rule must be chosen. */
+    needsRule: boolean;
+    /** The statement of the previewed decision, for the same choice. */
+    preview: string | null;
+    previewing: boolean;
+    deciding: boolean;
+    failure: CommunityFailure | null;
+    decided: boolean;
+    escalation: {
+        category: CaseCategory | '';
+        sending: boolean;
+        failure: CommunityFailure | null;
+        done: boolean;
+    } | null;
+}
+/** A pre-moderated message being reviewed. */
+export interface PremodReview {
+    item: ModerationItem;
+    outcome: 'approve' | 'reject' | '';
+    ruleId: string;
+    facts: string;
+    sending: boolean;
+    failure: CommunityFailure | null;
+    statement: string | null;
+    done: 'approved' | 'rejected' | null;
+    /** M3 FX (R3): the author edited the text while it was being reviewed — `item` holds the new one; decide again. */
+    changed: boolean;
+}
+export interface ModerationUi {
+    phase: ModerationPhase;
+    failure: CommunityFailure | null;
+    me: MyState | null;
+    /** '' every category of the moderator's. */
+    categoryId: string;
+    /** The moderator's categories (their names), in the forum's order. */
+    categories: ForumCategory[];
+    items: ModerationItem[];
+    nextCursor: string | null;
+    loadingMore: boolean;
+    rules: CommunityRule[] | null;
+    open: OpenCase | null;
+    review: PremodReview | null;
+    announcement: TextRef | null;
+    announceId: number;
+}
+export interface ModerationController {
+    readonly state: ModerationUi;
+    load(): Promise<void>;
+    loadMore(): Promise<void>;
+    setCategory(categoryId: string): Promise<void>;
+    openCase(item: ModerationItem): Promise<void>;
+    closeCase(): void;
+    /** Whether the case's decision may be previewed now (a restriction, facts, a rule where one is needed). */
+    canPreview(): boolean;
+    preview(): Promise<void>;
+    decide(): Promise<void>;
+    startEscalation(): void;
+    escalate(): Promise<void>;
+    openReview(item: ModerationItem, outcome: 'approve' | 'reject'): void;
+    closeReview(): void;
+    review(): Promise<void>;
+    dispose(): void;
+}
+export declare function createModeration(o: {
+    client: CommunityClient;
+    lang: Lang;
+    categoryId?: string | null;
+}): ModerationController;