@siteping/widget 0.9.6 → 0.9.7

package/dist/schema.d.ts

@@ -62,6 +62,15 @@ export declare const SITEPING_MODELS: Readonly<{
             readonly url: {
                 readonly type: "String";
             };
+            readonly urlPattern: {
+                readonly type: "String";
+                readonly optional: true;
+            };
+            readonly screenshotUrl: {
+                readonly type: "String";
+                readonly optional: true;
+                readonly nativeType: "Text";
+            };
             readonly viewport: {
                 readonly type: "String";
             };
@@ -102,6 +111,8 @@ export declare const SITEPING_MODELS: Readonly<{
             readonly fields: ["projectName"];
         }, {
             readonly fields: ["projectName", "status", "createdAt"];
+        }, {
+            readonly fields: ["projectName", "url"];
         }];
     };
     readonly SitepingAnnotation: {
@@ -158,6 +169,10 @@ export declare const SITEPING_MODELS: Readonly<{
                 readonly type: "String";
                 readonly nativeType: "Text";
             };
+            readonly anchorKey: {
+                readonly type: "String";
+                readonly optional: true;
+            };
             readonly xPct: {
                 readonly type: "Float";
             };

package/dist/siteping-core.d.ts

@@ -1,4 +1,5 @@
 export type { FieldDef, IndexDef, ModelDef } from "./schema.js";
 export { SITEPING_MODELS } from "./schema.js";
-export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, FeedbackCreateInput, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackStatus, FeedbackType, FeedbackUpdateInput, RectData, SitepingConfig, SitepingInstance, SitepingPublicEvents, SitepingStore, } from "./types.js";
+export type { ScreenshotStorage } from "./screenshot-storage.js";
+export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, FeedbackCreateInput, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackStatus, FeedbackType, FeedbackUpdateInput, PageScope, RectData, SitepingConfig, SitepingInstance, SitepingPublicEvents, SitepingStore, } from "./types.js";
 export { FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isStoreDuplicate, isStoreNotFound, StoreDuplicateError, StoreNotFoundError, } from "./types.js";

package/dist/types.d.ts

@@ -18,6 +18,45 @@ export interface SitepingConfig {
     theme?: "light" | "dark" | "auto";
     /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru. Any other string falls back to English. */
     locale?: "en" | "fr" | "de" | "es" | "it" | "pt" | "ru" | (string & {}) | undefined;
+    /**
+     * Returns the current page scope for annotations and panel filtering.
+     * Called on initial markers load and on `instance.refresh()`.
+     *
+     * Default: `{ url: window.location.pathname, urlPattern: null }` — annotations
+     * are scoped strictly to the current pathname.
+     *
+     * Apps with parameterized routes (e.g. React Router) should return both the
+     * concrete URL and the route template (e.g. `/orders/:orderId`) so the panel
+     * can offer a "this type of page" filter that groups feedbacks by template.
+     */
+    getPageScope?: (() => PageScope) | undefined;
+    /**
+     * When true (default), the widget filters initial markers and panel results
+     * by `feedback.url === scope.url`, so annotations created on one page never
+     * leak to other pages — even if their CSS selector accidentally matches.
+     * Set to `false` to revert to the legacy project-wide behavior.
+     */
+    scopeAnnotationsByUrl?: boolean | undefined;
+    /**
+     * Capture a JPEG screenshot of the annotated area on submit. Defaults to
+     * `false` — opt-in because:
+     *
+     * - it adds runtime weight (~40 KB gzip dynamic chunk for html2canvas,
+     *   loaded only on first capture),
+     * - it embeds page content in the feedback (privacy/GDPR consideration —
+     *   inform end users in your widget host UI when enabling).
+     *
+     * `html2canvas` ships as a regular dependency of `@siteping/widget` so the
+     * dynamic import always resolves; you don't need to install anything extra.
+     *
+     * **Masking sensitive elements:** add `data-siteping-ignore="true"` to any
+     * element you do NOT want captured (password fields, credit-card forms,
+     * API tokens shown in the UI, etc.). The capture predicate skips matching
+     * elements *and their descendants*. Do this BEFORE turning on screenshots
+     * in production — once a feedback is saved, the screenshot is in your DB
+     * (or object storage) regardless of what was on the page.
+     */
+    enableScreenshot?: boolean | undefined;
     /** Called when the widget is skipped (production mode, mobile viewport) */
     onSkip?: (reason: "production" | "mobile") => void;
     /** Called when the feedback panel is opened. */
@@ -59,6 +98,19 @@ export type FeedbackType = (typeof FEEDBACK_TYPES)[number];
 /** Single source of truth for feedback statuses. */
 export declare const FEEDBACK_STATUSES: readonly ["open", "resolved"];
 export type FeedbackStatus = (typeof FEEDBACK_STATUSES)[number];
+/**
+ * Page scope returned by `SitepingConfig.getPageScope()`.
+ *
+ * - `url`: concrete page identifier — usually `window.location.pathname`,
+ *   used as the strict scope for marker rendering.
+ * - `urlPattern`: optional parameterized template (e.g. `/orders/:orderId`)
+ *   used by the panel's "this type of page" filter to group feedbacks across
+ *   instances of the same page kind.
+ */
+export interface PageScope {
+    url: string;
+    urlPattern: string | null;
+}
 /** Input for creating a feedback record in the store. */
 export interface FeedbackCreateInput {
     projectName: string;
@@ -66,12 +118,28 @@ export interface FeedbackCreateInput {
     message: string;
     status: FeedbackStatus;
     url: string;
+    /**
+     * Optional parameterized URL template (e.g. `/orders/:orderId`) for the page
+     * where the feedback was created. Allows the panel to filter feedbacks by
+     * "this type of page" across different instances. Null when the host did not
+     * provide a `getPageScope` callback or the route has no template.
+     */
+    urlPattern?: string | null | undefined;
     viewport: string;
     userAgent: string;
     authorName: string;
     authorEmail: string;
     clientId: string;
     annotations: AnnotationCreateInput[];
+    /**
+     * Base64 JPEG `data:` URL captured by the widget at submit time.
+     *
+     * Adapters with a configured `ScreenshotStorage` are expected to upload
+     * this and persist the returned URL on `FeedbackRecord.screenshotUrl`.
+     * Adapters without storage may persist the data URL inline (memory /
+     * localStorage / dev) — the widget then renders it directly.
+     */
+    screenshotDataUrl?: string | null | undefined;
 }
 /** Input for a single annotation when creating a feedback. */
 export interface AnnotationCreateInput {
@@ -84,6 +152,13 @@ export interface AnnotationCreateInput {
     textSuffix: string;
     fingerprint: string;
     neighborText: string;
+    /**
+     * Semantic anchor identifier from the closest ancestor's `data-feedback-anchor`
+     * attribute. When set, this is the most stable re-anchoring signal because
+     * hosts deliberately place these on layout/section roots that survive DOM
+     * refactors and viewport changes. Null when no semantic ancestor exists.
+     */
+    anchorKey?: string | null | undefined;
     xPct: number;
     yPct: number;
     wPct: number;
@@ -102,6 +177,17 @@ export interface FeedbackQuery {
     search?: string | undefined;
     page?: number | undefined;
     limit?: number | undefined;
+    /**
+     * Filter to feedbacks created on this exact URL (path). Used by the panel's
+     * "this page" filter and by the markers loader to keep page scopes isolated.
+     */
+    url?: string | undefined;
+    /**
+     * Filter to feedbacks created on this URL pattern (e.g. `/orders/:orderId`).
+     * Used by the panel's "this type of page" filter to group feedbacks across
+     * different concrete instances of the same template.
+     */
+    urlPattern?: string | undefined;
 }
 /** Update payload for patching a feedback. */
 export interface FeedbackUpdateInput {
@@ -116,6 +202,11 @@ export interface FeedbackRecord {
     status: FeedbackStatus;
     projectName: string;
     url: string;
+    /**
+     * Parameterized URL template the feedback was created on.
+     * Null for legacy records or hosts without `getPageScope`.
+     */
+    urlPattern: string | null;
     authorName: string;
     authorEmail: string;
     viewport: string;
@@ -125,6 +216,13 @@ export interface FeedbackRecord {
     createdAt: Date;
     updatedAt: Date;
     annotations: AnnotationRecord[];
+    /**
+     * URL the widget renders as `<img src>`. Either an `https://...` from a
+     * configured `ScreenshotStorage`, or a `data:image/jpeg;base64,...` URL
+     * inline-persisted by adapters without storage. Null when no screenshot
+     * was captured (legacy records, capture failed, or host disabled it).
+     */
+    screenshotUrl: string | null;
 }
 /** A persisted annotation record returned by the store. */
 export interface AnnotationRecord {
@@ -139,6 +237,11 @@ export interface AnnotationRecord {
     textSuffix: string;
     fingerprint: string;
     neighborText: string;
+    /**
+     * Semantic anchor identifier from `data-feedback-anchor`. Null for legacy
+     * annotations or those drawn outside any anchored region.
+     */
+    anchorKey: string | null;
     xPct: number;
     yPct: number;
     wPct: number;
@@ -214,6 +317,11 @@ export interface FeedbackPayload {
     type: FeedbackType;
     message: string;
     url: string;
+    /**
+     * Parameterized URL template (e.g. `/orders/:orderId`) supplied by
+     * `SitepingConfig.getPageScope()`. Null when the host did not provide one.
+     */
+    urlPattern?: string | null | undefined;
     viewport: string;
     userAgent: string;
     authorName: string;
@@ -221,6 +329,12 @@ export interface FeedbackPayload {
     annotations: AnnotationPayload[];
     /** Client-generated UUID for deduplication */
     clientId: string;
+    /**
+     * Base64 JPEG `data:` URL of the annotated area. Captured by the widget
+     * when `enableScreenshot: true` is set in `SitepingConfig`. Null when
+     * disabled or when capture failed silently.
+     */
+    screenshotDataUrl?: string | null | undefined;
 }
 /** DOM anchoring data for re-attaching annotations to page elements. */
 export interface AnchorData {
@@ -242,6 +356,13 @@ export interface AnchorData {
     fingerprint: string;
     /** Text content of adjacent sibling elements (context) */
     neighborText: string;
+    /**
+     * Semantic anchor identifier from the closest ancestor's `data-feedback-anchor`
+     * attribute. When set, this is the highest-priority re-anchoring signal —
+     * hosts deliberately place these on layout/section roots that survive
+     * viewport changes and DOM refactors.
+     */
+    anchorKey?: string | null | undefined;
 }
 /** Drawn rectangle coordinates as percentages relative to the anchor element. */
 export interface RectData {
@@ -272,6 +393,8 @@ export interface FeedbackResponse {
     message: string;
     status: FeedbackStatus;
     url: string;
+    /** Parameterized URL template the feedback was created on, or null. */
+    urlPattern: string | null;
     viewport: string;
     userAgent: string;
     authorName: string;
@@ -280,6 +403,8 @@ export interface FeedbackResponse {
     createdAt: string;
     updatedAt: string;
     annotations: AnnotationResponse[];
+    /** Screenshot URL (data: or http:) — see `FeedbackRecord.screenshotUrl`. */
+    screenshotUrl: string | null;
 }
 /** Annotation record as returned by the API. */
 export interface AnnotationResponse {
@@ -294,6 +419,8 @@ export interface AnnotationResponse {
     textSuffix: string;
     fingerprint: string;
     neighborText: string;
+    /** Semantic anchor identifier from `data-feedback-anchor`, or null. */
+    anchorKey: string | null;
     xPct: number;
     yPct: number;
     wPct: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siteping/widget",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Feedback widget for client review during development — annotations, bugs, questions directly on the site",
   "type": "module",
   "sideEffects": false,
@@ -53,6 +53,9 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "html2canvas": "^1.4.1"
+  },
   "devDependencies": {
     "@medv/finder": "^3.2.0",
     "@siteping/core": "workspace:*"