@beezping/adapter-memory 0.6.0 → 0.7.0

package/dist/types.d.ts

@@ -1,96 +1,152 @@
-import { type Prettify, type Serialized } from "./type-utils.js";
+import { type DeepReadonly, type Prettify, type Serialized } from "./type-utils.js";
 /** FAB anchor — bottom-corner placement supported by the widget. */
-export type SitepingPosition = "bottom-right" | "bottom-left";
+export type BeezpingPosition = "bottom-right" | "bottom-left";
 /** Visual theme — `auto` resolves to `light` or `dark` via system preference. */
-export type SitepingTheme = "light" | "dark" | "auto";
+export type BeezpingTheme = "light" | "dark" | "auto";
 /** Built-in UI locales shipped with the widget. */
-export declare const BUILTIN_LOCALES: readonly ["en", "fr", "de", "es", "it", "pt", "ru"];
+export declare const BUILTIN_LOCALES: readonly ["en", "fr", "de", "es", "it", "pt", "ru", "ja"];
 export type BuiltinLocale = (typeof BUILTIN_LOCALES)[number];
 /**
  * Locale identifier accepted by the widget. Built-in locales are kept as
  * literal strings so editors auto-complete them, but arbitrary BCP-47 tags
  * are also accepted (custom dictionaries registered via `registerLocale`).
  */
-export type SitepingLocale = BuiltinLocale | (string & {});
+export type BeezpingLocale = BuiltinLocale | (string & {});
 /**
- * Reasons reported through `SitepingConfig.onSkip` — production environment,
- * mobile viewport, or server-side rendering (no `window`/`document`).
+ * Reasons reported through `BeezpingConfig.onSkip` — production environment,
+ * viewport narrower than `minViewportWidth` (`"mobile"`), or server-side
+ * rendering (no `window`/`document`).
  */
-export type SitepingSkipReason = "production" | "mobile" | "ssr";
+export type BeezpingSkipReason = "production" | "mobile" | "ssr";
 /** Per-channel + per-buffer-size diagnostics configuration. */
 export interface DiagnosticsCaptureOptions {
     console?: boolean | undefined;
     network?: boolean | undefined;
+    /** Console buffer size — default and maximum 50 (the server's cap; larger values are clamped). */
     maxConsoleEntries?: number | undefined;
+    /** Failed-request buffer size — default and maximum 20 (the server's cap; larger values are clamped). */
     maxNetworkEntries?: number | undefined;
 }
 /** Identity payload supplied by the host application — bypasses the modal. */
-export interface SitepingIdentity {
+export interface BeezpingIdentity {
     name: string;
     email: string;
 }
+/**
+ * Max length of an identity's `name` and `email` — the HTTP schema's
+ * `authorName` / `authorEmail` cap. The widget's modal enforces it so a value
+ * it persists is never a 400 on every later submission.
+ */
+export declare const IDENTITY_FIELD_MAX_LENGTH = 200;
 /** Deep-link configuration — controls how a feedback id is read from the URL. */
-export interface SitepingDeepLinkOptions {
-    /** Query parameter name carrying the feedback id. Defaults to `"siteping"`. */
+export interface BeezpingDeepLinkOptions {
+    /** Query parameter name carrying the feedback id. Defaults to `"beezping"`. */
     param?: string | undefined;
 }
 /**
- * Extra request headers for HTTP mode — a static map, or a factory (sync or
- * async) invoked once per request to produce fresh values (e.g. a short-lived
- * session token).
+ * The feedback handed to panel action callbacks: a detached, deeply frozen
+ * copy, typed read-only all the way down. Type your own helpers with it — a
+ * `FeedbackResponse` parameter does not accept the frozen copy.
  */
-export type SitepingHeadersOption = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+export type BeezpingPanelActionFeedback = DeepReadonly<FeedbackResponse>;
 /**
- * Cookie policy for HTTP-mode requests — forwarded verbatim as the
- * `credentials` option of every `fetch` the widget (or the dashboard's
- * endpoint source) makes. Mirrors the DOM `RequestCredentials` union,
- * declared here so core stays free of DOM lib types.
- *
- * - `"same-origin"` (default): cookies only when the endpoint shares the
- *   page's origin — the browser's own default.
- * - `"include"`: also send cookies to a cross-origin endpoint. Required when a
- *   server on another origin authenticates with a session cookie; the server
- *   must answer with credentialed CORS (the page's exact origin plus
- *   `Access-Control-Allow-Credentials: true`, e.g. `@beezping/server`'s
- *   `allowedOrigins`).
- * - `"omit"`: never send cookies, even same-origin.
- */
-export type SitepingRequestCredentials = "omit" | "same-origin" | "include";
-/** Every accepted {@link SitepingRequestCredentials} value — runtime guard source for untyped (script-tag) consumers. */
-export declare const REQUEST_CREDENTIALS_MODES: readonly ["omit", "same-origin", "include"];
-/**
- * Credentials mode used when none is configured — the browser's own `fetch`
- * default, so leaving the option unset never changes cookie behavior (and
- * never opts a cross-origin endpoint into cookie-carrying, CSRF-prone requests).
- */
-export declare const DEFAULT_REQUEST_CREDENTIALS = "same-origin";
-/**
- * Narrow an untyped config value to a {@link SitepingRequestCredentials} mode.
+ * Helpers passed to a panel action's `onAction` as its second argument.
+ * Both do nothing once the widget has been destroyed.
+ */
+export interface BeezpingPanelActionContext {
+    /**
+     * Re-fetch the panel list and markers, then re-render the detail view with
+     * the updated feedback — or go back to the list when it no longer matches
+     * the panel filters. Call it after your action changed the feedback
+     * server-side (e.g. moved it to `in_progress` once a ticket exists).
+     */
+    refresh: () => Promise<void>;
+    /** Close the feedback panel. */
+    close: () => void;
+}
+/**
+ * Fields shared by both kinds of {@link BeezpingPanelAction}.
  *
- * @param value - Raw `credentials` option (may come from an untyped script-tag config).
- * @returns `true` when `value` is one of {@link REQUEST_CREDENTIALS_MODES}.
+ * Do not use this type directly — use {@link BeezpingPanelAction}.
  */
-export declare function isRequestCredentials(value: unknown): value is SitepingRequestCredentials;
+export interface BeezpingPanelActionBase {
+    /** Stable, unique identifier — becomes `data-action-id` on the rendered control. */
+    id: string;
+    /**
+     * Visible label, rendered as plain text. Host-provided verbatim — not
+     * routed through the widget i18n, since hosts localize their own strings.
+     */
+    label: string;
+    /**
+     * Optional inline SVG markup rendered before the label. It is parsed
+     * inertly and reduced to plain shapes — scripts, event handlers, links,
+     * styles and external references are dropped — but keep it static markup
+     * you control. Markup that is not an `<svg>` is ignored with a warning.
+     */
+    icon?: string | undefined;
+    /**
+     * Per-feedback visibility predicate. Return `false` to omit the action
+     * for that feedback. Defaults to always visible. A throw hides the action
+     * and is reported through `onError`.
+     */
+    visible?: ((feedback: BeezpingPanelActionFeedback) => boolean) | undefined;
+}
+/** A panel action rendered as a button that runs host code. */
+export interface BeezpingPanelButtonAction extends BeezpingPanelActionBase {
+    /**
+     * Invoked on click. While a returned promise is pending the detail view's
+     * action buttons are disabled and the clicked button shows a spinner —
+     * also after `context.refresh()` re-renders the view, and when the user
+     * comes back to that feedback.
+     * Throws and rejections are reported through `onError` and restore the
+     * buttons; the detail view stays open either way.
+     */
+    onAction: (feedback: BeezpingPanelActionFeedback, context: BeezpingPanelActionContext) => void | Promise<void>;
+    /** Not available on a button action — use either `onAction` or `href`, never both. */
+    href?: never;
+}
+/** A panel action rendered as a link. */
+export interface BeezpingPanelLinkAction extends BeezpingPanelActionBase {
+    /**
+     * Link target — a URL, or a function building one from the feedback.
+     * Relative URLs resolve against the page. Only `http:`, `https:` and
+     * `mailto:` are rendered: a static `href` with any other scheme
+     * (`javascript:` included) skips the action with a warning; a function
+     * returning one hides the action and is reported through `onError`. Web
+     * links open in a new tab with `rel="noopener noreferrer"`.
+     */
+    href: string | ((feedback: BeezpingPanelActionFeedback) => string);
+    /** Not available on a link action — use either `onAction` or `href`, never both. */
+    onAction?: never;
+}
 /**
- * Actionable description of a rejected `credentials` option — shared by the
- * widget init guard and the dashboard's endpoint source so both report the
- * same wording.
+ * A host-defined action rendered in the feedback detail view, below the
+ * built-in Resolve / Delete buttons: a button running your code
+ * (`onAction`) or a link (`href`) — never both.
  *
- * @param value - The rejected raw value (a config value, never user content).
- * @returns e.g. `invalid \`credentials\` "all". Expected one of "omit", "same-origin", "include".`
+ * Hosts use this to bridge feedbacks into their own systems — create a
+ * ticket, dispatch to a bot, open the feedback in their tracker — without
+ * forking the panel. Callbacks receive a detached, deeply frozen copy of
+ * the feedback: read it freely, it can never alter what the panel displays.
  */
-export declare function describeInvalidRequestCredentials(value: unknown): string;
+export type BeezpingPanelAction = BeezpingPanelButtonAction | BeezpingPanelLinkAction;
+/**
+ * Extra request headers for HTTP mode — a static map, or a factory (sync or
+ * async) invoked once per request to produce fresh values (e.g. a short-lived
+ * session token).
+ */
+export type BeezpingHeadersOption = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
 /**
  * Options shared by both widget modes (HTTP and direct store).
  *
- * Do not use this type directly — use {@link SitepingConfig}, the
+ * Do not use this type directly — use {@link BeezpingConfig}, the
  * discriminated union that adds the mode-specific fields.
  */
-export interface SitepingBaseConfig {
+export interface BeezpingBaseConfig {
     /** Required — project identifier used to scope feedbacks */
     projectName: string;
     /** FAB position — defaults to 'bottom-right' */
-    position?: SitepingPosition | undefined;
+    position?: BeezpingPosition | undefined;
     /**
      * Show the "toggle markers visibility" item in the FAB radial menu.
      * Defaults to `true` (current behavior). Set to `false` to hide that
@@ -109,7 +165,7 @@ export interface SitepingBaseConfig {
     accentColor?: string | undefined;
     /**
      * Render the widget even when it would normally be skipped — this bypasses
-     * BOTH the production-environment guard AND the mobile-viewport guard.
+     * BOTH the production-environment guard AND the `minViewportWidth` guard.
      * It does NOT bypass the SSR guard: without `window`/`document` the widget
      * never renders and `onSkip("ssr")` fires instead.
      * Defaults to false. Use it for dedicated review tools, staging environments,
@@ -118,18 +174,20 @@ export interface SitepingBaseConfig {
     forceShow?: boolean | undefined;
     /**
      * Minimum viewport width (px) at or above which the widget renders. Below it,
-     * the widget is skipped and `onSkip("mobile")` fires. Defaults to `768`.
+     * the widget is skipped and `onSkip("mobile")` fires. Defaults to `0`: the
+     * widget renders at every width, and phones get a compact layout (bottom
+     * sheets, touch-sized controls).
      *
-     * Set lower (e.g. `0`) to allow narrow/mobile viewports, or use `forceShow`
-     * to bypass the viewport check entirely.
+     * Set it (e.g. `768`) to keep the widget off small screens, or use
+     * `forceShow` to bypass the viewport check entirely.
      */
     minViewportWidth?: number | undefined;
     /** Enable debug logging of lifecycle events — defaults to false */
     debug?: boolean | undefined;
     /** Color theme — defaults to 'light' */
-    theme?: SitepingTheme | undefined;
-    /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru. Any other string falls back to English. */
-    locale?: SitepingLocale | undefined;
+    theme?: BeezpingTheme | undefined;
+    /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru, ja. Any other string falls back to English. */
+    locale?: BeezpingLocale | undefined;
     /**
      * Returns the current page scope for annotations and panel filtering.
      * Called on initial markers load and on `instance.refresh()`.
@@ -161,7 +219,7 @@ export interface SitepingBaseConfig {
      * `html2canvas-pro` ships as a regular dependency of `@beezping/widget` so the
      * dynamic import always resolves; you don't need to install anything extra.
      *
-     * **Masking sensitive elements:** add `data-siteping-ignore="true"` to any
+     * **Masking sensitive elements:** add `data-beezping-ignore="true"` to any
      * element you do NOT want captured (password fields, credit-card forms,
      * API tokens shown in the UI, etc.). The capture predicate skips matching
      * elements *and their descendants*. Do this BEFORE turning on screenshots
@@ -179,18 +237,21 @@ export interface SitepingBaseConfig {
      *
      * Keyboard-triggered context menus (≣ Menu key, Shift+F10) always get the
      * native menu; only mouse right-click and touch/pen long-press open the
-     * composer.
+     * composer — a long-press only where the browser fires `contextmenu` for
+     * it, which iOS and iPadOS never do (see the note below).
      *
      * **Modifier-key escape hatch:** holding Shift, Ctrl, Alt, or Meta while
      * right-clicking always falls through to the native context menu, giving
      * users (and devtools) an escape hatch regardless of this setting.
      *
-     * Right-clicks on SitePing's own UI (FAB, panel, markers, popup) are
+     * Right-clicks on Beezping's own UI (FAB, panel, markers, popup) are
      * ignored — the native menu is shown as expected.
      *
-     * Note: on Android, `contextmenu` fires on long-press. The widget already
-     * hides below `minViewportWidth` (default 768 px), but tablets above that
-     * threshold will trigger this flow on long-press.
+     * Note: on Android, `contextmenu` fires on long-press — touch users open the
+     * composer by long-pressing, on phones too since the widget renders at every
+     * width by default (see `minViewportWidth`). On iPhone and iPad a long-press
+     * never fires `contextmenu` (WebKit bug 213953): users there open annotate
+     * mode from the floating button and tap the element.
      */
     enableRightClickComment?: boolean | undefined;
     /**
@@ -203,16 +264,19 @@ export interface SitepingBaseConfig {
      *
      * - `true` — capture with defaults (50 console / 20 network entries).
      * - `false` (default) — no capture, no monkey-patching.
-     * - object — per-channel toggles + custom buffer sizes.
+     * - object — per-channel toggles + smaller buffer sizes (values above the
+     *   50 / 20 server caps are clamped so submissions never fail validation).
      *
      * **Privacy considerations:** console messages may contain anything the
      * host page logs, including user data. Failed network requests record the
-     * URL (with query string) but never the response body. Inform end users
-     * before enabling in environments where they might log sensitive values.
+     * URL without its credentials, query string or hash, and never the
+     * response body.
+     * Inform end users before enabling in environments where they might log
+     * sensitive values.
      */
     captureDiagnostics?: boolean | DiagnosticsCaptureOptions | undefined;
-    /** Called when the widget is skipped (production mode, mobile viewport, SSR — no DOM) */
-    onSkip?: (reason: SitepingSkipReason) => void;
+    /** Called when the widget is skipped (production mode, viewport under `minViewportWidth`, SSR — no DOM) */
+    onSkip?: (reason: BeezpingSkipReason) => void;
     /**
      * Auto-focus a specific annotation when its ID appears in the URL query
      * string. Lets hosts deeplink directly into a feedback from external
@@ -226,7 +290,7 @@ export interface SitepingBaseConfig {
      *
      * - `false` / `undefined` (default): no URL parsing. Existing behavior
      *   unchanged, no host URL inspection.
-     * - `true`: enabled with default query parameter name `siteping`.
+     * - `true`: enabled with default query parameter name `beezping`.
      * - object: enabled with a custom parameter name. Use this to avoid
      *   clashes with host-app query keys.
      *
@@ -236,7 +300,7 @@ export interface SitepingBaseConfig {
      * Hosts that need re-focus on route change can call
      * `instance.focusFeedback(id)` explicitly.
      */
-    deepLink?: boolean | SitepingDeepLinkOptions | undefined;
+    deepLink?: boolean | BeezpingDeepLinkOptions | undefined;
     /**
      * Automatically re-fetch feedbacks when the page changes during client-side
      * (SPA) navigation. Enabled by default.
@@ -275,26 +339,51 @@ export interface SitepingBaseConfig {
      * read at widget init time, not on every render. Hosts that need live
      * identity updates after sign-in/sign-out should currently remount the
      * widget (e.g. via a React `key` on the wrapping component). See
-     * https://github.com/NeosiaNexus/SitePing/issues/85 for tracking a
+     * https://github.com/guidomodarelli/beezping/issues/85 for tracking a
      * future enhancement that propagates identity updates without a remount.
      */
-    identity?: SitepingIdentity | undefined;
+    identity?: BeezpingIdentity | undefined;
+    /**
+     * Host-defined actions rendered in the feedback detail view, below the
+     * built-in Resolve and Delete buttons. Read once when the panel loads:
+     * entries without a non-empty `id` and `label`, without exactly one of
+     * `onAction` / `href`, with an unsafe static `href`, or reusing an earlier
+     * `id` are skipped with a console warning. See {@link BeezpingPanelAction}.
+     */
+    panelActions?: readonly BeezpingPanelAction[] | undefined;
+    /**
+     * Reviewer mode: hide the actions that triage feedback — resolve, reopen,
+     * delete, the bulk actions, "Delete all" — and keep creating, browsing
+     * and replying. Defaults to `false`. The server's `permissions` hide
+     * what it would refuse on top of it. It only hides: the server decides
+     * what it accepts. Read once when the panel loads.
+     */
+    readOnly?: boolean | undefined;
     /** Called when the feedback panel is opened. */
     onOpen?: (() => void) | undefined;
     /** Called when the feedback panel is closed. */
     onClose?: (() => void) | undefined;
     /** Called after a feedback is successfully submitted. */
     onFeedbackSent?: ((feedback: FeedbackResponse) => void) | undefined;
+    /** Called after a reply is posted from the panel's discussion thread. */
+    onCommentAdded?: ((comment: CommentResponse) => void) | undefined;
     /**
      * Called when a feedback API call fails.
      *
-     * The widget always emits a `SitepingError` (or a subclass:
-     * `SitepingNetworkError`, `SitepingValidationError`, `SitepingAuthError`)
+     * The widget always emits a `BeezpingError` (or a subclass:
+     * `BeezpingNetworkError`, `BeezpingValidationError`, `BeezpingAuthError`)
      * for HTTP-mode failures — host apps can `instanceof` to drive retry
      * logic, or read `error.code` (`"NETWORK" | "VALIDATION" | "AUTH" |
-     * "SERVER"`) and `error.retryable`. The type is widened to `Error` so
-     * direct-store callers can still surface raw errors without breaking the
-     * contract.
+     * "SERVER"`) and `error.retryable` — and an `AUTH` error's `status`
+     * (`401` for missing or dead credentials, `403` for a refusal). The type
+     * is widened to `Error` so direct-store callers can still surface raw
+     * errors without breaking the contract.
+     *
+     * Also receives whatever a `panelActions` callback throws or rejects with
+     * (non-`Error` values are wrapped). Those host failures are not API
+     * failures, so they are not emitted on the public `feedback:error` event.
+     * The widget has no UI for them, so they are also always logged with
+     * `console.error`, whether or not `onError` is set.
      */
     onError?: ((error: Error) => void) | undefined;
     /** Called when the user starts drawing an annotation. */
@@ -306,8 +395,8 @@ export interface SitepingBaseConfig {
  * HTTP mode — the widget talks to a server endpoint backed by a store
  * adapter (e.g. `@beezping/adapter-prisma` request handlers).
  */
-export interface SitepingHttpConfig extends SitepingBaseConfig {
-    /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). */
+export interface BeezpingHttpConfig extends BeezpingBaseConfig {
+    /** HTTP endpoint that receives feedbacks (e.g. '/api/beezping'). */
     endpoint: string;
     /**
      * Convenience auth for HTTP mode — sent as `Authorization: Bearer <apiKey>`
@@ -323,60 +412,44 @@ export interface SitepingHttpConfig extends SitepingBaseConfig {
     /**
      * Extra headers for every HTTP-mode request — a static map, or a factory
      * (sync or async) called once per request (e.g. to fetch a fresh session
-     * token). Merged over the widget's generated headers, so an explicit
-     * `Authorization` entry overrides `apiKey`. A throwing/rejecting factory
-     * fails the request like a network error.
-     */
-    headers?: SitepingHeadersOption | undefined;
-    /**
-     * Cookie policy for every HTTP-mode request (submit, list, update, delete
-     * and the offline retry-queue replay). Defaults to `"same-origin"` — the
-     * browser default, so existing setups are unchanged.
-     *
-     * Set `"include"` when `endpoint` lives on **another origin** and the
-     * server authenticates with a session cookie (e.g. a custom
-     * `access.authenticate` in `@beezping/server`): without it the browser
-     * never attaches the cookie and every request is rejected as
-     * unauthenticated. The server must allow the page's origin explicitly with
-     * credentialed CORS (`allowedOrigins`) — a wildcard origin never works
-     * with cookies. Only opt in for origins you trust: cookie-authenticated
-     * cross-origin requests rely on the server's CSRF defenses (strict origin
-     * allowlist, `SameSite` cookies).
-     *
-     * An unknown value (untyped script-tag config) is rejected at init: the
-     * widget logs an error and does not load.
-     */
-    credentials?: SitepingRequestCredentials | undefined;
+     * token). Merged over the widget's generated headers, case-insensitively,
+     * so an explicit `Authorization` entry overrides `apiKey`. A factory that
+     * throws, rejects, or does not settle within 10 s fails the request like a
+     * network error.
+     */
+    headers?: BeezpingHeadersOption | undefined;
     /** Not available in HTTP mode — use either `endpoint` or `store`, never both. */
     store?: never;
 }
 /**
- * Store mode — the widget talks to a `SitepingStore` directly in the
+ * Store mode — the widget talks to a `BeezpingStore` directly in the
  * browser, no server needed (demos, prototypes, localStorage persistence).
  */
-export interface SitepingStoreConfig extends SitepingBaseConfig {
-    /** Direct store for client-side mode. Bypasses HTTP entirely. */
-    store: SitepingStore;
+export interface BeezpingStoreConfig extends BeezpingBaseConfig {
+    /**
+     * Direct store for client-side mode. Bypasses HTTP entirely. A send stops
+     * waiting on `createFeedback` after 30 s (the call itself cannot be
+     * cancelled), so a network-backed store should bound its own calls.
+     */
+    store: BeezpingStore;
     /** Not available in store mode — use either `endpoint` or `store`, never both. */
     endpoint?: never;
     /** HTTP-mode only — meaningless without an `endpoint`. */
     apiKey?: never;
     /** HTTP-mode only — meaningless without an `endpoint`. */
     headers?: never;
-    /** HTTP-mode only — meaningless without an `endpoint`. */
-    credentials?: never;
 }
 /**
- * Configuration options for the Siteping widget.
+ * Configuration options for the Beezping widget.
  *
  * A discriminated union over the two transport modes: pass `endpoint`
- * (HTTP mode, optionally with `apiKey`/`headers`/`credentials`) **or** `store` (direct
+ * (HTTP mode, optionally with `apiKey`/`headers`) **or** `store` (direct
  * client-side mode) — never both, never neither. Invalid combinations are
  * compile errors instead of runtime warnings.
  */
-export type SitepingConfig = SitepingHttpConfig | SitepingStoreConfig;
-/** Instance returned by initSiteping() with lifecycle methods. */
-export interface SitepingInstance {
+export type BeezpingConfig = BeezpingHttpConfig | BeezpingStoreConfig;
+/** Instance returned by initBeezping() with lifecycle methods. */
+export interface BeezpingInstance {
     /** Remove the widget from the DOM and clean up all listeners. */
     destroy: () => void;
     /** Open the panel programmatically */
@@ -397,21 +470,23 @@ export interface SitepingInstance {
      */
     focusFeedback: (feedbackId: string) => boolean;
     /** Subscribe to a public widget event */
-    on: <K extends keyof SitepingPublicEvents>(event: K, listener: SitepingPublicEventListener<K>) => SitepingUnsubscribe;
+    on: <K extends keyof BeezpingPublicEvents>(event: K, listener: BeezpingPublicEventListener<K>) => BeezpingUnsubscribe;
     /** Unsubscribe from a public widget event */
-    off: <K extends keyof SitepingPublicEvents>(event: K, listener: SitepingPublicEventListener<K>) => void;
-}
-/** Listener signature for a single `SitepingPublicEvents` key. */
-export type SitepingPublicEventListener<K extends keyof SitepingPublicEvents> = (...args: SitepingPublicEvents[K]) => void;
-/** Disposer returned by `SitepingInstance.on` — call once to detach the listener. */
-export type SitepingUnsubscribe = () => void;
-/** Events exposed to consumers via SitepingInstance.on / .off */
-export interface SitepingPublicEvents {
+    off: <K extends keyof BeezpingPublicEvents>(event: K, listener: BeezpingPublicEventListener<K>) => void;
+}
+/** Listener signature for a single `BeezpingPublicEvents` key. */
+export type BeezpingPublicEventListener<K extends keyof BeezpingPublicEvents> = (...args: BeezpingPublicEvents[K]) => void;
+/** Disposer returned by `BeezpingInstance.on` — call once to detach the listener. */
+export type BeezpingUnsubscribe = () => void;
+/** Events exposed to consumers via BeezpingInstance.on / .off */
+export interface BeezpingPublicEvents {
     "feedback:sent": [FeedbackResponse];
     "feedback:deleted": [FeedbackResponse["id"]];
+    /** A reply was posted from the panel's discussion thread. */
+    "comment:added": [CommentResponse];
     /**
      * A feedback API call failed. Same payload contract as
-     * `SitepingConfig.onError` — a `SitepingError` subclass in HTTP mode,
+     * `BeezpingConfig.onError` — a `BeezpingError` subclass in HTTP mode,
      * possibly a raw `Error` in store mode.
      */
     "feedback:error": [Error];
@@ -444,7 +519,7 @@ export type OpenFeedbackStatus = (typeof OPEN_FEEDBACK_STATUSES)[number];
 /** Whether a status is terminal (`resolved` or `wont_fix`). Narrows the status type. */
 export declare function isClosedStatus(status: FeedbackStatus): status is ClosedFeedbackStatus;
 /**
- * Page scope returned by `SitepingConfig.getPageScope()`.
+ * Page scope returned by `BeezpingConfig.getPageScope()`.
  *
  * - `url`: concrete page identifier — usually `window.location.pathname`,
  *   used as the strict scope for marker rendering.
@@ -495,7 +570,7 @@ export interface FeedbackCreateInput {
     screenshotRegion?: ScreenshotRegion | null | undefined;
     /**
      * Optional console + failed-network snapshot captured by the widget when
-     * `SitepingConfig.captureDiagnostics` is enabled. Stored as JSON on
+     * `BeezpingConfig.captureDiagnostics` is enabled. Stored as JSON on
      * `FeedbackRecord.diagnostics` so reviewers can replay the context.
      */
     diagnostics?: DiagnosticsSnapshot | null | undefined;
@@ -543,6 +618,11 @@ export interface FeedbackQuery {
     statuses?: readonly FeedbackStatus[] | undefined;
     search?: string | undefined;
     page?: number | undefined;
+    /**
+     * Page size. Defaults to `DEFAULT_PAGE_LIMIT` (50) and is capped at
+     * `MAX_PAGE_LIMIT` (100) — `clampPagination` implements both, and the
+     * conformance suite checks them.
+     */
     limit?: number | undefined;
     /**
      * Filter to feedbacks created on this exact URL (path). Used by the panel's
@@ -601,6 +681,13 @@ export interface FeedbackRecord {
     createdAt: Date;
     updatedAt: Date;
     annotations: AnnotationRecord[];
+    /**
+     * Discussion thread, oldest first. A store that implements
+     * `BeezpingStore.addComment` returns it on every record; a store without
+     * comments may leave it out, which reads as an empty thread (HTTP handlers
+     * send `[]`).
+     */
+    comments?: CommentRecord[] | undefined;
     /**
      * URL the widget renders as `<img src>`. Either an `https://...` from a
      * configured `ScreenshotStorage`, or a `data:image/jpeg;base64,...` URL
@@ -648,6 +735,66 @@ export interface AnnotationRecord {
     devicePixelRatio: number;
     createdAt: Date;
 }
+/**
+ * Who wrote a comment: `client` — the reviewer on the site (the widget) —
+ * or `team` — the project side (the dashboard). HTTP handlers stamp
+ * `client` unless the server's access policy vouches for the caller, so a
+ * visitor cannot pose as the team.
+ */
+export declare const COMMENT_AUTHOR_ROLES: readonly ["client", "team"];
+export type CommentAuthorRole = (typeof COMMENT_AUTHOR_ROLES)[number];
+/** Longest comment `body` the HTTP API accepts — the cap of a feedback `message`. */
+export declare const COMMENT_BODY_MAX_LENGTH = 5000;
+/**
+ * Most `client` comments one thread holds. List responses embed whole
+ * threads, which are not paginated, so this bounds what one feedback weighs
+ * however much a public endpoint is spammed. `team` comments — a role only
+ * the access policy grants — neither count nor meet it: a thread spammed
+ * full still takes the team's answer. Stores enforce it with
+ * `StoreLimitError`; a store without an atomic primitive may overshoot it by
+ * the posts that race the last free slot.
+ */
+export declare const MAX_COMMENTS_PER_FEEDBACK = 100;
+/** A persisted comment returned by the store. */
+export interface CommentRecord {
+    id: string;
+    /** The feedback whose thread holds this comment. */
+    feedbackId: string;
+    body: string;
+    authorName: string;
+    /**
+     * Author email, or `""` when the author has none on file (a dashboard
+     * user). HTTP handlers redact it exactly like `FeedbackRecord.authorEmail`.
+     */
+    authorEmail: string;
+    authorRole: CommentAuthorRole;
+    /** Client-generated id — `addComment` is idempotent on it, so a retried post never duplicates a reply. */
+    clientId: string;
+    createdAt: Date;
+}
+/** Input of `BeezpingStore.addComment`. */
+export interface CommentCreateInput {
+    body: string;
+    authorName: string;
+    authorEmail: string;
+    authorRole: CommentAuthorRole;
+    clientId: string;
+}
+/**
+ * Body of a comment `POST`. `feedbackId` is what tells it apart from a
+ * feedback submission on the same endpoint; `projectName` scopes the write
+ * to that project's feedbacks.
+ */
+export interface CommentPayload extends CommentCreateInput {
+    projectName: string;
+    feedbackId: string;
+}
+/** Body of a comment `DELETE` — `commentId` is what tells it apart from a feedback delete. */
+export interface CommentDeletePayload {
+    projectName: string;
+    feedbackId: string;
+    commentId: string;
+}
 /**
  * Thrown when a record is not found during update or delete.
  *
@@ -677,24 +824,41 @@ export declare class StorePersistenceError extends Error {
     readonly code: "STORE_PERSISTENCE";
     constructor(message?: string, options?: ErrorOptions);
 }
+/**
+ * Thrown when a write would break a bound of the store contract — a
+ * `client` comment on a thread already holding `MAX_COMMENTS_PER_FEEDBACK`
+ * of them. Handlers translate this to HTTP 409.
+ */
+export declare class StoreLimitError extends Error {
+    readonly code: "STORE_LIMIT";
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a value is longer than the store can hold, though the HTTP
+ * validation accepts it — on MySQL, Prisma maps a plain `String` to
+ * `VARCHAR(191)`. Handlers translate this to HTTP 422: the submission can
+ * never be stored as it is, so a client must not retry it.
+ */
+export declare class StoreValueTooLongError extends Error {
+    readonly code: "STORE_VALUE_TOO_LONG";
+    constructor(message?: string, options?: ErrorOptions);
+}
 /** Shape of any ORM error that carries a Prisma-style `code` field. */
 type CodedError<C extends string = string> = {
     code: C;
 };
 /**
  * Type guard — works for `StoreNotFoundError` and ORM-specific equivalents
- * (e.g. Prisma P2025). Matches the stable `STORE_NOT_FOUND` code as well as
- * `instanceof`: every consumer package bundles its own copy of core (tsup
- * `noExternal`), so an adapter's instance fails `instanceof` against the
- * server's class identity.
+ * (e.g. Prisma P2025). Matches on the stable `code` too, for the same
+ * cross-bundle reason as {@link isStorePersistence}.
  */
-export declare function isStoreNotFound(error: unknown): error is StoreNotFoundError | CodedError<"STORE_NOT_FOUND"> | CodedError<"P2025">;
+export declare function isStoreNotFound(error: unknown): error is StoreNotFoundError | CodedError<"STORE_NOT_FOUND" | "P2025">;
 /**
  * Type guard — works for `StoreDuplicateError` and ORM-specific equivalents
- * (e.g. Prisma P2002). Matches the stable `STORE_DUPLICATE` code as well as
- * `instanceof`, for the same cross-bundle reason as {@link isStoreNotFound}.
+ * (e.g. Prisma P2002). Matches on the stable `code` too, for the same
+ * cross-bundle reason as {@link isStorePersistence}.
  */
-export declare function isStoreDuplicate(error: unknown): error is StoreDuplicateError | CodedError<"STORE_DUPLICATE"> | CodedError<"P2002">;
+export declare function isStoreDuplicate(error: unknown): error is StoreDuplicateError | CodedError<"STORE_DUPLICATE" | "P2002">;
 /**
  * Type guard for `StorePersistenceError`. Matches on the stable `code` field
  * in addition to `instanceof`: every consumer package bundles its own copy of
@@ -702,10 +866,14 @@ export declare function isStoreDuplicate(error: unknown): error is StoreDuplicat
  * `instanceof` check against another package's class identity.
  */
 export declare function isStorePersistence(error: unknown): error is StorePersistenceError | CodedError<"STORE_PERSISTENCE">;
+/** Type guard for `StoreLimitError`, matching on `code` for the same cross-bundle reason as {@link isStorePersistence}. */
+export declare function isStoreLimit(error: unknown): error is StoreLimitError | CodedError<"STORE_LIMIT">;
+/** Type guard for `StoreValueTooLongError`, matching on `code` for the same cross-bundle reason as {@link isStorePersistence}. */
+export declare function isStoreValueTooLong(error: unknown): error is StoreValueTooLongError | CodedError<"STORE_VALUE_TOO_LONG">;
 /** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */
 export declare function flattenAnnotation(ann: AnnotationPayload): AnnotationCreateInput;
 /**
- * Outcome of `SitepingStore.createFeedbackIfAbsent` — the record plus whether
+ * Outcome of `BeezpingStore.createFeedbackIfAbsent` — the record plus whether
  * this very call inserted it.
  */
 export interface FeedbackCreateOutcome {
@@ -717,17 +885,17 @@ export interface FeedbackCreateOutcome {
      */
     created: boolean;
 }
-/** Paginated result returned by `SitepingStore.getFeedbacks`. */
+/** Paginated result returned by `BeezpingStore.getFeedbacks`. */
 export interface FeedbackPage {
     feedbacks: FeedbackRecord[];
     total: number;
 }
 /**
- * Abstract storage interface for Siteping.
+ * Abstract storage interface for Beezping.
  *
  * Any adapter (Prisma, Drizzle, raw SQL, localStorage, etc.) implements this
  * interface. The HTTP handler and widget `StoreClient` operate against
- * `SitepingStore`, decoupled from the storage backend.
+ * `BeezpingStore`, decoupled from the storage backend.
  *
  * ## Error contract
  *
@@ -744,7 +912,7 @@ export interface FeedbackPage {
  *   a phantom success. Detect it with `isStorePersistence`.
  * - Other methods should not throw on empty results — return empty arrays or `null`.
  */
-export interface SitepingStore {
+export interface BeezpingStore {
     /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. Throws `StorePersistenceError` when the write cannot be persisted. */
     createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
     /** Paginated query with optional filters. Returns empty array (not error) when no results. */
@@ -762,10 +930,8 @@ export interface SitepingStore {
      * `projectName`, `false` otherwise (including when it does not exist).
      *
      * HTTP handlers use this to reject cross-project PATCH/DELETE requests.
-     * Implement it whenever your store serves multiple projects. When absent,
-     * handlers rely on `id` alone — so `createSitepingHandler` refuses to start
-     * with a custom `access.authorize` (which may scope callers to projects)
-     * over a store that lacks it.
+     * Implement it whenever your store serves multiple projects; when absent,
+     * handlers skip the ownership check and rely on `id` alone.
      */
     verifyProjectOwnership?(id: string, projectName: string): Promise<boolean>;
     /**
@@ -780,12 +946,39 @@ export interface SitepingStore {
      * transaction, compare-and-set).
      *
      * HTTP handlers prefer it over `createFeedback` to fire creation side
-     * effects (webhooks, `onCreated`) exactly once when concurrent requests
-     * race on the same `clientId`. Stores whose `createFeedback` throws
+     * effects (webhooks) exactly once when concurrent requests race on the
+     * same `clientId`. Stores whose `createFeedback` throws
      * `StoreDuplicateError` on a duplicate already give that signal and may
      * leave it out.
      */
     createFeedbackIfAbsent?(data: FeedbackCreateInput): Promise<FeedbackCreateOutcome>;
+    /**
+     * Optional — append a comment to the thread of feedback `feedbackId` and
+     * return it. Idempotent on `data.clientId`: when a comment with that
+     * `clientId` exists, on any thread, return it unchanged (HTTP handlers
+     * refuse a replay aimed at another thread).
+     *
+     * Throws `StoreNotFoundError` when the feedback does not exist,
+     * `StoreLimitError` when a `client` comment meets a thread already holding
+     * `MAX_COMMENTS_PER_FEEDBACK` of them (a `team` comment is never refused
+     * for it), `StorePersistenceError` when the
+     * write cannot be persisted. A comment is not a change of the feedback
+     * itself: its `updatedAt` stays as it was.
+     *
+     * A store that implements it returns every feedback's thread on
+     * `FeedbackRecord.comments`, oldest first, and deletes a thread with its
+     * feedback. A store without it (and `deleteComment`) has no threads:
+     * HTTP handlers serve empty threads and answer comment writes with 501.
+     */
+    addComment?(feedbackId: string, data: CommentCreateInput): Promise<CommentRecord>;
+    /**
+     * Optional — delete comment `commentId` from the thread of `feedbackId`.
+     * Scoped to that thread, which the caller was authorized for: throws
+     * `StoreNotFoundError` when the feedback does not exist or the comment is
+     * not on its thread, `StorePersistenceError` when the write cannot be
+     * persisted.
+     */
+    deleteComment?(feedbackId: string, commentId: string): Promise<void>;
 }
 /** Payload sent from the widget to the server when submitting feedback. */
 export interface FeedbackPayload {
@@ -795,7 +988,7 @@ export interface FeedbackPayload {
     url: string;
     /**
      * Parameterized URL template (e.g. `/orders/:orderId`) supplied by
-     * `SitepingConfig.getPageScope()`. Null when the host did not provide one.
+     * `BeezpingConfig.getPageScope()`. Null when the host did not provide one.
      */
     urlPattern?: string | null | undefined;
     viewport: string;
@@ -807,7 +1000,7 @@ export interface FeedbackPayload {
     clientId: string;
     /**
      * Base64 JPEG `data:` URL of the annotated area. Captured by the widget
-     * when `enableScreenshot: true` is set in `SitepingConfig`. Null when
+     * when `enableScreenshot: true` is set in `BeezpingConfig`. Null when
      * disabled or when capture failed silently.
      */
     screenshotDataUrl?: string | null | undefined;
@@ -857,11 +1050,26 @@ export interface DiagnosticsSnapshot {
     console: ConsoleDiagnosticEntry[];
     network: NetworkDiagnosticEntry[];
 }
+/**
+ * Length caps for `AnchorData.elementTag` / `elementId`, shared by the widget
+ * (which bounds what it captures) and the HTTP adapter (which rejects a longer
+ * tag and drops a longer id) so the two can't drift. 191 fits Prisma's default `String` column
+ * on MySQL (`VARCHAR(191)`); real tag names and ids are far shorter.
+ */
+export declare const ANCHOR_ELEMENT_TAG_MAX = 191;
+export declare const ANCHOR_ELEMENT_ID_MAX = 191;
 /** DOM anchoring data for re-attaching annotations to page elements. */
 export interface AnchorData {
-    /** CSS selector generated by @medv/finder — primary anchor */
+    /**
+     * CSS selector generated by @medv/finder — primary anchor. Inside open
+     * shadow roots: one selector per tree, outermost host first, joined by
+     * `" >>> "` (e.g. `"#pricing >>> .plan-title"`).
+     */
     cssSelector: string;
-    /** XPath — fallback 1 */
+    /**
+     * XPath — fallback 1. Inside a shadow root it is relative to that root
+     * (`./…`) and informational only: XPath cannot enter shadow trees.
+     */
     xpath: string;
     /** First ~120 chars of element innerText — empty string if none */
     textSnippet: string;
@@ -926,22 +1134,73 @@ export interface AnnotationPayload {
 /**
  * Feedback record as returned by the API — derived from
  * {@link FeedbackRecord}: dates are serialized to ISO strings and `clientId`
- * is omitted (server-side dedup concern, never exposed on the wire). Adding
- * a field to `FeedbackRecord` updates this type automatically.
+ * is omitted (server-side dedup concern, never exposed on the wire), on the
+ * record and on each comment of its thread. Adding a field to
+ * `FeedbackRecord` updates this type automatically.
  *
  * Note: `authorEmail` may be an empty string — HTTP adapters redact it for
  * unauthenticated requests; the full value requires a Bearer-authenticated
  * request.
  */
-export type FeedbackResponse = Prettify<Serialized<Omit<FeedbackRecord, "clientId">>>;
+export type FeedbackResponse = Prettify<Serialized<Omit<FeedbackRecord, "clientId" | "comments">> & {
+    /** The thread, oldest first — always sent by `@beezping/server`, absent from servers that predate comments. */
+    comments?: CommentResponse[] | undefined;
+    /**
+     * What the requester may do with this feedback — always sent by
+     * `@beezping/server`. Absent from servers that predate it, and in store
+     * mode: nothing is refused then.
+     */
+    permissions?: FeedbackPermissions | undefined;
+}>;
+/**
+ * What a requester may do with one feedback, as the server's access policy
+ * decides — so clients hide the actions it would refuse. The server still
+ * enforces every one of them.
+ */
+export interface FeedbackPermissions {
+    /** Change its status: resolve, reopen, … */
+    canChangeStatus: boolean;
+    /** Delete it. */
+    canDelete: boolean;
+    /** Reply in its thread. */
+    canComment: boolean;
+    /** Delete replies from its thread. */
+    canDeleteComment: boolean;
+}
+/** What a requester may do with a whole project, sent with each list. */
+export interface FeedbackListPermissions {
+    /** Delete every feedback of the project at once. */
+    canDeleteAll: boolean;
+}
 /**
  * Annotation record as returned by the API — {@link AnnotationRecord} with
  * `createdAt` serialized to an ISO string.
  */
 export type AnnotationResponse = Prettify<Serialized<AnnotationRecord>>;
+/**
+ * Comment as returned by the API — {@link CommentRecord} with `createdAt`
+ * serialized and `clientId` omitted, like on `FeedbackResponse`. Its
+ * `authorEmail` is redacted on the same terms as the feedback's.
+ */
+export type CommentResponse = Prettify<Serialized<Omit<CommentRecord, "clientId">>>;
+/** What the store behind an endpoint supports — advertised on every list response. */
+export interface BeezpingCapabilities {
+    /** Whether comments can be posted: the store implements `addComment`. */
+    comments: boolean;
+    /**
+     * Whether comments can be deleted: the store implements `deleteComment`.
+     * Sent by `@beezping/server`; a client that does not delete (the widget)
+     * leaves it out.
+     */
+    deleteComments?: boolean | undefined;
+}
 /** Paginated `FeedbackResponse` shape returned by the API. */
 export interface FeedbackResponseList {
     feedbacks: FeedbackResponse[];
     total: number;
+    /** Always sent by `@beezping/server` — absent from servers that predate it. */
+    capabilities?: BeezpingCapabilities | undefined;
+    /** Always sent by `@beezping/server` — absent from servers that predate it. */
+    permissions?: FeedbackListPermissions | undefined;
 }
 export {};