@siteping/widget 0.9.13 → 0.9.15

package/dist/siteping-core.d.ts

@@ -8,4 +8,4 @@ export type { ScreenshotStorage } from "./screenshot-storage.js";
 export type { AssertEqual, Brand, DeepReadonly, IfEquals, KeysOfType, NonEmptyArray, Prettify, Replace, RequiredNonNull, } from "./type-utils.js";
 export { hasOwn, isRecord } from "./type-utils.js";
 export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, BuiltinLocale, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackPage, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, PageScope, RectData, SitepingConfig, SitepingDeepLinkOptions, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingTheme, SitepingUnsubscribe, } from "./types.js";
-export { BUILTIN_LOCALES, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isStoreDuplicate, isStoreNotFound, StoreDuplicateError, StoreNotFoundError, } from "./types.js";
+export { BUILTIN_LOCALES, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isStoreDuplicate, isStoreNotFound, isStorePersistence, StoreDuplicateError, StoreNotFoundError, StorePersistenceError, } from "./types.js";

package/dist/types.d.ts

@@ -57,8 +57,21 @@ export interface SitepingConfig {
     showAnnotationsToggle?: boolean | undefined;
     /** Accent color for the widget UI — defaults to '#0066ff' */
     accentColor?: string;
-    /** Show the widget even in production — defaults to false */
+    /**
+     * Render the widget even when it would normally be skipped — this bypasses
+     * BOTH the production-environment guard AND the mobile-viewport guard.
+     * Defaults to false. Use it for dedicated review tools, staging environments,
+     * or responsive testing where you always want the widget present.
+     */
     forceShow?: boolean;
+    /**
+     * Minimum viewport width (px) at or above which the widget renders. Below it,
+     * the widget is skipped and `onSkip("mobile")` fires. Defaults to `768`.
+     *
+     * Set lower (e.g. `0`) to allow narrow/mobile viewports, or use `forceShow`
+     * to bypass the viewport check entirely.
+     */
+    minViewportWidth?: number | undefined;
     /** Enable debug logging of lifecycle events — defaults to false */
     debug?: boolean;
     /** Color theme — defaults to 'light' */
@@ -148,6 +161,28 @@ export interface SitepingConfig {
      * `instance.focusFeedback(id)` explicitly.
      */
     deepLink?: boolean | SitepingDeepLinkOptions | undefined;
+    /**
+     * Automatically re-fetch feedbacks when the page changes during client-side
+     * (SPA) navigation. Enabled by default.
+     *
+     * The widget is normally mounted once (singleton) inside a persistent layout
+     * — e.g. a Next.js App Router `layout.tsx`, which does NOT remount on
+     * client-side navigation. Without this, init runs a single time and both the
+     * panel list and the page markers stay frozen on the page where the widget
+     * first mounted. With it on, the widget patches the History API
+     * (`pushState`/`replaceState`, which SPA routers call instead of triggering
+     * `popstate`) and listens for `popstate`/`hashchange`, then re-fetches when
+     * the scope key (`getPageScope().url` + template) actually changes.
+     *
+     * This re-fetches data only — it deliberately does NOT re-focus or re-scroll
+     * to an annotation (deep-link focus stays initial-load only; see `deepLink`),
+     * so normal browsing is never interrupted by a surprise scroll.
+     *
+     * - `true` (default) — watch navigation and re-fetch on route change.
+     * - `false` — never touch the History API; hosts drive updates manually via
+     *   `instance.refresh()`.
+     */
+    watchNavigation?: boolean | undefined;
     /**
      * Pre-fill author identity from the host application — typically the
      * currently signed-in user. When set, the widget uses these values
@@ -418,6 +453,16 @@ export declare class StoreDuplicateError extends Error {
     readonly code: "STORE_DUPLICATE";
     constructor(message?: string);
 }
+/**
+ * Thrown when a store accepts a mutation but cannot persist it — e.g.
+ * `localStorage` is full (QuotaExceededError). Adapters MUST throw this rather
+ * than swallow the failure, so callers learn the write was lost instead of
+ * seeing a phantom success.
+ */
+export declare class StorePersistenceError extends Error {
+    readonly code: "STORE_PERSISTENCE";
+    constructor(message?: string, options?: ErrorOptions);
+}
 /** Shape of any ORM error that carries a Prisma-style `code` field. */
 type CodedError<C extends string = string> = {
     code: C;
@@ -426,6 +471,13 @@ type CodedError<C extends string = string> = {
 export declare function isStoreNotFound(error: unknown): error is StoreNotFoundError | CodedError<"P2025">;
 /** Type guard — works for `StoreDuplicateError` and ORM-specific equivalents (e.g. Prisma P2002). */
 export declare function isStoreDuplicate(error: unknown): error is StoreDuplicateError | CodedError<"P2002">;
+/**
+ * Type guard for `StorePersistenceError`. Matches on the stable `code` field
+ * in addition to `instanceof`: every consumer package bundles its own copy of
+ * core (tsup `noExternal`), so an instance thrown by one package fails an
+ * `instanceof` check against another package's class identity.
+ */
+export declare function isStorePersistence(error: unknown): error is StorePersistenceError | CodedError<"STORE_PERSISTENCE">;
 /** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */
 export declare function flattenAnnotation(ann: AnnotationPayload): Prettify<AnnotationCreateInput>;
 /** Paginated result returned by `SitepingStore.getFeedbacks`. */
@@ -447,20 +499,23 @@ export interface FeedbackPage {
  * - **`createFeedback`**: either return the existing record on duplicate
  *   `clientId` (idempotent) or throw `StoreDuplicateError`. The handler
  *   handles both patterns.
+ * - **All mutations**: when a write is accepted but cannot be persisted
+ *   (e.g. storage quota), throw `StorePersistenceError` instead of reporting
+ *   a phantom success. Detect it with `isStorePersistence`.
  * - Other methods should not throw on empty results — return empty arrays or `null`.
  */
 export interface SitepingStore {
-    /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. */
+    /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. Throws `StorePersistenceError` when the write cannot be persisted. */
     createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
     /** Paginated query with optional filters. Returns empty array (not error) when no results. */
     getFeedbacks(query: FeedbackQuery): Promise<FeedbackPage>;
     /** Lookup by client-generated UUID. Returns `null` (not error) when not found. */
     findByClientId(clientId: string): Promise<FeedbackRecord | null>;
-    /** Update status/resolvedAt. Throws `StoreNotFoundError` if `id` does not exist. */
+    /** Update status/resolvedAt. Throws `StoreNotFoundError` if `id` does not exist, `StorePersistenceError` when the write cannot be persisted. */
     updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;
-    /** Delete a single record. Throws `StoreNotFoundError` if `id` does not exist. */
+    /** Delete a single record. Throws `StoreNotFoundError` if `id` does not exist, `StorePersistenceError` when the write cannot be persisted. */
     deleteFeedback(id: string): Promise<void>;
-    /** Bulk delete all feedbacks for a project. No-op (not error) if none exist. */
+    /** Bulk delete all feedbacks for a project. No-op (not error) if none exist. Throws `StorePersistenceError` when the write cannot be persisted. */
     deleteAllFeedbacks(projectName: string): Promise<void>;
 }
 /** Payload sent from the widget to the server when submitting feedback. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siteping/widget",
-  "version": "0.9.13",
+  "version": "0.9.15",
   "description": "Feedback widget for client review during development — annotations, bugs, questions directly on the site",
   "type": "module",
   "sideEffects": false,