@siteping/widget 0.10.9 → 0.11.0

package/dist/types.d.ts

@@ -1,10 +1,10 @@
-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";
 /** Visual theme — `auto` resolves to `light` or `dark` via system preference. */
 export type SitepingTheme = "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
@@ -14,14 +14,17 @@ export type BuiltinLocale = (typeof BUILTIN_LOCALES)[number];
 export type SitepingLocale = BuiltinLocale | (string & {});
 /**
  * Reasons reported through `SitepingConfig.onSkip` — production environment,
- * mobile viewport, or server-side rendering (no `window`/`document`).
+ * viewport narrower than `minViewportWidth` (`"mobile"`), or server-side
+ * rendering (no `window`/`document`).
  */
 export type SitepingSkipReason = "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. */
@@ -29,11 +32,104 @@ export interface SitepingIdentity {
     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"`. */
     param?: string | undefined;
 }
+/**
+ * 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 SitepingPanelActionFeedback = DeepReadonly<FeedbackResponse>;
+/**
+ * Helpers passed to a panel action's `onAction` as its second argument.
+ * Both do nothing once the widget has been destroyed.
+ */
+export interface SitepingPanelActionContext {
+    /**
+     * 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 SitepingPanelAction}.
+ *
+ * Do not use this type directly — use {@link SitepingPanelAction}.
+ */
+export interface SitepingPanelActionBase {
+    /** 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: SitepingPanelActionFeedback) => boolean) | undefined;
+}
+/** A panel action rendered as a button that runs host code. */
+export interface SitepingPanelButtonAction extends SitepingPanelActionBase {
+    /**
+     * 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: SitepingPanelActionFeedback, context: SitepingPanelActionContext) => 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 SitepingPanelLinkAction extends SitepingPanelActionBase {
+    /**
+     * 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: SitepingPanelActionFeedback) => string);
+    /** Not available on a link action — use either `onAction` or `href`, never both. */
+    onAction?: never;
+}
+/**
+ * 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.
+ *
+ * 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 type SitepingPanelAction = SitepingPanelButtonAction | SitepingPanelLinkAction;
 /**
  * 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
@@ -69,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,
@@ -78,17 +174,19 @@ 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. */
+    /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru, ja. Any other string falls back to English. */
     locale?: SitepingLocale | undefined;
     /**
      * Returns the current page scope for annotations and panel filtering.
@@ -139,7 +237,8 @@ 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
@@ -148,9 +247,11 @@ export interface SitepingBaseConfig {
      * Right-clicks on SitePing'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;
     /**
@@ -163,15 +264,18 @@ 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) */
+    /** Called when the widget is skipped (production mode, viewport under `minViewportWidth`, SSR — no DOM) */
     onSkip?: (reason: SitepingSkipReason) => void;
     /**
      * Auto-focus a specific annotation when its ID appears in the URL query
@@ -239,12 +343,30 @@ export interface SitepingBaseConfig {
      * future enhancement that propagates identity updates without a remount.
      */
     identity?: SitepingIdentity | 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 SitepingPanelAction}.
+     */
+    panelActions?: readonly SitepingPanelAction[] | 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.
      *
@@ -252,9 +374,16 @@ export interface SitepingBaseConfig {
      * `SitepingNetworkError`, `SitepingValidationError`, `SitepingAuthError`)
      * 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. */
@@ -283,9 +412,10 @@ 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.
+     * 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?: SitepingHeadersOption | undefined;
     /** Not available in HTTP mode — use either `endpoint` or `store`, never both. */
@@ -296,7 +426,11 @@ export interface SitepingHttpConfig extends SitepingBaseConfig {
  * browser, no server needed (demos, prototypes, localStorage persistence).
  */
 export interface SitepingStoreConfig extends SitepingBaseConfig {
-    /** Direct store for client-side mode. Bypasses HTTP entirely. */
+    /**
+     * 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: SitepingStore;
     /** Not available in store mode — use either `endpoint` or `store`, never both. */
     endpoint?: never;
@@ -348,6 +482,8 @@ export type SitepingUnsubscribe = () => void;
 export interface SitepingPublicEvents {
     "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,
@@ -482,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
@@ -540,6 +681,13 @@ export interface FeedbackRecord {
     createdAt: Date;
     updatedAt: Date;
     annotations: AnnotationRecord[];
+    /**
+     * Discussion thread, oldest first. A store that implements
+     * `SitepingStore.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
@@ -587,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 `SitepingStore.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.
  *
@@ -616,14 +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). */
-export declare function isStoreNotFound(error: unknown): error is StoreNotFoundError | CodedError<"P2025">;
-/** Type guard — works for `StoreDuplicateError` and ORM-specific equivalents (e.g. Prisma P2002). */
-export declare function isStoreDuplicate(error: unknown): error is StoreDuplicateError | CodedError<"P2002">;
+/**
+ * Type guard — works for `StoreNotFoundError` and ORM-specific equivalents
+ * (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" | "P2025">;
+/**
+ * Type guard — works for `StoreDuplicateError` and ORM-specific equivalents
+ * (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" | "P2002">;
 /**
  * Type guard for `StorePersistenceError`. Matches on the stable `code` field
  * in addition to `instanceof`: every consumer package bundles its own copy of
@@ -631,8 +866,25 @@ 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
+ * this very call inserted it.
+ */
+export interface FeedbackCreateOutcome {
+    feedback: FeedbackRecord;
+    /**
+     * `true` when this call inserted the record, `false` when a record with the
+     * same `clientId` already existed and is returned instead (a replay, or a
+     * concurrent request that won the race).
+     */
+    created: boolean;
+}
 /** Paginated result returned by `SitepingStore.getFeedbacks`. */
 export interface FeedbackPage {
     feedbacks: FeedbackRecord[];
@@ -651,7 +903,10 @@ export interface FeedbackPage {
  *   the record does not exist.
  * - **`createFeedback`**: either return the existing record on duplicate
  *   `clientId` (idempotent) or throw `StoreDuplicateError`. The handler
- *   handles both patterns.
+ *   handles both patterns — but only a throw, or the optional
+ *   `createFeedbackIfAbsent`, tells it the record was not inserted by this
+ *   call; stores that return the existing record should implement
+ *   `createFeedbackIfAbsent` so creation side effects never run twice.
  * - **All mutations**: when a write is accepted but cannot be persisted
  *   (e.g. storage quota), throw `StorePersistenceError` instead of reporting
  *   a phantom success. Detect it with `isStorePersistence`.
@@ -679,6 +934,51 @@ export interface SitepingStore {
      * handlers skip the ownership check and rely on `id` alone.
      */
     verifyProjectOwnership?(id: string, projectName: string): Promise<boolean>;
+    /**
+     * Optional — `createFeedback` that reports whether this call inserted the
+     * record (`created: true`) or found an existing one with the same
+     * `clientId` (`created: false`). The dedup check and the insert must be
+     * atomic, like `createFeedback`'s: of N concurrent calls with the same
+     * `clientId`, exactly one may report `created: true`, and all must return
+     * that same record. `createCollectionStore` guarantees this within one
+     * store instance by serializing its mutations; stores shared across
+     * processes need an atomic backend primitive (unique constraint,
+     * transaction, compare-and-set).
+     *
+     * HTTP handlers prefer it over `createFeedback` to fire creation side
+     * 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 {
@@ -750,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;
@@ -819,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 `@siteping/server`, absent from servers that predate comments. */
+    comments?: CommentResponse[] | undefined;
+    /**
+     * What the requester may do with this feedback — always sent by
+     * `@siteping/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 SitepingCapabilities {
+    /** Whether comments can be posted: the store implements `addComment`. */
+    comments: boolean;
+    /**
+     * Whether comments can be deleted: the store implements `deleteComment`.
+     * Sent by `@siteping/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 `@siteping/server` — absent from servers that predate it. */
+    capabilities?: SitepingCapabilities | undefined;
+    /** Always sent by `@siteping/server` — absent from servers that predate it. */
+    permissions?: FeedbackListPermissions | undefined;
 }
 export {};