@blogmcp/community 0.0.0-stage → 0.1.0

package/dist/core/attrs.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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;
+}
+/** 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 stays a template).
+ * 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;
+};
+/** 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/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/discussion.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `<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';
+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); `pending` (being decided).
+ */
+export type ComposerMode = 'write' | 'signIn' | 'onboarding' | 'ageRefused' | 'sanction' | 'notMoved' | 'restricted' | '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, or none for this member. */
+    block: 'notMoved' | 'restricted' | 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;
+}
+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;
+}
+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>;
+    beginOnboarding(): void;
+    cancelOnboarding(): void;
+    /** Seconds a draft still waits (0 when it may go). */
+    waitLeft(draft: Draft): number;
+    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,17 @@
+/**
+ * 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;
+/** 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,52 @@
+import { type AgeBand, type CommunityClient, type CommunityFailure, type CommunityRule, type CurrentLegalText, type MyState } from '@blogmcp/sdk/community';
+import type { Lang } from './i18n';
+export type OnboardingStep = 'age' | 'rules' | 'art9' | 'profile';
+export type OnboardingPhase = 'loading' | 'ready' | 'sending' | 'done' | 'failed' | 'refused';
+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[];
+    /** The member accepted an older rules text; this one asks again. */
+    reconsent: boolean;
+    ageBand: AgeBand | null;
+    rulesAccepted: boolean;
+    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;
+}
+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;
+    signal?: AbortSignal;
+}
+export declare function createOnboarding(o: OnboardingOptions): OnboardingModel;

package/dist/core/outcomes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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;
+ *   - `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;

package/dist/core/panel.d.ts

@@ -0,0 +1,80 @@
+import { type AppealItem, type BlockEntry, type CommunityClient, type CommunityFailure, type DecisionSummary, type MemberExport, type MyState, type NoticeStatus, type NotificationItem, type ReportItem, type Statement } from '@blogmcp/sdk/community';
+import type { TextRef } from './i18n';
+export type LoadPhase = 'idle' | 'loading' | 'ready' | 'failed';
+export interface AppealDraft {
+    body: string;
+    sending: boolean;
+    failure: CommunityFailure | null;
+}
+export interface ProfileDraft {
+    displayName: string;
+    handle: string;
+    avatarPreset: string | null;
+    sending: boolean;
+    failure: CommunityFailure | null;
+    fields: string[];
+}
+export interface PanelUi {
+    /** The member's part: `signIn` when the session cannot act as a member (or there is none). */
+    phase: LoadPhase | 'signIn';
+    failure: CommunityFailure | null;
+    me: MyState | null;
+    notifications: NotificationItem[];
+    decisions: DecisionSummary[];
+    appeals: AppealItem[];
+    reports: ReportItem[];
+    blocks: BlockEntry[];
+    /** The statement the page opens (`decision-id`). */
+    statement: {
+        phase: LoadPhase | 'signIn';
+        value: Statement | null;
+        failure: CommunityFailure | null;
+        appeal: AppealDraft;
+    };
+    /** The notifier's part (`#t=` in the address). `missing`: a `#t=` that holds no receipt. */
+    notice: {
+        phase: LoadPhase | 'missing';
+        value: NoticeStatus | null;
+        failure: CommunityFailure | null;
+        appeal: AppealDraft;
+    };
+    profile: ProfileDraft | null;
+    /** The profile's deletion: its date once requested here (kb-api's MyState does not carry it). */
+    purgeAfter: string | null;
+    exporting: boolean;
+    busy: Record<string, boolean>;
+    announcement: TextRef | null;
+    announceId: number;
+}
+export interface PanelController {
+    readonly state: PanelUi;
+    /** The member's sections (me/get and the lists). */
+    loadMember(): Promise<void>;
+    loadStatement(decisionId: string): Promise<void>;
+    loadNotice(receipt: string | null): Promise<void>;
+    unreadCount(): number;
+    markAllRead(): Promise<void>;
+    fileAppeal(): Promise<void>;
+    withdrawAppeal(): Promise<void>;
+    fileNoticeAppeal(): Promise<void>;
+    withdrawNoticeAppeal(): Promise<void>;
+    withdrawConsent(): Promise<boolean>;
+    unblock(memberId: string): Promise<void>;
+    editProfile(): void;
+    cancelProfile(): void;
+    saveProfile(): Promise<void>;
+    /** `me/export` as a JSON file the browser saves (`save` does the download; tests pass their own). */
+    exportData(save: (data: MemberExport) => void): Promise<void>;
+    erase(): Promise<boolean>;
+    cancelErase(): Promise<void>;
+    /** The member asked for the deletion (here or before). */
+    erasing(): boolean;
+    appealLength(draft: AppealDraft): number;
+    canAppealWith(draft: AppealDraft): boolean;
+    dispose(): void;
+}
+export interface PanelOptions {
+    client: CommunityClient;
+    lang: string;
+}
+export declare function createPanel(o: PanelOptions): PanelController;

package/dist/core/receipt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The receipt this element's page carries: a string; `null` for a `#t=` that holds none (a cut link — "incomplete",
+ * never an older receipt of the tab); `undefined` when the page carries none for it.
+ */
+export declare function receiptForElement(owner: object | null): string | null | undefined;

package/dist/core/text.d.ts

@@ -0,0 +1,22 @@
+export type TextSegment = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'link';
+    readonly text: string;
+    readonly href: string;
+};
+/** The rel every link to what a member wrote carries (user-generated, no referrer, no opener). */
+export declare const UGC_LINK_REL = "nofollow ugc noopener noreferrer";
+/** A member's text as text runs and links. */
+export declare function linkify(text: string): TextSegment[];
+/** Characters in code points, as kb-api counts a body (after NFC and trimming). */
+export declare function codePointLength(text: string): number;
+/** A body as kb-api will measure it: NFC, trimmed. */
+export declare function normalizeBody(text: string): string;
+/**
+ * The paragraphs of the tenant's own legal text (`legal/current`'s `body` is HTML with anchors) as plain
+ * text, for the art. 9 consent step: tags are dropped and entities decoded AFTER that, so nothing in the
+ * text is ever parsed as markup again. String work only — no HTML parser, no live DOM.
+ */
+export declare function htmlToParagraphs(html: string): string[];

package/dist/core/turnstile.d.ts

@@ -0,0 +1,33 @@
+export declare const TURNSTILE_SCRIPT_SRC = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+interface TurnstileRenderOptions {
+    sitekey: string;
+    action?: string;
+    language?: string;
+    appearance?: 'always' | 'execute' | 'interaction-only';
+    callback?: (token: string) => void;
+    'expired-callback'?: () => void;
+    'error-callback'?: () => void;
+    'timeout-callback'?: () => void;
+}
+export interface TurnstileApi {
+    render(el: HTMLElement, options: TurnstileRenderOptions): string;
+    reset(widgetId: string): void;
+    remove(widgetId: string): void;
+}
+/** One `<script>` per page however many forms mount; a failed load may be tried again later. */
+export declare function loadTurnstile(nonce?: string): Promise<TurnstileApi>;
+export interface TurnstileWidget {
+    /** A fresh token (the last one is spent). */
+    reset(): void;
+    remove(): void;
+}
+export interface RenderTurnstileOptions {
+    siteKey: string;
+    language: string;
+    /** A new token, or null when it expired or failed (the form cannot be sent until a new one comes). */
+    onToken(token: string | null): void;
+    nonce?: string;
+}
+/** The widget in `container`; rejects when the script cannot load (an ad blocker, the network). */
+export declare function renderTurnstile(container: HTMLElement, o: RenderTurnstileOptions): Promise<TurnstileWidget>;
+export {};

package/dist/element.d.ts

@@ -0,0 +1,26 @@
+export declare const DISCUSSION_ELEMENT_TAG = "blogmcp-discussion";
+export declare const NOTICE_FORM_ELEMENT_TAG = "blogmcp-notice-form";
+export declare const MY_COMMUNITY_ELEMENT_TAG = "blogmcp-my-community";
+export interface DefineCommunityElementOptions {
+    /** Another tag name for the element. */
+    tag?: string;
+    /** CSP nonce for the element's `<style>` (else each element's own `nonce`). */
+    nonce?: string;
+}
+export interface DefineCommunityElementsOptions {
+    /** CSP nonce for the elements' `<style>`. */
+    nonce?: string;
+    tags?: {
+        discussion?: string;
+        noticeForm?: string;
+        myCommunity?: string;
+    };
+}
+/** Register `<blogmcp-discussion>` (once; later calls are no-ops). Browser only. */
+export declare function defineDiscussionElement(opts?: DefineCommunityElementOptions): void;
+/** Register `<blogmcp-notice-form>` (once). Browser only. */
+export declare function defineNoticeFormElement(opts?: DefineCommunityElementOptions): void;
+/** Register `<blogmcp-my-community>` (once). Browser only. */
+export declare function defineMyCommunityElement(opts?: DefineCommunityElementOptions): void;
+/** Register all three (once). Browser only. */
+export declare function defineCommunityElements(opts?: DefineCommunityElementsOptions): void;

package/dist/global.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `<script>` build: registers `<blogmcp-discussion>`, `<blogmcp-notice-form>` and `<blogmcp-my-community>`
+ * with the script tag's own CSP nonce, and exposes `window.BlogmcpCommunity`.
+ */
+import { defineCommunityElements } from './element';
+import { mountDiscussion, mountMyCommunity, mountNoticeForm } from './mount';
+import { VERSION } from './version';
+export { defineCommunityElements, mountDiscussion, mountMyCommunity, mountNoticeForm, VERSION };