@siteping/adapter-kit 0.1.0

package/dist/index.cjs

@@ -0,0 +1,256 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CLOSED_FEEDBACK_STATUSES: () => CLOSED_FEEDBACK_STATUSES,
+  CONSOLE_DIAGNOSTIC_LEVELS: () => CONSOLE_DIAGNOSTIC_LEVELS,
+  FEEDBACK_STATUSES: () => FEEDBACK_STATUSES,
+  FEEDBACK_TYPES: () => FEEDBACK_TYPES,
+  OPEN_FEEDBACK_STATUSES: () => OPEN_FEEDBACK_STATUSES,
+  StoreDuplicateError: () => StoreDuplicateError,
+  StoreNotFoundError: () => StoreNotFoundError,
+  StorePersistenceError: () => StorePersistenceError,
+  applyFeedbackFilters: () => applyFeedbackFilters,
+  buildAnnotationRecord: () => buildAnnotationRecord,
+  buildFeedbackRecord: () => buildFeedbackRecord,
+  createCollectionStore: () => createCollectionStore,
+  flattenAnnotation: () => flattenAnnotation,
+  isClosedStatus: () => isClosedStatus,
+  isStoreDuplicate: () => isStoreDuplicate,
+  isStoreNotFound: () => isStoreNotFound,
+  isStorePersistence: () => isStorePersistence,
+  toFeedbackUpdate: () => toFeedbackUpdate
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../core/src/filters.ts
+var DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 100;
+function applyFeedbackFilters(items, query) {
+  let results = items.filter((f) => f.projectName === query.projectName);
+  if (query.type) results = results.filter((f) => f.type === query.type);
+  if (query.statuses && query.statuses.length > 0) {
+    const allowed = query.statuses;
+    results = results.filter((f) => allowed.includes(f.status));
+  } else if (query.status) {
+    results = results.filter((f) => f.status === query.status);
+  }
+  if (query.url) results = results.filter((f) => f.url === query.url);
+  if (query.urlPattern) results = results.filter((f) => f.urlPattern === query.urlPattern);
+  if (query.search) {
+    const s = query.search.toLowerCase();
+    results = results.filter((f) => f.message.toLowerCase().includes(s));
+  }
+  results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+  const total = results.length;
+  const page = Math.max(1, query.page ?? 1);
+  const limit = Math.max(1, Math.min(query.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
+  const start = (page - 1) * limit;
+  return { feedbacks: results.slice(start, start + limit), total };
+}
+
+// ../core/src/type-utils.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasOwn(value, key) {
+  return isRecord(value) && key in value;
+}
+
+// ../core/src/types.ts
+var FEEDBACK_TYPES = ["question", "change", "bug", "other"];
+var FEEDBACK_STATUSES = ["open", "in_progress", "resolved", "wont_fix"];
+var CLOSED_FEEDBACK_STATUSES = ["resolved", "wont_fix"];
+var OPEN_FEEDBACK_STATUSES = ["open", "in_progress"];
+function isClosedStatus(status) {
+  return CLOSED_FEEDBACK_STATUSES.includes(status);
+}
+function toFeedbackUpdate(status, closedAt = /* @__PURE__ */ new Date()) {
+  return isClosedStatus(status) ? { status, resolvedAt: closedAt } : { status, resolvedAt: null };
+}
+var StoreNotFoundError = class extends Error {
+  code = "STORE_NOT_FOUND";
+  constructor(message = "Record not found") {
+    super(message);
+    this.name = "StoreNotFoundError";
+  }
+};
+var StoreDuplicateError = class extends Error {
+  code = "STORE_DUPLICATE";
+  constructor(message = "Duplicate record") {
+    super(message);
+    this.name = "StoreDuplicateError";
+  }
+};
+var StorePersistenceError = class extends Error {
+  code = "STORE_PERSISTENCE";
+  constructor(message = "Failed to persist store mutation", options) {
+    super(message, options);
+    this.name = "StorePersistenceError";
+  }
+};
+function hasErrorCode(error, code) {
+  return hasOwn(error, "code") && error.code === code;
+}
+function isStoreNotFound(error) {
+  if (error instanceof StoreNotFoundError) return true;
+  return hasErrorCode(error, "P2025");
+}
+function isStoreDuplicate(error) {
+  if (error instanceof StoreDuplicateError) return true;
+  return hasErrorCode(error, "P2002");
+}
+function isStorePersistence(error) {
+  if (error instanceof StorePersistenceError) return true;
+  return hasErrorCode(error, "STORE_PERSISTENCE");
+}
+function flattenAnnotation(ann) {
+  return {
+    cssSelector: ann.anchor.cssSelector,
+    xpath: ann.anchor.xpath,
+    textSnippet: ann.anchor.textSnippet,
+    elementTag: ann.anchor.elementTag,
+    elementId: ann.anchor.elementId,
+    textPrefix: ann.anchor.textPrefix,
+    textSuffix: ann.anchor.textSuffix,
+    fingerprint: ann.anchor.fingerprint,
+    neighborText: ann.anchor.neighborText,
+    anchorKey: ann.anchor.anchorKey ?? null,
+    xPct: ann.rect.xPct,
+    yPct: ann.rect.yPct,
+    wPct: ann.rect.wPct,
+    hPct: ann.rect.hPct,
+    scrollX: ann.scrollX,
+    scrollY: ann.scrollY,
+    viewportW: ann.viewportW,
+    viewportH: ann.viewportH,
+    devicePixelRatio: ann.devicePixelRatio
+  };
+}
+var CONSOLE_DIAGNOSTIC_LEVELS = ["log", "info", "warn", "error"];
+
+// ../core/src/store-helpers.ts
+function buildAnnotationRecord(input, ctx) {
+  return {
+    id: ctx.id,
+    feedbackId: ctx.feedbackId,
+    cssSelector: input.cssSelector,
+    xpath: input.xpath,
+    textSnippet: input.textSnippet,
+    elementTag: input.elementTag,
+    elementId: input.elementId ?? null,
+    textPrefix: input.textPrefix,
+    textSuffix: input.textSuffix,
+    fingerprint: input.fingerprint,
+    neighborText: input.neighborText,
+    anchorKey: input.anchorKey ?? null,
+    xPct: input.xPct,
+    yPct: input.yPct,
+    wPct: input.wPct,
+    hPct: input.hPct,
+    scrollX: input.scrollX,
+    scrollY: input.scrollY,
+    viewportW: input.viewportW,
+    viewportH: input.viewportH,
+    devicePixelRatio: input.devicePixelRatio,
+    createdAt: ctx.now
+  };
+}
+function buildFeedbackRecord(input, ctx) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  return {
+    id: ctx.id,
+    type: input.type,
+    message: input.message,
+    status: input.status,
+    projectName: input.projectName,
+    url: input.url,
+    urlPattern: input.urlPattern ?? null,
+    authorName: input.authorName,
+    authorEmail: input.authorEmail,
+    viewport: input.viewport,
+    userAgent: input.userAgent,
+    clientId: input.clientId,
+    resolvedAt: null,
+    createdAt: now,
+    updatedAt: now,
+    annotations: input.annotations.map(
+      (ann) => buildAnnotationRecord(ann, { id: ctx.annotationId(), feedbackId: ctx.id, now })
+    ),
+    screenshotUrl: input.screenshotDataUrl ?? null,
+    screenshotRegion: input.screenshotRegion ?? null,
+    diagnostics: input.diagnostics ?? null
+  };
+}
+function createCollectionStore(backend) {
+  return {
+    async createFeedback(data) {
+      const feedbacks = await backend.load();
+      const existing = feedbacks.find((f) => f.clientId === data.clientId);
+      if (existing) return existing;
+      const record = buildFeedbackRecord(data, {
+        id: backend.generateId(),
+        annotationId: () => backend.generateId()
+      });
+      feedbacks.unshift(record);
+      try {
+        await backend.persist(feedbacks);
+      } catch (err) {
+        if (!record.screenshotUrl) throw err;
+        record.screenshotUrl = null;
+        await backend.persist(feedbacks);
+      }
+      return record;
+    },
+    async getFeedbacks(query) {
+      return applyFeedbackFilters(await backend.load(), query);
+    },
+    async findByClientId(clientId) {
+      return (await backend.load()).find((f) => f.clientId === clientId) ?? null;
+    },
+    async updateFeedback(id, data) {
+      const feedbacks = await backend.load();
+      const fb = feedbacks.find((f) => f.id === id);
+      if (!fb) throw new StoreNotFoundError();
+      fb.status = data.status;
+      fb.resolvedAt = data.resolvedAt;
+      fb.updatedAt = /* @__PURE__ */ new Date();
+      await backend.persist(feedbacks);
+      return fb;
+    },
+    async deleteFeedback(id) {
+      const feedbacks = await backend.load();
+      const idx = feedbacks.findIndex((f) => f.id === id);
+      if (idx === -1) throw new StoreNotFoundError();
+      feedbacks.splice(idx, 1);
+      await backend.persist(feedbacks);
+    },
+    async deleteAllFeedbacks(projectName) {
+      const feedbacks = await backend.load();
+      await backend.persist(feedbacks.filter((f) => f.projectName !== projectName));
+    },
+    async verifyProjectOwnership(id, projectName) {
+      const fb = (await backend.load()).find((f) => f.id === id);
+      return fb !== void 0 && fb.projectName === projectName;
+    }
+  };
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../../core/src/filters.ts","../../core/src/type-utils.ts","../../core/src/types.ts","../../core/src/store-helpers.ts"],"sourcesContent":["/**\n * Everything needed to build a custom Siteping store adapter, published —\n * `@siteping/core` is an internal (unpublished) package, so this kit is the\n * supported dependency for third-party adapters.\n *\n * Two ways to implement a store:\n *\n * 1. **Snapshot backends** (KV, flat file, IndexedDB, …): hand\n *    {@link createCollectionStore} a `load`/`persist`/`generateId` trio and\n *    every store semantic (clientId dedup, filtering, pagination, error\n *    contract) comes built-in — an adapter is ~20 lines plus its storage\n *    specifics.\n * 2. **Query backends** (SQL, ORMs): implement {@link SitepingStore}\n *    directly; {@link buildFeedbackRecord} / {@link buildAnnotationRecord}\n *    handle input→record construction, and the JSDoc on `SitepingStore`\n *    documents the exact error contract.\n *\n * Either way, verify with the conformance suite from\n * `@siteping/adapter-kit/testing`:\n *\n * @example\n * ```ts\n * import { testSitepingStore } from \"@siteping/adapter-kit/testing\";\n * import { MyStore } from \"../src/index.js\";\n *\n * testSitepingStore(() => new MyStore());\n * ```\n */\n\n// The store contract and its data model\n// Building blocks — record construction, the shared filter pipeline, and\n// the full collection-store engine\nexport type {\n  AnchorData,\n  AnnotationCreateInput,\n  AnnotationPayload,\n  AnnotationRecord,\n  AnnotationResponse,\n  ClosedFeedbackStatus,\n  CollectionStore,\n  CollectionStoreBackend,\n  ConsoleDiagnosticEntry,\n  ConsoleDiagnosticLevel,\n  DiagnosticsSnapshot,\n  FeedbackCreateInput,\n  FeedbackPage,\n  FeedbackPayload,\n  FeedbackQuery,\n  FeedbackRecord,\n  FeedbackResponse,\n  FeedbackResponseList,\n  FeedbackStatus,\n  FeedbackType,\n  FeedbackUpdateInput,\n  FilterResult,\n  NetworkDiagnosticEntry,\n  OpenFeedbackStatus,\n  RectData,\n  ScreenshotRegion,\n  ScreenshotStorage,\n  Serialized,\n  SitepingStore,\n} from \"@siteping/core\";\n// Status/type constants + helpers\n// Store errors — throw these from adapter implementations\nexport {\n  applyFeedbackFilters,\n  buildAnnotationRecord,\n  buildFeedbackRecord,\n  CLOSED_FEEDBACK_STATUSES,\n  CONSOLE_DIAGNOSTIC_LEVELS,\n  createCollectionStore,\n  FEEDBACK_STATUSES,\n  FEEDBACK_TYPES,\n  flattenAnnotation,\n  isClosedStatus,\n  isStoreDuplicate,\n  isStoreNotFound,\n  isStorePersistence,\n  OPEN_FEEDBACK_STATUSES,\n  StoreDuplicateError,\n  StoreNotFoundError,\n  StorePersistenceError,\n  toFeedbackUpdate,\n} from \"@siteping/core\";\n","/**\n * Shared feedback-record filtering and pagination — extracted from\n * `adapter-memory` and `adapter-localstorage` which previously kept two\n * near-identical copies of the same logic. Any adapter that holds an\n * in-memory snapshot of feedbacks can use it.\n *\n * Filtering order matches the historical adapter behaviour:\n *   1. projectName  (always required)\n *   2. type\n *   3. status / statuses  (`statuses` bucket wins when both are set)\n *   4. url\n *   5. urlPattern\n *   6. search       (lowercase substring match on `message`)\n *\n * Pagination clamps `limit` to a maximum of 100 and treats `page` as 1-based,\n * matching the public API contract documented on `getFeedbacks`. A page or\n * limit below 1 is clamped up to 1 rather than indexing backwards from the\n * end of the match set.\n */\n\nimport type { FeedbackQuery, FeedbackRecord } from \"./types.js\";\n\n/** Default page size when the caller omits `query.limit`. */\nconst DEFAULT_LIMIT = 50;\n/** Maximum allowed page size — defends against memory blow-ups on hostile callers. */\nconst MAX_LIMIT = 100;\n\nexport interface FilterResult {\n  feedbacks: FeedbackRecord[];\n  total: number;\n}\n\n/**\n * Apply the standard feedback filter + pagination pipeline against an\n * in-memory snapshot. Used by `MemoryStore.getFeedbacks` and\n * `LocalStorageStore.getFeedbacks` so the two never drift.\n *\n * @param items  All known feedback records (already include `annotations`).\n * @param query  Filter and pagination options. `projectName` is required.\n */\nexport function applyFeedbackFilters(items: readonly FeedbackRecord[], query: FeedbackQuery): FilterResult {\n  let results: FeedbackRecord[] = items.filter((f) => f.projectName === query.projectName);\n\n  if (query.type) results = results.filter((f) => f.type === query.type);\n  // `statuses` (bucket / any-of) wins over the exact `status` filter when both\n  // are present; an empty array is treated as absent.\n  if (query.statuses && query.statuses.length > 0) {\n    const allowed = query.statuses;\n    results = results.filter((f) => allowed.includes(f.status));\n  } else if (query.status) {\n    results = results.filter((f) => f.status === query.status);\n  }\n  if (query.url) results = results.filter((f) => f.url === query.url);\n  if (query.urlPattern) results = results.filter((f) => f.urlPattern === query.urlPattern);\n  if (query.search) {\n    const s = query.search.toLowerCase();\n    results = results.filter((f) => f.message.toLowerCase().includes(s));\n  }\n\n  // Newest first is part of the store contract (PrismaStore orders by\n  // createdAt desc) — sort explicitly instead of relying on insertion order.\n  // Array.prototype.sort is stable, so same-millisecond records keep their\n  // insertion order (newest inserted first).\n  results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());\n\n  const total = results.length;\n  // Both bounds are clamped from below, not just `limit` from above:\n  // `(page - 1) * limit` goes negative for a non-positive page or limit, and\n  // `slice` reads negative indices from the END — so `page: -1` returned a\n  // window whose position depended on how many records happened to match,\n  // rather than an empty page or the first one. The Prisma adapter rejects\n  // these at the HTTP edge (`z.coerce.number().int().min(1)`), but the\n  // in-memory adapters have no schema in front of them and call straight in.\n  const page = Math.max(1, query.page ?? 1);\n  const limit = Math.max(1, Math.min(query.limit ?? DEFAULT_LIMIT, MAX_LIMIT));\n  const start = (page - 1) * limit;\n\n  return { feedbacks: results.slice(start, start + limit), total };\n}\n","/**\n * General-purpose TypeScript utility types used across `@siteping/*`.\n *\n * These are kept dependency-free and re-exported from the package entry\n * so adapters and integrators can rely on the same primitives the core\n * uses internally.\n */\n\n/**\n * Force TypeScript to expand a computed type into a flat object literal in\n * tooltips and error messages. Purely cosmetic — same structural type, just\n * easier to read.\n *\n * @example\n *   type Raw = Omit<FeedbackRecord, \"annotations\"> & { annotations: number };\n *   type Pretty = Prettify<Raw>; // displayed as a flat object\n */\nexport type Prettify<T> = { [K in keyof T]: T[K] } & {};\n\n/**\n * Returns `Y` when `A` is exactly assignable to `B` and vice-versa,\n * otherwise `N`. Powers compile-time equality assertions.\n */\nexport type IfEquals<A, B, Y = true, N = false> =\n  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? Y : N;\n\n/**\n * Compile-time exact-type guard — resolves to `true` when `Actual` and\n * `Expected` are identical, `never` otherwise. Assign the result to a\n * `const _lock: AssertEqual<A, B> = true;` so any drift becomes a compile\n * error at the declaration site.\n */\nexport type AssertEqual<Actual, Expected> = IfEquals<Actual, Expected, true, never>;\n\n/**\n * JSON-serialized shape of `T` — the wire form produced by `Response.json()`\n * / `JSON.stringify`: `Date` becomes ISO `string` (nullability preserved),\n * arrays are serialized element-wise, everything else is untouched.\n *\n * Used to derive the `*Response` API types from the `*Record` store types so\n * the two can never drift: add a field to `FeedbackRecord` and\n * `FeedbackResponse` follows automatically.\n */\nexport type Serialized<T> = {\n  [K in keyof T]: T[K] extends Date\n    ? string\n    : T[K] extends Date | null\n      ? string | null\n      : T[K] extends (infer U)[]\n        ? Serialized<U>[]\n        : T[K];\n};\n\n/**\n * Type guard that narrows `value` to a non-null `Record<PropertyKey, unknown>`.\n * Useful when validating arbitrary inputs before reading fields.\n */\nexport function isRecord(value: unknown): value is Record<PropertyKey, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\n/**\n * Returns true when `value` is an object that exposes the requested key.\n * Type-narrows `value` so the property can be accessed without further\n * casting — a strictly typed replacement for `\"k\" in obj`.\n *\n * Named after the standardised `Object.hasOwn` helper rather than the\n * legacy `Object.prototype.hasOwnProperty`, which the linter forbids\n * shadowing.\n */\nexport function hasOwn<K extends PropertyKey>(value: unknown, key: K): value is Record<K, unknown> {\n  return isRecord(value) && key in value;\n}\n","import { type AssertEqual, hasOwn, type Prettify, type Serialized } from \"./type-utils.js\";\n\n// ---------------------------------------------------------------------------\n// Config\n// ---------------------------------------------------------------------------\n\n/** FAB anchor — bottom-corner placement supported by the widget. */\nexport type SitepingPosition = \"bottom-right\" | \"bottom-left\";\n\n/** Visual theme — `auto` resolves to `light` or `dark` via system preference. */\nexport type SitepingTheme = \"light\" | \"dark\" | \"auto\";\n\n/** Built-in UI locales shipped with the widget. */\nexport const BUILTIN_LOCALES = [\"en\", \"fr\", \"de\", \"es\", \"it\", \"pt\", \"ru\"] as const;\nexport type BuiltinLocale = (typeof BUILTIN_LOCALES)[number];\n\n/**\n * Locale identifier accepted by the widget. Built-in locales are kept as\n * literal strings so editors auto-complete them, but arbitrary BCP-47 tags\n * are also accepted (custom dictionaries registered via `registerLocale`).\n */\nexport type SitepingLocale = BuiltinLocale | (string & {});\n\n/**\n * Reasons reported through `SitepingConfig.onSkip` — production environment,\n * mobile viewport, or server-side rendering (no `window`/`document`).\n */\nexport type SitepingSkipReason = \"production\" | \"mobile\" | \"ssr\";\n\n/** Per-channel + per-buffer-size diagnostics configuration. */\nexport interface DiagnosticsCaptureOptions {\n  console?: boolean | undefined;\n  network?: boolean | undefined;\n  maxConsoleEntries?: number | undefined;\n  maxNetworkEntries?: number | undefined;\n}\n\n/** Identity payload supplied by the host application — bypasses the modal. */\nexport interface SitepingIdentity {\n  name: string;\n  email: string;\n}\n\n/** Deep-link configuration — controls how a feedback id is read from the URL. */\nexport interface SitepingDeepLinkOptions {\n  /** Query parameter name carrying the feedback id. Defaults to `\"siteping\"`. */\n  param?: string | undefined;\n}\n\n/**\n * Extra request headers for HTTP mode — a static map, or a factory (sync or\n * async) invoked once per request to produce fresh values (e.g. a short-lived\n * session token).\n */\nexport type SitepingHeadersOption =\n  | Record<string, string>\n  | (() => Record<string, string> | Promise<Record<string, string>>);\n\n/**\n * Options shared by both widget modes (HTTP and direct store).\n *\n * Do not use this type directly — use {@link SitepingConfig}, the\n * discriminated union that adds the mode-specific fields.\n */\nexport interface SitepingBaseConfig {\n  /** Required — project identifier used to scope feedbacks */\n  projectName: string;\n  /** FAB position — defaults to 'bottom-right' */\n  position?: SitepingPosition | undefined;\n  /**\n   * Show the \"toggle markers visibility\" item in the FAB radial menu.\n   * Defaults to `true` (current behavior). Set to `false` to hide that\n   * item entirely — useful for hosts that always want markers visible\n   * (e.g. dedicated review tools) or that find the eye icon redundant\n   * when no marker is on screen.\n   *\n   * Hiding the item also removes its keyboard navigation slot — the\n   * remaining two items still respond to ArrowUp/ArrowDown/Home/End.\n   * The marker-visibility state itself is unaffected; markers stay\n   * visible (the previous default state) and `annotations:toggle` is\n   * simply never emitted from the FAB.\n   */\n  showAnnotationsToggle?: boolean | undefined;\n  /** Accent color for the widget UI — defaults to '#0066ff' */\n  accentColor?: string | undefined;\n  /**\n   * Render the widget even when it would normally be skipped — this bypasses\n   * BOTH the production-environment guard AND the mobile-viewport guard.\n   * It does NOT bypass the SSR guard: without `window`/`document` the widget\n   * never renders and `onSkip(\"ssr\")` fires instead.\n   * Defaults to false. Use it for dedicated review tools, staging environments,\n   * or responsive testing where you always want the widget present.\n   */\n  forceShow?: boolean | undefined;\n  /**\n   * Minimum viewport width (px) at or above which the widget renders. Below it,\n   * the widget is skipped and `onSkip(\"mobile\")` fires. Defaults to `768`.\n   *\n   * Set lower (e.g. `0`) to allow narrow/mobile viewports, or use `forceShow`\n   * to bypass the viewport check entirely.\n   */\n  minViewportWidth?: number | undefined;\n  /** Enable debug logging of lifecycle events — defaults to false */\n  debug?: boolean | undefined;\n  /** Color theme — defaults to 'light' */\n  theme?: SitepingTheme | undefined;\n  /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru. Any other string falls back to English. */\n  locale?: SitepingLocale | undefined;\n  /**\n   * Returns the current page scope for annotations and panel filtering.\n   * Called on initial markers load and on `instance.refresh()`.\n   *\n   * Default: `{ url: window.location.pathname, urlPattern: null }` — annotations\n   * are scoped strictly to the current pathname.\n   *\n   * Apps with parameterized routes (e.g. React Router) should return both the\n   * concrete URL and the route template (e.g. `/orders/:orderId`) so the panel\n   * can offer a \"this type of page\" filter that groups feedbacks by template.\n   */\n  getPageScope?: (() => PageScope) | undefined;\n  /**\n   * When true (default), the widget filters initial markers and panel results\n   * by `feedback.url === scope.url`, so annotations created on one page never\n   * leak to other pages — even if their CSS selector accidentally matches.\n   * Set to `false` to revert to the legacy project-wide behavior.\n   */\n  scopeAnnotationsByUrl?: boolean | undefined;\n  /**\n   * Capture a JPEG screenshot of the annotated area on submit. Defaults to\n   * `false` — opt-in because:\n   *\n   * - it adds runtime weight (~40 KB gzip dynamic chunk for html2canvas,\n   *   loaded only on first capture),\n   * - it embeds page content in the feedback (privacy/GDPR consideration —\n   *   inform end users in your widget host UI when enabling).\n   *\n   * `html2canvas` ships as a regular dependency of `@siteping/widget` so the\n   * dynamic import always resolves; you don't need to install anything extra.\n   *\n   * **Masking sensitive elements:** add `data-siteping-ignore=\"true\"` to any\n   * element you do NOT want captured (password fields, credit-card forms,\n   * API tokens shown in the UI, etc.). The capture predicate skips matching\n   * elements *and their descendants*. Do this BEFORE turning on screenshots\n   * in production — once a feedback is saved, the screenshot is in your DB\n   * (or object storage) regardless of what was on the page.\n   */\n  enableScreenshot?: boolean | undefined;\n  /**\n   * Enable right-click (`contextmenu`) to instantly open the comment composer\n   * at the cursor location. When enabled, a document-level listener intercepts\n   * right-clicks, prevents the browser's native context menu, and enters the\n   * annotation flow anchored to the element under the cursor. Defaults to\n   * `false` — the browser's native context menu is never hijacked unless the\n   * host explicitly opts in.\n   *\n   * Keyboard-triggered context menus (≣ Menu key, Shift+F10) always get the\n   * native menu; only mouse right-click and touch/pen long-press open the\n   * composer.\n   *\n   * **Modifier-key escape hatch:** holding Shift, Ctrl, Alt, or Meta while\n   * right-clicking always falls through to the native context menu, giving\n   * users (and devtools) an escape hatch regardless of this setting.\n   *\n   * Right-clicks on SitePing's own UI (FAB, panel, markers, popup) are\n   * ignored — the native menu is shown as expected.\n   *\n   * Note: on Android, `contextmenu` fires on long-press. The widget already\n   * hides below `minViewportWidth` (default 768 px), but tablets above that\n   * threshold will trigger this flow on long-press.\n   */\n  enableRightClickComment?: boolean | undefined;\n  /**\n   * Capture the last few `console.*` calls and failed network requests\n   * (HTTP >= 400 or network error) at the moment a feedback is submitted.\n   *\n   * Lets reviewers replay the technical context that led to the report —\n   * stack traces, 500 responses, dead third-party scripts. Great for the\n   * \"the page just doesn't work\" feedback that contains zero detail.\n   *\n   * - `true` — capture with defaults (50 console / 20 network entries).\n   * - `false` (default) — no capture, no monkey-patching.\n   * - object — per-channel toggles + custom buffer sizes.\n   *\n   * **Privacy considerations:** console messages may contain anything the\n   * host page logs, including user data. Failed network requests record the\n   * URL (with query string) but never the response body. Inform end users\n   * before enabling in environments where they might log sensitive values.\n   */\n  captureDiagnostics?: boolean | DiagnosticsCaptureOptions | undefined;\n  /** Called when the widget is skipped (production mode, mobile viewport, SSR — no DOM) */\n  onSkip?: (reason: SitepingSkipReason) => void;\n  /**\n   * Auto-focus a specific annotation when its ID appears in the URL query\n   * string. Lets hosts deeplink directly into a feedback from external\n   * systems (Zammad tickets, Slack notifications, dashboard rows).\n   *\n   * When enabled, the widget reads the configured query parameter from\n   * `window.location.search` right after the initial markers load. If the\n   * value matches a visible feedback ID, the widget scrolls the annotation\n   * into view, pins its highlight, and pulses the marker — the same visual\n   * affordance a marker click produces.\n   *\n   * - `false` / `undefined` (default): no URL parsing. Existing behavior\n   *   unchanged, no host URL inspection.\n   * - `true`: enabled with default query parameter name `siteping`.\n   * - object: enabled with a custom parameter name. Use this to avoid\n   *   clashes with host-app query keys.\n   *\n   * Only the initial load triggers focus. Subsequent URL changes (SPA\n   * navigation, `history.pushState`, hash updates) are ignored —\n   * deliberate, to avoid surprising re-scrolls during normal browsing.\n   * Hosts that need re-focus on route change can call\n   * `instance.focusFeedback(id)` explicitly.\n   */\n  deepLink?: boolean | SitepingDeepLinkOptions | undefined;\n  /**\n   * Automatically re-fetch feedbacks when the page changes during client-side\n   * (SPA) navigation. Enabled by default.\n   *\n   * The widget is normally mounted once (singleton) inside a persistent layout\n   * — e.g. a Next.js App Router `layout.tsx`, which does NOT remount on\n   * client-side navigation. Without this, init runs a single time and both the\n   * panel list and the page markers stay frozen on the page where the widget\n   * first mounted. With it on, the widget patches the History API\n   * (`pushState`/`replaceState`, which SPA routers call instead of triggering\n   * `popstate`) and listens for `popstate`/`hashchange`, then re-fetches when\n   * the scope key (`getPageScope().url` + template) actually changes.\n   *\n   * This re-fetches data only — it deliberately does NOT re-focus or re-scroll\n   * to an annotation (deep-link focus stays initial-load only; see `deepLink`),\n   * so normal browsing is never interrupted by a surprise scroll.\n   *\n   * - `true` (default) — watch navigation and re-fetch on route change.\n   * - `false` — never touch the History API; hosts drive updates manually via\n   *   `instance.refresh()`.\n   */\n  watchNavigation?: boolean | undefined;\n  /**\n   * Pre-fill author identity from the host application — typically the\n   * currently signed-in user. When set, the widget uses these values\n   * directly and never shows the identity modal, even on first feedback.\n   *\n   * Use case: SSO-integrated apps where the end user is already\n   * authenticated by the host. Avoids the awkward \"enter your name and\n   * email\" prompt for users the host already knows.\n   *\n   * When unset (default), the widget falls back to localStorage and shows\n   * the modal on first feedback as before — existing behavior unchanged.\n   *\n   * Note: `config.identity` is **not** persisted to localStorage. It is\n   * read at widget init time, not on every render. Hosts that need live\n   * identity updates after sign-in/sign-out should currently remount the\n   * widget (e.g. via a React `key` on the wrapping component). See\n   * https://github.com/NeosiaNexus/SitePing/issues/85 for tracking a\n   * future enhancement that propagates identity updates without a remount.\n   */\n  identity?: SitepingIdentity | undefined;\n\n  // Events\n  /** Called when the feedback panel is opened. */\n  onOpen?: (() => void) | undefined;\n  /** Called when the feedback panel is closed. */\n  onClose?: (() => void) | undefined;\n  /** Called after a feedback is successfully submitted. */\n  onFeedbackSent?: ((feedback: FeedbackResponse) => void) | undefined;\n  /**\n   * Called when a feedback API call fails.\n   *\n   * The widget always emits a `SitepingError` (or a subclass:\n   * `SitepingNetworkError`, `SitepingValidationError`, `SitepingAuthError`)\n   * for HTTP-mode failures — host apps can `instanceof` to drive retry\n   * logic, or read `error.code` (`\"NETWORK\" | \"VALIDATION\" | \"AUTH\" |\n   * \"SERVER\"`) and `error.retryable`. The type is widened to `Error` so\n   * direct-store callers can still surface raw errors without breaking the\n   * contract.\n   */\n  onError?: ((error: Error) => void) | undefined;\n  /** Called when the user starts drawing an annotation. */\n  onAnnotationStart?: (() => void) | undefined;\n  /** Called when the user finishes drawing an annotation. */\n  onAnnotationEnd?: (() => void) | undefined;\n}\n\n/**\n * HTTP mode — the widget talks to a server endpoint backed by a store\n * adapter (e.g. `@siteping/adapter-prisma` request handlers).\n */\nexport interface SitepingHttpConfig extends SitepingBaseConfig {\n  /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). */\n  endpoint: string;\n  /**\n   * Convenience auth for HTTP mode — sent as `Authorization: Bearer <apiKey>`\n   * on every request to `endpoint`.\n   *\n   * **WARNING: the widget runs in every visitor's browser, so a static key\n   * configured here is public** — anyone can read it from your page source\n   * and replay it against your API. Only use `apiKey` for internal tools\n   * already behind your own login. On public sites, prefer `headers` with a\n   * per-request factory returning a short-lived session token.\n   */\n  apiKey?: string | undefined;\n  /**\n   * Extra headers for every HTTP-mode request — a static map, or a factory\n   * (sync or async) called once per request (e.g. to fetch a fresh session\n   * token). Merged over the widget's generated headers, so an explicit\n   * `Authorization` entry overrides `apiKey`. A throwing/rejecting factory\n   * fails the request like a network error.\n   */\n  headers?: SitepingHeadersOption | undefined;\n  /** Not available in HTTP mode — use either `endpoint` or `store`, never both. */\n  store?: never;\n}\n\n/**\n * Store mode — the widget talks to a `SitepingStore` directly in the\n * browser, no server needed (demos, prototypes, localStorage persistence).\n */\nexport interface SitepingStoreConfig extends SitepingBaseConfig {\n  /** Direct store for client-side mode. Bypasses HTTP entirely. */\n  store: SitepingStore;\n  /** Not available in store mode — use either `endpoint` or `store`, never both. */\n  endpoint?: never;\n  /** HTTP-mode only — meaningless without an `endpoint`. */\n  apiKey?: never;\n  /** HTTP-mode only — meaningless without an `endpoint`. */\n  headers?: never;\n}\n\n/**\n * Configuration options for the Siteping widget.\n *\n * A discriminated union over the two transport modes: pass `endpoint`\n * (HTTP mode, optionally with `apiKey`/`headers`) **or** `store` (direct\n * client-side mode) — never both, never neither. Invalid combinations are\n * compile errors instead of runtime warnings.\n */\nexport type SitepingConfig = SitepingHttpConfig | SitepingStoreConfig;\n\n/** Instance returned by initSiteping() with lifecycle methods. */\nexport interface SitepingInstance {\n  /** Remove the widget from the DOM and clean up all listeners. */\n  destroy: () => void;\n  /** Open the panel programmatically */\n  open: () => void;\n  /** Close the panel */\n  close: () => void;\n  /** Reload feedbacks from server */\n  refresh: () => void;\n  /**\n   * Scroll the matching annotation into view, pin its highlight, and\n   * pulse its marker. Returns `true` when a visible feedback matched the\n   * given ID, `false` otherwise (unknown ID, feedback on another URL when\n   * `scopeAnnotationsByUrl` filtered it out, or markers not yet loaded).\n   *\n   * Counterpart to the `deepLink` config option for hosts that prefer to\n   * drive focus from JS (e.g., a notification click handler) instead of a\n   * URL query parameter.\n   */\n  focusFeedback: (feedbackId: string) => boolean;\n  /** Subscribe to a public widget event */\n  on: <K extends keyof SitepingPublicEvents>(event: K, listener: SitepingPublicEventListener<K>) => SitepingUnsubscribe;\n  /** Unsubscribe from a public widget event */\n  off: <K extends keyof SitepingPublicEvents>(event: K, listener: SitepingPublicEventListener<K>) => void;\n}\n\n/** Listener signature for a single `SitepingPublicEvents` key. */\nexport type SitepingPublicEventListener<K extends keyof SitepingPublicEvents> = (\n  ...args: SitepingPublicEvents[K]\n) => void;\n\n/** Disposer returned by `SitepingInstance.on` — call once to detach the listener. */\nexport type SitepingUnsubscribe = () => void;\n\n/** Events exposed to consumers via SitepingInstance.on / .off */\nexport interface SitepingPublicEvents {\n  \"feedback:sent\": [FeedbackResponse];\n  \"feedback:deleted\": [FeedbackResponse[\"id\"]];\n  /**\n   * A feedback API call failed. Same payload contract as\n   * `SitepingConfig.onError` — a `SitepingError` subclass in HTTP mode,\n   * possibly a raw `Error` in store mode.\n   */\n  \"feedback:error\": [Error];\n  \"panel:open\": [];\n  \"panel:close\": [];\n  /** The user started drawing an annotation. */\n  \"annotation:start\": [];\n  /** The user finished drawing an annotation. */\n  \"annotation:end\": [];\n}\n\n// ---------------------------------------------------------------------------\n// Feedback\n// ---------------------------------------------------------------------------\n\n/** Single source of truth for feedback types — used by both TS types and Zod schemas. */\nexport const FEEDBACK_TYPES = [\"question\", \"change\", \"bug\", \"other\"] as const;\nexport type FeedbackType = (typeof FEEDBACK_TYPES)[number];\n\n/** Single source of truth for feedback statuses. */\nexport const FEEDBACK_STATUSES = [\"open\", \"in_progress\", \"resolved\", \"wont_fix\"] as const;\nexport type FeedbackStatus = (typeof FEEDBACK_STATUSES)[number];\n\n/**\n * Terminal statuses — the feedback needs no further action. `resolvedAt` is\n * the closure timestamp: set when a feedback enters a closed status, null\n * while it is open or in progress. The derivation happens at the edge (HTTP\n * handler, dashboard) — store adapters persist whatever they are given.\n */\nexport const CLOSED_FEEDBACK_STATUSES = [\"resolved\", \"wont_fix\"] as const;\n/** A terminal status — `resolved` or `wont_fix`. */\nexport type ClosedFeedbackStatus = (typeof CLOSED_FEEDBACK_STATUSES)[number];\n\n/** Non-terminal statuses — the feedback still needs attention. */\nexport const OPEN_FEEDBACK_STATUSES = [\"open\", \"in_progress\"] as const;\n/** A non-terminal status — `open` or `in_progress`. */\nexport type OpenFeedbackStatus = (typeof OPEN_FEEDBACK_STATUSES)[number];\n\n// Adding a fifth status without assigning it to exactly one bucket is a\n// compile error here.\nconst _statusBucketsCoverAll: AssertEqual<OpenFeedbackStatus | ClosedFeedbackStatus, FeedbackStatus> = true;\nvoid _statusBucketsCoverAll;\n\n/** Whether a status is terminal (`resolved` or `wont_fix`). Narrows the status type. */\nexport function isClosedStatus(status: FeedbackStatus): status is ClosedFeedbackStatus {\n  return (CLOSED_FEEDBACK_STATUSES as readonly FeedbackStatus[]).includes(status);\n}\n\n/**\n * Page scope returned by `SitepingConfig.getPageScope()`.\n *\n * - `url`: concrete page identifier — usually `window.location.pathname`,\n *   used as the strict scope for marker rendering.\n * - `urlPattern`: optional parameterized template (e.g. `/orders/:orderId`)\n *   used by the panel's \"this type of page\" filter to group feedbacks across\n *   instances of the same page kind.\n */\nexport interface PageScope {\n  url: string;\n  urlPattern: string | null;\n}\n\n// ---------------------------------------------------------------------------\n// Abstract Store — adapter pattern\n// ---------------------------------------------------------------------------\n\n/** Input for creating a feedback record in the store. */\nexport interface FeedbackCreateInput {\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  url: string;\n  /**\n   * Optional parameterized URL template (e.g. `/orders/:orderId`) for the page\n   * where the feedback was created. Allows the panel to filter feedbacks by\n   * \"this type of page\" across different instances. Null when the host did not\n   * provide a `getPageScope` callback or the route has no template.\n   */\n  urlPattern?: string | null | undefined;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  clientId: string;\n  annotations: AnnotationCreateInput[];\n  /**\n   * Base64 JPEG `data:` URL captured by the widget at submit time.\n   *\n   * Adapters with a configured `ScreenshotStorage` are expected to upload\n   * this and persist the returned URL on `FeedbackRecord.screenshotUrl`.\n   * Adapters without storage may persist the data URL inline (memory /\n   * localStorage / dev) — the widget then renders it directly.\n   */\n  screenshotDataUrl?: string | null | undefined;\n  /**\n   * Where the client's annotation rect sits within the screenshot image,\n   * as fractions [0, 1] of the image dimensions. Present when the widget\n   * captured context around the drawn rect; null for legacy captures that\n   * were cropped exactly to the rect (dashboards then render the image\n   * without an overlay).\n   */\n  screenshotRegion?: ScreenshotRegion | null | undefined;\n  /**\n   * Optional console + failed-network snapshot captured by the widget when\n   * `SitepingConfig.captureDiagnostics` is enabled. Stored as JSON on\n   * `FeedbackRecord.diagnostics` so reviewers can replay the context.\n   */\n  diagnostics?: DiagnosticsSnapshot | null | undefined;\n}\n\n/** Input for a single annotation when creating a feedback. */\nexport interface AnnotationCreateInput {\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId?: string | undefined;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  /**\n   * Semantic anchor identifier from the closest ancestor's `data-feedback-anchor`\n   * attribute. When set, this is the most stable re-anchoring signal because\n   * hosts deliberately place these on layout/section roots that survive DOM\n   * refactors and viewport changes. Null when no semantic ancestor exists.\n   */\n  anchorKey?: string | null | undefined;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n}\n\n/** Query parameters for fetching feedbacks. */\nexport interface FeedbackQuery {\n  projectName: string;\n  type?: FeedbackType | undefined;\n  /** Exact single-status filter. For \"any of a set\" (bucket) semantics, use `statuses`. */\n  status?: FeedbackStatus | undefined;\n  /**\n   * Filter to feedbacks whose status is any of the listed values — bucket\n   * semantics used by the panel's binary tabs (e.g. \"Open\" passes\n   * `[\"open\", \"in_progress\"]`). When both `status` and `statuses` are set,\n   * `statuses` wins. An empty array is treated as absent (no status filter).\n   */\n  statuses?: readonly FeedbackStatus[] | undefined;\n  search?: string | undefined;\n  page?: number | undefined;\n  limit?: number | undefined;\n  /**\n   * Filter to feedbacks created on this exact URL (path). Used by the panel's\n   * \"this page\" filter and by the markers loader to keep page scopes isolated.\n   */\n  url?: string | undefined;\n  /**\n   * Filter to feedbacks created on this URL pattern (e.g. `/orders/:orderId`).\n   * Used by the panel's \"this type of page\" filter to group feedbacks across\n   * different concrete instances of the same template.\n   */\n  urlPattern?: string | undefined;\n}\n\n/**\n * Update payload for patching a feedback.\n *\n * A discriminated union encoding the closure invariant: a feedback entering\n * a closed status carries its closure timestamp, an open one carries `null`.\n * `{ status: \"resolved\", resolvedAt: null }` is a compile error instead of a\n * silent data bug. Build it from a plain `FeedbackStatus` with\n * {@link toFeedbackUpdate}.\n */\nexport type FeedbackUpdateInput =\n  | { status: OpenFeedbackStatus; resolvedAt: null }\n  | { status: ClosedFeedbackStatus; resolvedAt: Date };\n\n/**\n * Derive the {@link FeedbackUpdateInput} for a status change — the closure\n * timestamp is stamped for closed statuses and cleared otherwise. This is\n * the edge derivation described on {@link CLOSED_FEEDBACK_STATUSES}; store\n * adapters persist the result verbatim.\n */\nexport function toFeedbackUpdate(status: FeedbackStatus, closedAt: Date = new Date()): FeedbackUpdateInput {\n  return isClosedStatus(status) ? { status, resolvedAt: closedAt } : { status, resolvedAt: null };\n}\n\n/** A persisted feedback record returned by the store. */\nexport interface FeedbackRecord {\n  id: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  projectName: string;\n  url: string;\n  /**\n   * Parameterized URL template the feedback was created on.\n   * Null for legacy records or hosts without `getPageScope`.\n   */\n  urlPattern: string | null;\n  authorName: string;\n  authorEmail: string;\n  viewport: string;\n  userAgent: string;\n  clientId: string;\n  resolvedAt: Date | null;\n  createdAt: Date;\n  updatedAt: Date;\n  annotations: AnnotationRecord[];\n  /**\n   * URL the widget renders as `<img src>`. Either an `https://...` from a\n   * configured `ScreenshotStorage`, or a `data:image/jpeg;base64,...` URL\n   * inline-persisted by adapters without storage. Null when no screenshot\n   * was captured (legacy records, capture failed, or host disabled it).\n   */\n  screenshotUrl: string | null;\n  /**\n   * Annotation rect position within the screenshot image, as fractions of\n   * its dimensions. Null for legacy captures cropped exactly to the rect.\n   */\n  screenshotRegion: ScreenshotRegion | null;\n  /**\n   * Console + failed-network snapshot captured at submit time. Null when\n   * diagnostics weren't enabled on the widget side.\n   */\n  diagnostics: DiagnosticsSnapshot | null;\n}\n\n/** A persisted annotation record returned by the store. */\nexport interface AnnotationRecord {\n  id: string;\n  feedbackId: string;\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId: string | null;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  /**\n   * Semantic anchor identifier from `data-feedback-anchor`. Null for legacy\n   * annotations or those drawn outside any anchored region.\n   */\n  anchorKey: string | null;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n  createdAt: Date;\n}\n\n// ---------------------------------------------------------------------------\n// Store errors — throw these from adapter implementations\n// ---------------------------------------------------------------------------\n\n/**\n * Thrown when a record is not found during update or delete.\n *\n * Handlers translate this to HTTP 404. Adapters MUST throw this (not\n * ORM-specific errors) so the handler layer remains ORM-agnostic.\n */\nexport class StoreNotFoundError extends Error {\n  readonly code = \"STORE_NOT_FOUND\" as const;\n  constructor(message = \"Record not found\") {\n    super(message);\n    this.name = \"StoreNotFoundError\";\n  }\n}\n\n/**\n * Thrown when a unique constraint is violated (e.g. duplicate `clientId`).\n *\n * Handlers use this to return the existing record instead of failing.\n */\nexport class StoreDuplicateError extends Error {\n  readonly code = \"STORE_DUPLICATE\" as const;\n  constructor(message = \"Duplicate record\") {\n    super(message);\n    this.name = \"StoreDuplicateError\";\n  }\n}\n\n/**\n * Thrown when a store accepts a mutation but cannot persist it — e.g.\n * `localStorage` is full (QuotaExceededError). Adapters MUST throw this rather\n * than swallow the failure, so callers learn the write was lost instead of\n * seeing a phantom success.\n */\nexport class StorePersistenceError extends Error {\n  readonly code = \"STORE_PERSISTENCE\" as const;\n  constructor(message = \"Failed to persist store mutation\", options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"StorePersistenceError\";\n  }\n}\n\n/** Shape of any ORM error that carries a Prisma-style `code` field. */\ntype CodedError<C extends string = string> = { code: C };\n\nfunction hasErrorCode<C extends string>(error: unknown, code: C): error is CodedError<C> {\n  return hasOwn(error, \"code\") && error.code === code;\n}\n\n/** Type guard — works for `StoreNotFoundError` and ORM-specific equivalents (e.g. Prisma P2025). */\nexport function isStoreNotFound(error: unknown): error is StoreNotFoundError | CodedError<\"P2025\"> {\n  if (error instanceof StoreNotFoundError) return true;\n  // Backwards compat: Prisma's P2025\n  return hasErrorCode(error, \"P2025\");\n}\n\n/** Type guard — works for `StoreDuplicateError` and ORM-specific equivalents (e.g. Prisma P2002). */\nexport function isStoreDuplicate(error: unknown): error is StoreDuplicateError | CodedError<\"P2002\"> {\n  if (error instanceof StoreDuplicateError) return true;\n  // Backwards compat: Prisma's P2002\n  return hasErrorCode(error, \"P2002\");\n}\n\n/**\n * Type guard for `StorePersistenceError`. Matches on the stable `code` field\n * in addition to `instanceof`: every consumer package bundles its own copy of\n * core (tsup `noExternal`), so an instance thrown by one package fails an\n * `instanceof` check against another package's class identity.\n */\nexport function isStorePersistence(error: unknown): error is StorePersistenceError | CodedError<\"STORE_PERSISTENCE\"> {\n  if (error instanceof StorePersistenceError) return true;\n  return hasErrorCode(error, \"STORE_PERSISTENCE\");\n}\n\n// ---------------------------------------------------------------------------\n// Store helpers — shared conversion logic for adapters\n// ---------------------------------------------------------------------------\n\n/** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */\nexport function flattenAnnotation(ann: AnnotationPayload): AnnotationCreateInput {\n  return {\n    cssSelector: ann.anchor.cssSelector,\n    xpath: ann.anchor.xpath,\n    textSnippet: ann.anchor.textSnippet,\n    elementTag: ann.anchor.elementTag,\n    elementId: ann.anchor.elementId,\n    textPrefix: ann.anchor.textPrefix,\n    textSuffix: ann.anchor.textSuffix,\n    fingerprint: ann.anchor.fingerprint,\n    neighborText: ann.anchor.neighborText,\n    anchorKey: ann.anchor.anchorKey ?? null,\n    xPct: ann.rect.xPct,\n    yPct: ann.rect.yPct,\n    wPct: ann.rect.wPct,\n    hPct: ann.rect.hPct,\n    scrollX: ann.scrollX,\n    scrollY: ann.scrollY,\n    viewportW: ann.viewportW,\n    viewportH: ann.viewportH,\n    devicePixelRatio: ann.devicePixelRatio,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Abstract Store — adapter pattern\n// ---------------------------------------------------------------------------\n\n/** Paginated result returned by `SitepingStore.getFeedbacks`. */\nexport interface FeedbackPage {\n  feedbacks: FeedbackRecord[];\n  total: number;\n}\n\n/**\n * Abstract storage interface for Siteping.\n *\n * Any adapter (Prisma, Drizzle, raw SQL, localStorage, etc.) implements this\n * interface. The HTTP handler and widget `StoreClient` operate against\n * `SitepingStore`, decoupled from the storage backend.\n *\n * ## Error contract\n *\n * - **`updateFeedback` / `deleteFeedback`**: throw `StoreNotFoundError` when\n *   the record does not exist.\n * - **`createFeedback`**: either return the existing record on duplicate\n *   `clientId` (idempotent) or throw `StoreDuplicateError`. The handler\n *   handles both patterns.\n * - **All mutations**: when a write is accepted but cannot be persisted\n *   (e.g. storage quota), throw `StorePersistenceError` instead of reporting\n *   a phantom success. Detect it with `isStorePersistence`.\n * - Other methods should not throw on empty results — return empty arrays or `null`.\n */\nexport interface SitepingStore {\n  /** 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. */\n  createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;\n  /** Paginated query with optional filters. Returns empty array (not error) when no results. */\n  getFeedbacks(query: FeedbackQuery): Promise<FeedbackPage>;\n  /** Lookup by client-generated UUID. Returns `null` (not error) when not found. */\n  findByClientId(clientId: string): Promise<FeedbackRecord | null>;\n  /** Update status/resolvedAt. Throws `StoreNotFoundError` if `id` does not exist, `StorePersistenceError` when the write cannot be persisted. */\n  updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;\n  /** Delete a single record. Throws `StoreNotFoundError` if `id` does not exist, `StorePersistenceError` when the write cannot be persisted. */\n  deleteFeedback(id: string): Promise<void>;\n  /** Bulk delete all feedbacks for a project. No-op (not error) if none exist. Throws `StorePersistenceError` when the write cannot be persisted. */\n  deleteAllFeedbacks(projectName: string): Promise<void>;\n  /**\n   * Optional — return `true` when the record with `id` belongs to\n   * `projectName`, `false` otherwise (including when it does not exist).\n   *\n   * HTTP handlers use this to reject cross-project PATCH/DELETE requests.\n   * Implement it whenever your store serves multiple projects; when absent,\n   * handlers skip the ownership check and rely on `id` alone.\n   */\n  verifyProjectOwnership?(id: string, projectName: string): Promise<boolean>;\n}\n\n/** Payload sent from the widget to the server when submitting feedback. */\nexport interface FeedbackPayload {\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  url: string;\n  /**\n   * Parameterized URL template (e.g. `/orders/:orderId`) supplied by\n   * `SitepingConfig.getPageScope()`. Null when the host did not provide one.\n   */\n  urlPattern?: string | null | undefined;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  annotations: AnnotationPayload[];\n  /** Client-generated UUID for deduplication */\n  clientId: string;\n  /**\n   * Base64 JPEG `data:` URL of the annotated area. Captured by the widget\n   * when `enableScreenshot: true` is set in `SitepingConfig`. Null when\n   * disabled or when capture failed silently.\n   */\n  screenshotDataUrl?: string | null | undefined;\n  /**\n   * Annotation rect position within the screenshot image — see\n   * `ScreenshotRegion`. Null/absent when no screenshot was captured or the\n   * capture predates contextual framing.\n   */\n  screenshotRegion?: ScreenshotRegion | null | undefined;\n  /**\n   * Snapshot of the last few console messages and failed network requests\n   * captured at submit time when `captureDiagnostics` is enabled.\n   */\n  diagnostics?: DiagnosticsSnapshot | null | undefined;\n}\n\n/** Single source of truth for console diagnostic severity levels. */\nexport const CONSOLE_DIAGNOSTIC_LEVELS = [\"log\", \"info\", \"warn\", \"error\"] as const;\n/** Severity levels persisted in `ConsoleDiagnosticEntry`. */\nexport type ConsoleDiagnosticLevel = (typeof CONSOLE_DIAGNOSTIC_LEVELS)[number];\n\n/** A single console entry captured by `ConsoleBuffer`. */\nexport interface ConsoleDiagnosticEntry {\n  level: ConsoleDiagnosticLevel;\n  /** ISO 8601 timestamp captured at log time. */\n  timestamp: string;\n  /** Best-effort string representation of the original console args. */\n  message: string;\n}\n\n/** A single failed network request captured by `NetworkBuffer`. */\nexport interface NetworkDiagnosticEntry {\n  url: string;\n  method: string;\n  /** HTTP status; 0 when the request never reached the server. */\n  status: number;\n  /** End-to-end duration in ms. */\n  durationMs: number;\n  /** ISO 8601 timestamp at the moment the request was initiated. */\n  timestamp: string;\n}\n\n/**\n * Diagnostics captured by the widget when `captureDiagnostics` is enabled.\n *\n * Both arrays are bounded (default: 50 console / 20 network). Adapters that\n * support diagnostics should persist this as a JSON blob alongside the\n * feedback so reviewers can replay the context that led to the report.\n */\nexport interface DiagnosticsSnapshot {\n  console: ConsoleDiagnosticEntry[];\n  network: NetworkDiagnosticEntry[];\n}\n\n// ---------------------------------------------------------------------------\n// Annotation — multi-selector anchoring (Hypothesis / W3C Web Annotation)\n// ---------------------------------------------------------------------------\n\n/** DOM anchoring data for re-attaching annotations to page elements. */\nexport interface AnchorData {\n  /** CSS selector generated by @medv/finder — primary anchor */\n  cssSelector: string;\n  /** XPath — fallback 1 */\n  xpath: string;\n  /** First ~120 chars of element innerText — empty string if none */\n  textSnippet: string;\n  /** Tag name for validation (e.g. \"DIV\", \"SECTION\") */\n  elementTag: string;\n  /** Element id attribute if available — most stable */\n  elementId?: string | undefined;\n  /** ~32 chars of text before this element in document flow (disambiguation) */\n  textPrefix: string;\n  /** ~32 chars of text after this element in document flow (disambiguation) */\n  textSuffix: string;\n  /** Structural fingerprint: \"childCount:siblingIdx:attrHash\" */\n  fingerprint: string;\n  /** Text content of adjacent sibling elements (context) */\n  neighborText: string;\n  /**\n   * Semantic anchor identifier from the closest ancestor's `data-feedback-anchor`\n   * attribute. When set, this is the highest-priority re-anchoring signal —\n   * hosts deliberately place these on layout/section roots that survive\n   * viewport changes and DOM refactors.\n   */\n  anchorKey?: string | null | undefined;\n}\n\n/**\n * Where the client's annotation rect sits within the captured screenshot,\n * as fractions [0, 1] of the image dimensions. The widget captures context\n * around the drawn rect and records the rect's position here so dashboards\n * can re-render the annotation on top of the image. Survives downscaling\n * (fractions are resolution-independent).\n */\nexport interface ScreenshotRegion {\n  /** X offset of the rect as fraction of image width — [0, 1] */\n  xPct: number;\n  /** Y offset of the rect as fraction of image height — [0, 1] */\n  yPct: number;\n  /** Rect width as fraction of image width — [0, 1] */\n  wPct: number;\n  /** Rect height as fraction of image height — [0, 1] */\n  hPct: number;\n}\n\n/** Drawn rectangle coordinates as percentages relative to the anchor element. */\nexport interface RectData {\n  /** X offset as fraction of anchor element width — must be in range [0, 1] */\n  xPct: number;\n  /** Y offset as fraction of anchor element height — must be in range [0, 1] */\n  yPct: number;\n  /** Width as fraction of anchor element width — must be in range [0, 1] */\n  wPct: number;\n  /** Height as fraction of anchor element height — must be in range [0, 1] */\n  hPct: number;\n}\n\n/** Annotation data sent as part of a feedback submission. */\nexport interface AnnotationPayload {\n  anchor: AnchorData;\n  rect: RectData;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n}\n\n// ---------------------------------------------------------------------------\n// API responses\n// ---------------------------------------------------------------------------\n\n/**\n * Feedback record as returned by the API — derived from\n * {@link FeedbackRecord}: dates are serialized to ISO strings and `clientId`\n * is omitted (server-side dedup concern, never exposed on the wire). Adding\n * a field to `FeedbackRecord` updates this type automatically.\n *\n * Note: `authorEmail` may be an empty string — HTTP adapters redact it for\n * unauthenticated requests; the full value requires a Bearer-authenticated\n * request.\n */\nexport type FeedbackResponse = Prettify<Serialized<Omit<FeedbackRecord, \"clientId\">>>;\n\n/**\n * Annotation record as returned by the API — {@link AnnotationRecord} with\n * `createdAt` serialized to an ISO string.\n */\nexport type AnnotationResponse = Prettify<Serialized<AnnotationRecord>>;\n\n/** Paginated `FeedbackResponse` shape returned by the API. */\nexport interface FeedbackResponseList {\n  feedbacks: FeedbackResponse[];\n  total: number;\n}\n","/**\n * Record-construction helpers and the collection-store engine.\n *\n * Every snapshot-style adapter (memory, localStorage, flat file, KV, …)\n * needs the same three ingredients: turn a `FeedbackCreateInput` into a\n * `FeedbackRecord` (null-normalizing optional fields, stamping ids and\n * timestamps), filter/paginate with `applyFeedbackFilters`, and implement\n * the dedup/update/delete choreography of the `SitepingStore` contract.\n *\n * `buildFeedbackRecord` / `buildAnnotationRecord` cover the first part for\n * any adapter. `createCollectionStore` covers all of it: give it `load`,\n * `persist`, and `generateId`, and it returns a fully conformant\n * `SitepingStore` — writing a new snapshot adapter is ~20 lines plus its\n * storage specifics.\n */\n\nimport { applyFeedbackFilters } from \"./filters.js\";\nimport type {\n  AnnotationCreateInput,\n  AnnotationRecord,\n  FeedbackCreateInput,\n  FeedbackPage,\n  FeedbackQuery,\n  FeedbackRecord,\n  FeedbackUpdateInput,\n  SitepingStore,\n} from \"./types.js\";\nimport { StoreNotFoundError } from \"./types.js\";\n\n// ---------------------------------------------------------------------------\n// Record construction\n// ---------------------------------------------------------------------------\n\n/**\n * Build a persisted `AnnotationRecord` from its create input — normalizes\n * the optional anchor fields to `null` and stamps identity/timestamp.\n */\nexport function buildAnnotationRecord(\n  input: AnnotationCreateInput,\n  ctx: { id: string; feedbackId: string; now: Date },\n): AnnotationRecord {\n  return {\n    id: ctx.id,\n    feedbackId: ctx.feedbackId,\n    cssSelector: input.cssSelector,\n    xpath: input.xpath,\n    textSnippet: input.textSnippet,\n    elementTag: input.elementTag,\n    elementId: input.elementId ?? null,\n    textPrefix: input.textPrefix,\n    textSuffix: input.textSuffix,\n    fingerprint: input.fingerprint,\n    neighborText: input.neighborText,\n    anchorKey: input.anchorKey ?? null,\n    xPct: input.xPct,\n    yPct: input.yPct,\n    wPct: input.wPct,\n    hPct: input.hPct,\n    scrollX: input.scrollX,\n    scrollY: input.scrollY,\n    viewportW: input.viewportW,\n    viewportH: input.viewportH,\n    devicePixelRatio: input.devicePixelRatio,\n    createdAt: ctx.now,\n  };\n}\n\n/**\n * Build a persisted `FeedbackRecord` (with its annotations) from a create\n * input — normalizes every optional field to `null` and stamps ids and\n * timestamps. Adapters without external screenshot storage keep the data\n * URL inline on `screenshotUrl`, which is what this helper does; adapters\n * with a `ScreenshotStorage` upload first and override `screenshotUrl`.\n */\nexport function buildFeedbackRecord(\n  input: FeedbackCreateInput,\n  ctx: { id: string; annotationId: () => string; now?: Date },\n): FeedbackRecord {\n  const now = ctx.now ?? new Date();\n  return {\n    id: ctx.id,\n    type: input.type,\n    message: input.message,\n    status: input.status,\n    projectName: input.projectName,\n    url: input.url,\n    urlPattern: input.urlPattern ?? null,\n    authorName: input.authorName,\n    authorEmail: input.authorEmail,\n    viewport: input.viewport,\n    userAgent: input.userAgent,\n    clientId: input.clientId,\n    resolvedAt: null,\n    createdAt: now,\n    updatedAt: now,\n    annotations: input.annotations.map((ann) =>\n      buildAnnotationRecord(ann, { id: ctx.annotationId(), feedbackId: ctx.id, now }),\n    ),\n    screenshotUrl: input.screenshotDataUrl ?? null,\n    screenshotRegion: input.screenshotRegion ?? null,\n    diagnostics: input.diagnostics ?? null,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Collection-store engine\n// ---------------------------------------------------------------------------\n\n/**\n * Storage primitives behind a collection store. `load`/`persist` may be\n * sync or async — the engine awaits both, so in-memory arrays, localStorage\n * and async KV stores all fit the same three functions.\n */\nexport interface CollectionStoreBackend {\n  /** Return the current full snapshot of feedback records. */\n  load(): FeedbackRecord[] | Promise<FeedbackRecord[]>;\n  /**\n   * Persist the full snapshot. Throw `StorePersistenceError` when the write\n   * is lost (quota, storage disabled, …) — never swallow the failure.\n   */\n  persist(feedbacks: FeedbackRecord[]): void | Promise<void>;\n  /** Generate a unique id for a new feedback or annotation record. */\n  generateId(): string;\n}\n\n/**\n * A `SitepingStore` with the optional `verifyProjectOwnership` guaranteed —\n * what `createCollectionStore` returns.\n */\nexport type CollectionStore = SitepingStore & Required<Pick<SitepingStore, \"verifyProjectOwnership\">>;\n\n/**\n * Build a fully conformant `SitepingStore` on top of a snapshot backend.\n *\n * The engine implements the whole store contract: clientId dedup (idempotent\n * create), newest-first ordering, the standard filter/pagination pipeline,\n * `StoreNotFoundError` on missing update/delete, project-scoped bulk delete,\n * and `verifyProjectOwnership`. When `persist` fails during `createFeedback`\n * and the record carries an inline screenshot, the engine retries once\n * without the screenshot (by far the heaviest field) so the text feedback\n * survives a storage-quota hit; if that also fails, the error propagates —\n * returning the record would claim a success that was never persisted.\n *\n * @example\n * ```ts\n * export class MemoryStore implements SitepingStore {\n *   private feedbacks: FeedbackRecord[] = [];\n *   private readonly store = createCollectionStore({\n *     load: () => this.feedbacks,\n *     persist: (next) => {\n *       this.feedbacks = next;\n *     },\n *     generateId: () => crypto.randomUUID(),\n *   });\n *   createFeedback = this.store.createFeedback;\n *   // …delegate the remaining methods the same way\n * }\n * ```\n */\nexport function createCollectionStore(backend: CollectionStoreBackend): CollectionStore {\n  return {\n    async createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord> {\n      const feedbacks = await backend.load();\n\n      // ClientId dedup — idempotent\n      const existing = feedbacks.find((f) => f.clientId === data.clientId);\n      if (existing) return existing;\n\n      const record = buildFeedbackRecord(data, {\n        id: backend.generateId(),\n        annotationId: () => backend.generateId(),\n      });\n\n      feedbacks.unshift(record);\n      try {\n        await backend.persist(feedbacks);\n      } catch (err) {\n        if (!record.screenshotUrl) throw err;\n        record.screenshotUrl = null;\n        await backend.persist(feedbacks);\n      }\n      return record;\n    },\n\n    async getFeedbacks(query: FeedbackQuery): Promise<FeedbackPage> {\n      return applyFeedbackFilters(await backend.load(), query);\n    },\n\n    async findByClientId(clientId: string): Promise<FeedbackRecord | null> {\n      return (await backend.load()).find((f) => f.clientId === clientId) ?? null;\n    },\n\n    async updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord> {\n      const feedbacks = await backend.load();\n      const fb = feedbacks.find((f) => f.id === id);\n      if (!fb) throw new StoreNotFoundError();\n\n      fb.status = data.status;\n      fb.resolvedAt = data.resolvedAt;\n      fb.updatedAt = new Date();\n      await backend.persist(feedbacks);\n      return fb;\n    },\n\n    async deleteFeedback(id: string): Promise<void> {\n      const feedbacks = await backend.load();\n      const idx = feedbacks.findIndex((f) => f.id === id);\n      if (idx === -1) throw new StoreNotFoundError();\n\n      feedbacks.splice(idx, 1);\n      await backend.persist(feedbacks);\n    },\n\n    async deleteAllFeedbacks(projectName: string): Promise<void> {\n      const feedbacks = await backend.load();\n      await backend.persist(feedbacks.filter((f) => f.projectName !== projectName));\n    },\n\n    async verifyProjectOwnership(id: string, projectName: string): Promise<boolean> {\n      const fb = (await backend.load()).find((f) => f.id === id);\n      return fb !== undefined && fb.projectName === projectName;\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+export { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, CLOSED_FEEDBACK_STATUSES, CONSOLE_DIAGNOSTIC_LEVELS, ClosedFeedbackStatus, CollectionStore, CollectionStoreBackend, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsSnapshot, FEEDBACK_STATUSES, FEEDBACK_TYPES, FeedbackCreateInput, FeedbackPage, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, FilterResult, NetworkDiagnosticEntry, OPEN_FEEDBACK_STATUSES, OpenFeedbackStatus, RectData, ScreenshotRegion, ScreenshotStorage, Serialized, SitepingStore, StoreDuplicateError, StoreNotFoundError, StorePersistenceError, applyFeedbackFilters, buildAnnotationRecord, buildFeedbackRecord, createCollectionStore, flattenAnnotation, isClosedStatus, isStoreDuplicate, isStoreNotFound, isStorePersistence, toFeedbackUpdate } from './siteping-core.cjs';
+import './siteping-core-testing.cjs';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, CLOSED_FEEDBACK_STATUSES, CONSOLE_DIAGNOSTIC_LEVELS, ClosedFeedbackStatus, CollectionStore, CollectionStoreBackend, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsSnapshot, FEEDBACK_STATUSES, FEEDBACK_TYPES, FeedbackCreateInput, FeedbackPage, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, FilterResult, NetworkDiagnosticEntry, OPEN_FEEDBACK_STATUSES, OpenFeedbackStatus, RectData, ScreenshotRegion, ScreenshotStorage, Serialized, SitepingStore, StoreDuplicateError, StoreNotFoundError, StorePersistenceError, applyFeedbackFilters, buildAnnotationRecord, buildFeedbackRecord, createCollectionStore, flattenAnnotation, isClosedStatus, isStoreDuplicate, isStoreNotFound, isStorePersistence, toFeedbackUpdate } from './siteping-core.js';
+import './siteping-core-testing.js';

package/dist/index.js

@@ -0,0 +1,170 @@
+import {
+  CLOSED_FEEDBACK_STATUSES,
+  CONSOLE_DIAGNOSTIC_LEVELS,
+  FEEDBACK_STATUSES,
+  FEEDBACK_TYPES,
+  OPEN_FEEDBACK_STATUSES,
+  StoreDuplicateError,
+  StoreNotFoundError,
+  StorePersistenceError,
+  flattenAnnotation,
+  isClosedStatus,
+  isStoreDuplicate,
+  isStoreNotFound,
+  isStorePersistence,
+  toFeedbackUpdate
+} from "./chunk-YQHAD24P.js";
+
+// ../core/src/filters.ts
+var DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 100;
+function applyFeedbackFilters(items, query) {
+  let results = items.filter((f) => f.projectName === query.projectName);
+  if (query.type) results = results.filter((f) => f.type === query.type);
+  if (query.statuses && query.statuses.length > 0) {
+    const allowed = query.statuses;
+    results = results.filter((f) => allowed.includes(f.status));
+  } else if (query.status) {
+    results = results.filter((f) => f.status === query.status);
+  }
+  if (query.url) results = results.filter((f) => f.url === query.url);
+  if (query.urlPattern) results = results.filter((f) => f.urlPattern === query.urlPattern);
+  if (query.search) {
+    const s = query.search.toLowerCase();
+    results = results.filter((f) => f.message.toLowerCase().includes(s));
+  }
+  results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+  const total = results.length;
+  const page = Math.max(1, query.page ?? 1);
+  const limit = Math.max(1, Math.min(query.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
+  const start = (page - 1) * limit;
+  return { feedbacks: results.slice(start, start + limit), total };
+}
+
+// ../core/src/store-helpers.ts
+function buildAnnotationRecord(input, ctx) {
+  return {
+    id: ctx.id,
+    feedbackId: ctx.feedbackId,
+    cssSelector: input.cssSelector,
+    xpath: input.xpath,
+    textSnippet: input.textSnippet,
+    elementTag: input.elementTag,
+    elementId: input.elementId ?? null,
+    textPrefix: input.textPrefix,
+    textSuffix: input.textSuffix,
+    fingerprint: input.fingerprint,
+    neighborText: input.neighborText,
+    anchorKey: input.anchorKey ?? null,
+    xPct: input.xPct,
+    yPct: input.yPct,
+    wPct: input.wPct,
+    hPct: input.hPct,
+    scrollX: input.scrollX,
+    scrollY: input.scrollY,
+    viewportW: input.viewportW,
+    viewportH: input.viewportH,
+    devicePixelRatio: input.devicePixelRatio,
+    createdAt: ctx.now
+  };
+}
+function buildFeedbackRecord(input, ctx) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  return {
+    id: ctx.id,
+    type: input.type,
+    message: input.message,
+    status: input.status,
+    projectName: input.projectName,
+    url: input.url,
+    urlPattern: input.urlPattern ?? null,
+    authorName: input.authorName,
+    authorEmail: input.authorEmail,
+    viewport: input.viewport,
+    userAgent: input.userAgent,
+    clientId: input.clientId,
+    resolvedAt: null,
+    createdAt: now,
+    updatedAt: now,
+    annotations: input.annotations.map(
+      (ann) => buildAnnotationRecord(ann, { id: ctx.annotationId(), feedbackId: ctx.id, now })
+    ),
+    screenshotUrl: input.screenshotDataUrl ?? null,
+    screenshotRegion: input.screenshotRegion ?? null,
+    diagnostics: input.diagnostics ?? null
+  };
+}
+function createCollectionStore(backend) {
+  return {
+    async createFeedback(data) {
+      const feedbacks = await backend.load();
+      const existing = feedbacks.find((f) => f.clientId === data.clientId);
+      if (existing) return existing;
+      const record = buildFeedbackRecord(data, {
+        id: backend.generateId(),
+        annotationId: () => backend.generateId()
+      });
+      feedbacks.unshift(record);
+      try {
+        await backend.persist(feedbacks);
+      } catch (err) {
+        if (!record.screenshotUrl) throw err;
+        record.screenshotUrl = null;
+        await backend.persist(feedbacks);
+      }
+      return record;
+    },
+    async getFeedbacks(query) {
+      return applyFeedbackFilters(await backend.load(), query);
+    },
+    async findByClientId(clientId) {
+      return (await backend.load()).find((f) => f.clientId === clientId) ?? null;
+    },
+    async updateFeedback(id, data) {
+      const feedbacks = await backend.load();
+      const fb = feedbacks.find((f) => f.id === id);
+      if (!fb) throw new StoreNotFoundError();
+      fb.status = data.status;
+      fb.resolvedAt = data.resolvedAt;
+      fb.updatedAt = /* @__PURE__ */ new Date();
+      await backend.persist(feedbacks);
+      return fb;
+    },
+    async deleteFeedback(id) {
+      const feedbacks = await backend.load();
+      const idx = feedbacks.findIndex((f) => f.id === id);
+      if (idx === -1) throw new StoreNotFoundError();
+      feedbacks.splice(idx, 1);
+      await backend.persist(feedbacks);
+    },
+    async deleteAllFeedbacks(projectName) {
+      const feedbacks = await backend.load();
+      await backend.persist(feedbacks.filter((f) => f.projectName !== projectName));
+    },
+    async verifyProjectOwnership(id, projectName) {
+      const fb = (await backend.load()).find((f) => f.id === id);
+      return fb !== void 0 && fb.projectName === projectName;
+    }
+  };
+}
+export {
+  CLOSED_FEEDBACK_STATUSES,
+  CONSOLE_DIAGNOSTIC_LEVELS,
+  FEEDBACK_STATUSES,
+  FEEDBACK_TYPES,
+  OPEN_FEEDBACK_STATUSES,
+  StoreDuplicateError,
+  StoreNotFoundError,
+  StorePersistenceError,
+  applyFeedbackFilters,
+  buildAnnotationRecord,
+  buildFeedbackRecord,
+  createCollectionStore,
+  flattenAnnotation,
+  isClosedStatus,
+  isStoreDuplicate,
+  isStoreNotFound,
+  isStorePersistence,
+  toFeedbackUpdate
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../core/src/filters.ts","../../core/src/store-helpers.ts"],"sourcesContent":["/**\n * Shared feedback-record filtering and pagination — extracted from\n * `adapter-memory` and `adapter-localstorage` which previously kept two\n * near-identical copies of the same logic. Any adapter that holds an\n * in-memory snapshot of feedbacks can use it.\n *\n * Filtering order matches the historical adapter behaviour:\n *   1. projectName  (always required)\n *   2. type\n *   3. status / statuses  (`statuses` bucket wins when both are set)\n *   4. url\n *   5. urlPattern\n *   6. search       (lowercase substring match on `message`)\n *\n * Pagination clamps `limit` to a maximum of 100 and treats `page` as 1-based,\n * matching the public API contract documented on `getFeedbacks`. A page or\n * limit below 1 is clamped up to 1 rather than indexing backwards from the\n * end of the match set.\n */\n\nimport type { FeedbackQuery, FeedbackRecord } from \"./types.js\";\n\n/** Default page size when the caller omits `query.limit`. */\nconst DEFAULT_LIMIT = 50;\n/** Maximum allowed page size — defends against memory blow-ups on hostile callers. */\nconst MAX_LIMIT = 100;\n\nexport interface FilterResult {\n  feedbacks: FeedbackRecord[];\n  total: number;\n}\n\n/**\n * Apply the standard feedback filter + pagination pipeline against an\n * in-memory snapshot. Used by `MemoryStore.getFeedbacks` and\n * `LocalStorageStore.getFeedbacks` so the two never drift.\n *\n * @param items  All known feedback records (already include `annotations`).\n * @param query  Filter and pagination options. `projectName` is required.\n */\nexport function applyFeedbackFilters(items: readonly FeedbackRecord[], query: FeedbackQuery): FilterResult {\n  let results: FeedbackRecord[] = items.filter((f) => f.projectName === query.projectName);\n\n  if (query.type) results = results.filter((f) => f.type === query.type);\n  // `statuses` (bucket / any-of) wins over the exact `status` filter when both\n  // are present; an empty array is treated as absent.\n  if (query.statuses && query.statuses.length > 0) {\n    const allowed = query.statuses;\n    results = results.filter((f) => allowed.includes(f.status));\n  } else if (query.status) {\n    results = results.filter((f) => f.status === query.status);\n  }\n  if (query.url) results = results.filter((f) => f.url === query.url);\n  if (query.urlPattern) results = results.filter((f) => f.urlPattern === query.urlPattern);\n  if (query.search) {\n    const s = query.search.toLowerCase();\n    results = results.filter((f) => f.message.toLowerCase().includes(s));\n  }\n\n  // Newest first is part of the store contract (PrismaStore orders by\n  // createdAt desc) — sort explicitly instead of relying on insertion order.\n  // Array.prototype.sort is stable, so same-millisecond records keep their\n  // insertion order (newest inserted first).\n  results.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());\n\n  const total = results.length;\n  // Both bounds are clamped from below, not just `limit` from above:\n  // `(page - 1) * limit` goes negative for a non-positive page or limit, and\n  // `slice` reads negative indices from the END — so `page: -1` returned a\n  // window whose position depended on how many records happened to match,\n  // rather than an empty page or the first one. The Prisma adapter rejects\n  // these at the HTTP edge (`z.coerce.number().int().min(1)`), but the\n  // in-memory adapters have no schema in front of them and call straight in.\n  const page = Math.max(1, query.page ?? 1);\n  const limit = Math.max(1, Math.min(query.limit ?? DEFAULT_LIMIT, MAX_LIMIT));\n  const start = (page - 1) * limit;\n\n  return { feedbacks: results.slice(start, start + limit), total };\n}\n","/**\n * Record-construction helpers and the collection-store engine.\n *\n * Every snapshot-style adapter (memory, localStorage, flat file, KV, …)\n * needs the same three ingredients: turn a `FeedbackCreateInput` into a\n * `FeedbackRecord` (null-normalizing optional fields, stamping ids and\n * timestamps), filter/paginate with `applyFeedbackFilters`, and implement\n * the dedup/update/delete choreography of the `SitepingStore` contract.\n *\n * `buildFeedbackRecord` / `buildAnnotationRecord` cover the first part for\n * any adapter. `createCollectionStore` covers all of it: give it `load`,\n * `persist`, and `generateId`, and it returns a fully conformant\n * `SitepingStore` — writing a new snapshot adapter is ~20 lines plus its\n * storage specifics.\n */\n\nimport { applyFeedbackFilters } from \"./filters.js\";\nimport type {\n  AnnotationCreateInput,\n  AnnotationRecord,\n  FeedbackCreateInput,\n  FeedbackPage,\n  FeedbackQuery,\n  FeedbackRecord,\n  FeedbackUpdateInput,\n  SitepingStore,\n} from \"./types.js\";\nimport { StoreNotFoundError } from \"./types.js\";\n\n// ---------------------------------------------------------------------------\n// Record construction\n// ---------------------------------------------------------------------------\n\n/**\n * Build a persisted `AnnotationRecord` from its create input — normalizes\n * the optional anchor fields to `null` and stamps identity/timestamp.\n */\nexport function buildAnnotationRecord(\n  input: AnnotationCreateInput,\n  ctx: { id: string; feedbackId: string; now: Date },\n): AnnotationRecord {\n  return {\n    id: ctx.id,\n    feedbackId: ctx.feedbackId,\n    cssSelector: input.cssSelector,\n    xpath: input.xpath,\n    textSnippet: input.textSnippet,\n    elementTag: input.elementTag,\n    elementId: input.elementId ?? null,\n    textPrefix: input.textPrefix,\n    textSuffix: input.textSuffix,\n    fingerprint: input.fingerprint,\n    neighborText: input.neighborText,\n    anchorKey: input.anchorKey ?? null,\n    xPct: input.xPct,\n    yPct: input.yPct,\n    wPct: input.wPct,\n    hPct: input.hPct,\n    scrollX: input.scrollX,\n    scrollY: input.scrollY,\n    viewportW: input.viewportW,\n    viewportH: input.viewportH,\n    devicePixelRatio: input.devicePixelRatio,\n    createdAt: ctx.now,\n  };\n}\n\n/**\n * Build a persisted `FeedbackRecord` (with its annotations) from a create\n * input — normalizes every optional field to `null` and stamps ids and\n * timestamps. Adapters without external screenshot storage keep the data\n * URL inline on `screenshotUrl`, which is what this helper does; adapters\n * with a `ScreenshotStorage` upload first and override `screenshotUrl`.\n */\nexport function buildFeedbackRecord(\n  input: FeedbackCreateInput,\n  ctx: { id: string; annotationId: () => string; now?: Date },\n): FeedbackRecord {\n  const now = ctx.now ?? new Date();\n  return {\n    id: ctx.id,\n    type: input.type,\n    message: input.message,\n    status: input.status,\n    projectName: input.projectName,\n    url: input.url,\n    urlPattern: input.urlPattern ?? null,\n    authorName: input.authorName,\n    authorEmail: input.authorEmail,\n    viewport: input.viewport,\n    userAgent: input.userAgent,\n    clientId: input.clientId,\n    resolvedAt: null,\n    createdAt: now,\n    updatedAt: now,\n    annotations: input.annotations.map((ann) =>\n      buildAnnotationRecord(ann, { id: ctx.annotationId(), feedbackId: ctx.id, now }),\n    ),\n    screenshotUrl: input.screenshotDataUrl ?? null,\n    screenshotRegion: input.screenshotRegion ?? null,\n    diagnostics: input.diagnostics ?? null,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Collection-store engine\n// ---------------------------------------------------------------------------\n\n/**\n * Storage primitives behind a collection store. `load`/`persist` may be\n * sync or async — the engine awaits both, so in-memory arrays, localStorage\n * and async KV stores all fit the same three functions.\n */\nexport interface CollectionStoreBackend {\n  /** Return the current full snapshot of feedback records. */\n  load(): FeedbackRecord[] | Promise<FeedbackRecord[]>;\n  /**\n   * Persist the full snapshot. Throw `StorePersistenceError` when the write\n   * is lost (quota, storage disabled, …) — never swallow the failure.\n   */\n  persist(feedbacks: FeedbackRecord[]): void | Promise<void>;\n  /** Generate a unique id for a new feedback or annotation record. */\n  generateId(): string;\n}\n\n/**\n * A `SitepingStore` with the optional `verifyProjectOwnership` guaranteed —\n * what `createCollectionStore` returns.\n */\nexport type CollectionStore = SitepingStore & Required<Pick<SitepingStore, \"verifyProjectOwnership\">>;\n\n/**\n * Build a fully conformant `SitepingStore` on top of a snapshot backend.\n *\n * The engine implements the whole store contract: clientId dedup (idempotent\n * create), newest-first ordering, the standard filter/pagination pipeline,\n * `StoreNotFoundError` on missing update/delete, project-scoped bulk delete,\n * and `verifyProjectOwnership`. When `persist` fails during `createFeedback`\n * and the record carries an inline screenshot, the engine retries once\n * without the screenshot (by far the heaviest field) so the text feedback\n * survives a storage-quota hit; if that also fails, the error propagates —\n * returning the record would claim a success that was never persisted.\n *\n * @example\n * ```ts\n * export class MemoryStore implements SitepingStore {\n *   private feedbacks: FeedbackRecord[] = [];\n *   private readonly store = createCollectionStore({\n *     load: () => this.feedbacks,\n *     persist: (next) => {\n *       this.feedbacks = next;\n *     },\n *     generateId: () => crypto.randomUUID(),\n *   });\n *   createFeedback = this.store.createFeedback;\n *   // …delegate the remaining methods the same way\n * }\n * ```\n */\nexport function createCollectionStore(backend: CollectionStoreBackend): CollectionStore {\n  return {\n    async createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord> {\n      const feedbacks = await backend.load();\n\n      // ClientId dedup — idempotent\n      const existing = feedbacks.find((f) => f.clientId === data.clientId);\n      if (existing) return existing;\n\n      const record = buildFeedbackRecord(data, {\n        id: backend.generateId(),\n        annotationId: () => backend.generateId(),\n      });\n\n      feedbacks.unshift(record);\n      try {\n        await backend.persist(feedbacks);\n      } catch (err) {\n        if (!record.screenshotUrl) throw err;\n        record.screenshotUrl = null;\n        await backend.persist(feedbacks);\n      }\n      return record;\n    },\n\n    async getFeedbacks(query: FeedbackQuery): Promise<FeedbackPage> {\n      return applyFeedbackFilters(await backend.load(), query);\n    },\n\n    async findByClientId(clientId: string): Promise<FeedbackRecord | null> {\n      return (await backend.load()).find((f) => f.clientId === clientId) ?? null;\n    },\n\n    async updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord> {\n      const feedbacks = await backend.load();\n      const fb = feedbacks.find((f) => f.id === id);\n      if (!fb) throw new StoreNotFoundError();\n\n      fb.status = data.status;\n      fb.resolvedAt = data.resolvedAt;\n      fb.updatedAt = new Date();\n      await backend.persist(feedbacks);\n      return fb;\n    },\n\n    async deleteFeedback(id: string): Promise<void> {\n      const feedbacks = await backend.load();\n      const idx = feedbacks.findIndex((f) => f.id === id);\n      if (idx === -1) throw new StoreNotFoundError();\n\n      feedbacks.splice(idx, 1);\n      await backend.persist(feedbacks);\n    },\n\n    async deleteAllFeedbacks(projectName: string): Promise<void> {\n      const feedbacks = await backend.load();\n      await backend.persist(feedbacks.filter((f) => f.projectName !== projectName));\n    },\n\n    async verifyProjectOwnership(id: string, projectName: string): Promise<boolean> {\n      const fb = (await backend.load()).find((f) => f.id === id);\n      return fb !== undefined && fb.projectName === projectName;\n    },\n  };\n}\n"],"mappings":"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","names":[]}