@blogmcp/community 0.0.0-stage → 0.2.0

package/dist/core/attrs.d.ts

@@ -0,0 +1,99 @@
+/**
+ * What the elements read from their attributes: the host's page routes (`routes`, JSON), the notice form's
+ * target (`target`, JSON, or `article-id`), and the link the discussion gives a reader without a session
+ * to report a message on the host's notice page.
+ *
+ * Every path is the HOST's (m1-contracts.md §10.2: the elements take the host's routes as attributes) and
+ * must be a path on its own site — one leading `/`, never `//` or `/\`, no blank, control character or
+ * backslash; anything else is dropped and the managed blog's default (COMMUNITY_ROUTES) applies.
+ *
+ * The defaults are router-relative (the SDK's COMMUNITY_ROUTES: "the blog prepends its own base"). A site served
+ * under a path — a managed blog under `/blog`, whose host's own `/api/` goes straight to kb-api — names it in
+ * `site-base`, and the defaults (the pages and the api-base) are taken under it; what the host names itself
+ * (`routes`, `api-base`, the tenant's MyState.links) is a full site path already and is used as it is.
+ */
+import { type NoticeTarget } from '@blogmcp/sdk/community';
+/** The host's community pages, as the `routes` attribute names them (all optional). */
+export interface CommunityRoutes {
+    /** A statement of reasons; `{id}` is the decision's id (`/komunita/rozhodnuti/{id}`). */
+    statementPath?: string;
+    /** The „Moje komunita" panel. */
+    myCommunityPath?: string;
+    /** The rules page (rendered by the host without JavaScript). */
+    rulesPath?: string;
+    /** The notice form. */
+    reportPath?: string;
+    /** A notifier's status page (the receipt goes in its fragment). */
+    noticesPath?: string;
+    /**
+     * The site's consultation page (drhoubicka's „poradna"): the regulated preset's `report_to_manufacturer` note
+     * 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;
+}
+/** A path on the host's own site (the SDK's links.ts rule). */
+export declare function isSitePath(path: unknown): path is string;
+/** The `routes` attribute: the site paths it names; anything malformed is left out. */
+export declare function parseRoutes(value: unknown): CommunityRoutes;
+/**
+ * The `site-base` attribute: the path the site is served under, without a trailing `/` (`/blog`; '' for the root,
+ * also when absent) — or null when it is no plain path (a URL, a query, a dot segment): the element then renders
+ * nothing, as for an absolute api-base.
+ */
+export declare function siteBaseOf(value: unknown): string | null;
+/**
+ * The pages with the managed blog's defaults filled in under the site's base (statementPath and profilePath 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?: {
+    statementPath?: string | null;
+    myCommunityPath?: string | null;
+} | null, siteBase?: string): {
+    statementPath: string;
+    myCommunityPath: string;
+    rulesPath: string;
+    reportPath: string;
+    noticesPath: string;
+    consultationPath: string | null;
+    profilePath: string;
+    settingsPath: string;
+    notificationsPath: string;
+    welcomePath: string;
+    discussionsPath: string;
+    articlePath: string | null;
+};
+/** 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;
+export type NoticeTargetKind = 'message' | 'profile' | 'article';
+export declare function targetKind(target: NoticeTarget): NoticeTargetKind;
+/**
+ * The notice page's link for a message, for a reader without a session (who cannot use the member's
+ * report): `${reportPath}#c=<conversationId>&s=<seq>`. The ids are public; they travel in the fragment so
+ * the notice page stays one address (no crawlable variants — the storefront's rule for the sign-in link).
+ */
+export declare function reportLink(reportPath: string, target: {
+    conversationId: string;
+    seq: number;
+}): string | null;
+/** The target the discussion's report link carries (`#c=…&s=…`), or `#a=<articleId>`; null for anything else. */
+export declare function targetFromHash(hash: string): NoticeTarget | null;

package/dist/core/avatars.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The avatar presets a member picks from (kb-api stores the id, `^[a-z0-9_]{1,64}$`, and knows no list).
+ * Each is one emoji: a screen reader names it in the reader's own language, so the picker needs no words of
+ * ours. An id this list does not know (a newer element's) shows the name's initial instead.
+ */
+export interface AvatarPreset {
+    readonly id: string;
+    readonly emoji: string;
+}
+export declare const AVATAR_PRESETS: readonly AvatarPreset[];
+/** The preset's emoji, or null for none or an unknown id. */
+export declare function avatarEmoji(preset: string | null | undefined): string | null;
+/** The first letter of a name (the avatar of a member without a known preset). */
+export declare function initialOf(name: string | null | undefined): string;
+/** A stable hue for a member id, so the same member keeps the same initial's colour (decoration only). */
+export declare function hueOf(id: string | null | undefined): number;

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/client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The client an element talks through: the SDK's `createCommunityClient` over the HOST's relative base
+ * (`api-base`; default `/api/community` under the site's `site-base` — a headless site's BFF, the storefront's,
+ * or with `site-base="/blog"` a managed blog's own proxy). Never kb-api directly: its community namespaces answer
+ * no CORS (m1-contracts.md §7.1), and the client refuses an absolute base. On a managed blog the tenant host's
+ * `/api/` IS kb-api, so `/api/community` there would skip the blog's proxy and its session. An element with an
+ * unusable base warns once and renders nothing.
+ */
+import { type CommunityClient, type CommunityTransport } from '@blogmcp/sdk/community';
+/** The base the hosts serve the community under, below their site base (§12; the BFF's default basePath). */
+export declare const DEFAULT_API_BASE = "/api/community";
+/**
+ * One console line per problem and page, for the site's developer — never a value from the page. The
+ * message starts with `[blogmcp-community]` (test/text-only.spec.ts tells developer lines from reader text
+ * by it).
+ */
+export declare function warnOnce(key: string, message: `[blogmcp-community] ${string}`): void;
+/**
+ * The `site-base` attribute as a path prefix ('' at the site's root), or null — the developer told once — when it
+ * is no path on this site.
+ */
+export declare function siteBaseFor(value: string | null | undefined): string | null;
+/**
+ * The client for an element's `api-base` (and an injected transport), or null when the base is not a relative
+ * path. Without an `api-base`: `/api/community` under the site's base.
+ */
+export declare function communityClientFor(apiBase: string | null | undefined, transport?: CommunityTransport | null, siteBase?: string): CommunityClient | null;

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

@@ -0,0 +1,175 @@
+/**
+ * `<blogmcp-discussion>`'s brain, without any view (m1-contracts.md §10.4): the SDK's discussion store fed by
+ * `discussions/list` pages and the `discussions/head` poll, the composer (a new message, a reply, an edit)
+ * with its optimistic rows, the Russmedia confirmation and the cooldowns, reactions, blocks, reports, and the
+ * inline onboarding. The element renders `controller.state`; tests drive it directly over a fake transport.
+ *
+ * Every request goes through the SDK client (the host's relative base); nothing here builds a path.
+ */
+import { 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 { Lang, TextRef } from './i18n';
+import { type OnboardingModel } from './onboarding';
+import type { DiscussionRealtime } from './realtime';
+export type DiscussionPhase = 'loading' | 'ready' | 'failed' | 'hidden';
+/** One composer's text and what happened to it. */
+export interface Draft {
+    body: string;
+    sending: boolean;
+    failure: CommunityFailure | null;
+    /** CONFIRMATION_REQUIRED: the codes the author confirms before the same text goes again. */
+    confirm: {
+        codes: string[];
+        checked: string[];
+    } | null;
+    /** A cooldown: the epoch milliseconds until which this write waits. */
+    waitUntil: number | null;
+    /** A post's id, kept until kb-api took it: a retry of a write whose answer was lost cannot post twice. */
+    clientMsgId: string | null;
+}
+export type InlineKind = 'reply' | 'edit';
+/** The one reply or edit open under a message (opening another closes it). */
+export interface InlineDraft extends Draft {
+    kind: InlineKind;
+    /** The message edited, or the TOP-LEVEL message a reply goes under (two levels only). */
+    seq: number;
+    /** A reply to a reply names whom it answers. */
+    replyingTo: string | null;
+}
+export interface ReportDraft {
+    conversationId: string;
+    seq: number;
+    category: CaseCategory | '';
+    ruleId: string;
+    note: string;
+    rules: CommunityRule[] | null;
+    rulesFailed: boolean;
+    sending: boolean;
+    failure: CommunityFailure | null;
+    done: boolean;
+}
+/**
+ * Where the composer stands: `write`; `signIn` (no session that can write); `onboarding` (the inline
+ * onboarding waits); `ageRefused` (the age band declared in it was below the minimum: reading only, the
+ * onboarding is not offered again); `sanction` (a restriction, suspension or ban in effect); `notMoved` (the
+ * discussion takes no writes yet — one sentence); `restricted` (the member is read-only or deleting their
+ * profile); `braked` (M2: the community is paused — `me/get`'s `module.brake`, or a write refused BRAKED: reading
+ * goes on, every member write waits — one sentence); `pending` (being decided).
+ *
+ * A module that is `read_only` changes nothing here (m2-contracts.md §3.1: the discussions under articles keep
+ * taking writes; only live updates, push and the Pro surfaces stop) — the discussion polls instead of a socket.
+ */
+export type ComposerMode = 'write' | 'signIn' | 'onboarding' | 'ageRefused' | 'sanction' | 'notMoved' | 'restricted' | 'braked' | 'pending';
+export interface DiscussionUi {
+    phase: DiscussionPhase;
+    /** Why the first load failed (`failed`). */
+    failure: CommunityFailure | null;
+    thread: DiscussionState;
+    loadingMore: boolean;
+    refreshing: boolean;
+    /** A head poll saw messages the page does not show yet. */
+    newMessages: boolean;
+    me: MyState | null;
+    /** What a write or the member's state taught: no writes yet, none for this member, or a pause (BRAKED). */
+    block: 'notMoved' | 'restricted' | 'braked' | null;
+    composer: Draft;
+    inline: InlineDraft | null;
+    report: ReportDraft | null;
+    /** The last outcome to announce (aria-live), and a counter so the same text is announced again. */
+    announcement: TextRef | null;
+    announceId: number;
+    /** Now, ticking while a cooldown runs. */
+    clock: number;
+    /** Actions on their way, by key (`react:…`, `delete:<seq>`, `block:<memberId>`). */
+    busy: Record<string, boolean>;
+    /**
+     * The minimum age a declared band fell below (AGE_BELOW_MINIMUM). kb-api keeps nothing of a refused band
+     * (§7.4.2), so the element does: the onboarding is not offered again while it lives.
+     */
+    refusedAge: number | null;
+    /**
+     * M2 T9: the onboarding just finished with the art. 9 consent refused (`public_write`): the composer says once,
+     * in view, what the refusal leaves (writing in the public discussion). Not kept beyond this element.
+     */
+    art9RefusedNote: boolean;
+    /**
+     * M2 (§3.5): the live updates' session fell back to polling (live updates are off here, or the server cut the
+     * socket for good — 4501): the discussion says so once and keeps polling; it never opens the socket again itself.
+     */
+    realtimeOff: boolean;
+}
+export interface DiscussionControllerOptions {
+    client: CommunityClient;
+    articleId: string;
+    lang: Lang;
+    /** Head poll interval (default 20 s; 0 = no polling). */
+    pollMs?: number;
+    now?: () => number;
+    /** The viewer's message was posted (`held`: it waits for review). */
+    onPosted?(state: 'visible' | 'held'): void;
+    /** A refusal the element saw before (a discussion started again in another language keeps it). */
+    refusedAge?: number | null;
+    /** The onboarding's age band was refused: the element keeps it for its next discussions. */
+    onAgeRefused?(minAge: number): void;
+    /**
+     * M2 (§3.5, §3.10): the host's live-updates session factory (`createRealtimeSession` of
+     * `@blogmcp/sdk/community/realtime`). Absent: the head poll, as before.
+     */
+    realtime?: DiscussionRealtime | null;
+}
+export interface DiscussionController {
+    readonly state: DiscussionUi;
+    readonly store: DiscussionStore;
+    readonly onboarding: ShallowRef<OnboardingModel | null>;
+    /** The first load, then the poll. */
+    start(): Promise<void>;
+    refresh(): Promise<void>;
+    loadMore(): Promise<void>;
+    mode(): ComposerMode;
+    needs(): ViewerNeeds;
+    isOwn(m: Pick<DiscussionMessage, 'author'>): boolean;
+    canReply(m: DiscussionMessage): boolean;
+    canEdit(m: DiscussionMessage): boolean;
+    canDelete(m: DiscussionMessage): boolean;
+    canReact(): boolean;
+    /** A member's report (`messages/report`): any signed-in reader, on someone else's message. */
+    canReport(m: DiscussionMessage): boolean;
+    /** A reader without a session reports through the host's notice page instead (reportLink). */
+    canReportAsNotifier(m: DiscussionMessage): boolean;
+    canBlock(m: DiscussionMessage): boolean;
+    /** The poll may run (the element is on screen). */
+    setInView(inView: boolean): void;
+    submit(): Promise<void>;
+    /** Reply under `seq`'s thread (a reply to a reply goes under its top-level message, naming its author). */
+    openReply(seq: number, replyingTo?: string | null): void;
+    openEdit(seq: number): void;
+    closeInline(): void;
+    submitInline(): Promise<void>;
+    /** Tick or untick one code of a draft's confirmation. */
+    setConfirmed(draft: Draft, code: string, checked: boolean): void;
+    /** Send the draft again with every confirmed code (the Russmedia confirmation). */
+    sendConfirmed(draft: Draft): Promise<void>;
+    remove(seq: number): Promise<boolean>;
+    react(target: ReactionTarget, emoji: string): Promise<void>;
+    setBlocked(memberId: string, blocked: boolean): Promise<void>;
+    openReport(m: DiscussionMessage): void;
+    closeReport(): void;
+    submitReport(): Promise<void>;
+    /**
+     * The onboarding inline; `offerArt9` asks the art. 9 consent also of a member who refused it (`public_write`, M2 T9) —
+     * the give-consent link on their own message held until the consent.
+     */
+    beginOnboarding(options?: {
+        offerArt9?: boolean;
+    }): void;
+    cancelOnboarding(): void;
+    /** Seconds a draft still waits (0 when it may go). */
+    waitLeft(draft: Draft): number;
+    /**
+     * M2 T10: the distinct `@handle`s one message of the viewer may carry (me/get's `caps.mentionsPerMessage`), or null
+     * when nothing is known to limit it (no member yet, an older kb-api, a module whose mentions notify nobody).
+     */
+    mentionCap(): number | null;
+    dispose(): void;
+}
+export declare function createDiscussionController(o: DiscussionControllerOptions): DiscussionController;

package/dist/core/download.d.ts

@@ -0,0 +1,4 @@
+/** The member's export as a file the browser saves (§8.3: the download is the SDK's). Nothing leaves the page. */
+export declare function saveJson(data: unknown, fileName: string): void;
+/** `<name>-YYYY-MM-DD.json`, the name being the catalogue's (`panel.exportFileName`). */
+export declare function exportFileName(name: string, now?: Date): string;

package/dist/core/format.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Dates and a statement's territorial scope as the reader's language writes them (Intl does the words; the
+ * catalogue holds the sentence around them).
+ */
+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;
+/**
+ * A statement's territorial scope (DSA art. 17(3)(a)) as the reader reads it. kb-api stores `all` — the measure
+ * applies without a territorial limit, the catalogue's `statement.scopeAll` — or the regions it is limited to as
+ * ISO 3166-1 alpha-2 codes (`CZ,SK`), which Intl names and joins („Česko a Slovensko"; a runtime without Intl reads
+ * `CZ, SK`). Any other value — one a newer kb-api sends — is shown as it came, never dropped and never an
+ * exception; '' when there is none.
+ */
+export declare function formatTerritorialScope(lang: Lang, scope: string | null | undefined): string;

package/dist/core/i18n.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The elements' language and their texts (m1-contracts.md §10.4): every string a reader sees comes from
+ * the SDK's catalogue, `communityMessage` — one catalogue, one tone test. The elements add no words of
+ * their own; test/text-only.spec.ts scans src/ for any.
+ */
+import { type CommunityMessageKey } from '@blogmcp/sdk/community';
+export type Lang = 'cs' | 'en';
+/**
+ * The review layer's rule: the first candidate that is Czech or Slovak reads Czech, the first that is
+ * English reads English; anything else is passed over; English when none decides. The candidates are
+ * the `lang` attribute, then `<html lang>`.
+ */
+export declare function pickLang(...candidates: Array<string | null | undefined>): Lang;
+/** The page's own language attribute, when there is a page (the elements mount in a browser only). */
+export declare function documentLang(): string | null;
+export type TextParams = Record<string, string | number>;
+export type Translate = (key: CommunityMessageKey, params?: TextParams) => string;
+export declare function translator(lang: Lang): Translate;
+/**
+ * A key built from one of kb-api's open codes (`restriction.<code>`, `caseStatus.<status>`, …) when the
+ * catalogue has a text for it, else null: a code a newer kb-api sends is skipped, never shown raw.
+ */
+export declare function knownKey(key: string): CommunityMessageKey | null;
+/** A message key and its params: what a controller hands the view, which turns it into text. */
+export interface TextRef {
+    readonly key: CommunityMessageKey;
+    readonly params?: TextParams;
+}

package/dist/core/names.d.ts

@@ -0,0 +1,15 @@
+/** The display name as kb-api will fold it: NFKC, white space collapsed, trimmed. */
+export declare function normalizeName(name: string): string;
+export declare function isDisplayNameOk(name: string): boolean;
+/** A handle's length as COMMUNITY_HANDLE_RE takes it (3–30), for the hint and the field's maxlength. */
+export declare const HANDLE_MIN = 3;
+export declare const HANDLE_MAX = 30;
+/** A handle as typed: lower case, trimmed; '' when none was typed. */
+export declare function normalizeHandle(handle: string): string;
+export declare function isHandleOk(handle: string): boolean;
+/**
+ * The handle kb-api would make of a display name when the member gives none (its stem: fold → ASCII →
+ * words joined by `_`, at most 24 characters) — shown as a suggestion; null when the name gives too little.
+ * kb-api may still add a number on a clash, or leave out a reserved word.
+ */
+export declare function suggestedHandle(displayName: string): string | null;

package/dist/core/notice.d.ts

@@ -0,0 +1,50 @@
+import { type CaseCategory, type CommunityClient, type CommunityFailure, type CommunityRule, type NoticeReceipt, type NoticeTarget } from '@blogmcp/sdk/community';
+import type { Lang } from './i18n';
+/** `off`: no site key (development, a host without the widget); kb-api then decides alone. */
+export type CaptchaState = 'off' | 'loading' | 'ready' | 'unavailable';
+export interface NoticeFormUi {
+    target: NoticeTarget | null;
+    category: CaseCategory | '';
+    ruleId: string;
+    rules: CommunityRule[] | null;
+    description: string;
+    name: string;
+    email: string;
+    goodFaith: boolean;
+    captcha: CaptchaState;
+    /** The widget's one-shot token, or null. */
+    token: string | null;
+    /** Bumped after every failed send: the widget issues a new token. */
+    resetSignal: number;
+    sending: boolean;
+    failure: CommunityFailure | null;
+    receipt: NoticeReceipt | null;
+    /** The notifier's status page with the receipt in the fragment. */
+    statusLink: string | null;
+}
+export interface NoticeFormController {
+    readonly state: NoticeFormUi;
+    /** The name and e-mail fields apply (not for an endangered child). */
+    contactAllowed(): boolean;
+    canSubmit(): boolean;
+    descriptionLength(): number;
+    setCategory(category: CaseCategory | ''): void;
+    setToken(token: string | null): void;
+    setCaptcha(state: CaptchaState): void;
+    submit(): Promise<void>;
+    dispose(): void;
+}
+export interface NoticeFormOptions {
+    client: Pick<CommunityClient, 'notices' | 'legal'>;
+    lang: Lang;
+    target: NoticeTarget | null;
+    /** A Turnstile site key was given: a token is needed before the form can be sent. */
+    captcha: boolean;
+    /** The host's status page (the receipt goes in its fragment). */
+    noticesPath: string;
+    /** The form was sent (the receipt is the page's: it is not passed on). */
+    onSubmitted?(answer: {
+        contactKept: boolean;
+    }): void;
+}
+export declare function createNoticeForm(o: NoticeFormOptions): NoticeFormController;

package/dist/core/onboarding.d.ts

@@ -0,0 +1,92 @@
+import { type AgeBand, type Art9ConsentLayout, type Art9Refusal, type CommunityClient, type CommunityFailure, type CommunityRule, type CurrentLegalText, type MyState } from '@blogmcp/sdk/community';
+import type { Lang, TextRef } from './i18n';
+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;
+}
+/** kb-api's issue code for a refusal the tenant does not take (`art9Refusal = read_only`, §3.8). */
+export declare const ART9_REFUSAL_READ_ONLY = "art9_refusal_read_only";
+/** The sentence a refusal of the onboarding shows: a refused refusal says the consent is needed to write. */
+export declare function onboardingFailureText(failure: Pick<CommunityFailure, 'code' | 'until' | 'fields' | 'issueCodes'>, lang: Lang): TextRef;
+export declare function createOnboarding(o: OnboardingOptions): OnboardingModel;

package/dist/core/outcomes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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, CommunityUiCode } from '@blogmcp/sdk/community';
+import type { Lang, TextRef } from './i18n';
+/** The sentence a refusal shows. Total over COMMUNITY_UI_CODES (test/outcomes.spec.ts). */
+export declare function failureText(failure: Pick<CommunityFailure, 'code' | 'until'>, lang: Lang): TextRef;
+/** Seconds a refusal asks to wait before the same write may go (the burst, a quota, the limiter). */
+export declare const DEFAULT_WAIT_S: Partial<Record<CommunityUiCode, number>>;
+/** The epoch milliseconds until which a write waits after `failure`, or null when it may go again at once. */
+export declare function waitUntilOf(failure: Pick<CommunityFailure, 'code' | 'retryAfterS'>, now: number): number | null;
+/** A countdown shows only for a short wait (a quota until midnight reads `error.quota` alone). */
+export declare 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';
+export declare function failureEffect(code: CommunityUiCode): FailureEffect;