helldots 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -60,6 +60,11 @@ export interface CommentContext {
 export type CommentId = string | number;
 
 export interface SerializedComment {
+  /**
+   * Version of this serialized shape. Stamped as 1 by serializeComments;
+   * optional because payloads persisted before it existed have none.
+   */
+  schemaVersion?: number;
   id: CommentId;
   text: string;
   /** ISO timestamp of the last edit; null when never edited. */
@@ -95,16 +100,70 @@ export interface SerializedComment {
   reactions?: Record<string, string[]>;
 }
 
+/**
+ * Everything that can change, as one discriminated union. Switch on `type`
+ * and TypeScript narrows the rest of the fields for you.
+ *
+ * The nine specific callbacks below carry exactly the same events at
+ * exactly the same moments; subscribe either way, or both.
+ */
+export type ChangeEvent =
+  | { type: "comment:created"; comment: SerializedComment }
+  | { type: "comment:edited"; comment: SerializedComment }
+  | { type: "comment:deleted"; id: CommentId }
+  | { type: "comment:status-changed"; comment: SerializedComment }
+  /** Type, priority or tags changed. */
+  | { type: "comment:updated"; comment: SerializedComment }
+  | { type: "comment:anchor-lost"; comment: SerializedComment }
+  | {
+      type: "reply:added";
+      comment: SerializedComment;
+      reply: CommentReply;
+    }
+  | {
+      type: "reply:deleted";
+      comment: SerializedComment;
+      reply: CommentReply;
+    }
+  | {
+      type: "reply:edited";
+      comment: SerializedComment;
+      reply: CommentReply;
+    };
+
 export interface CommentOverlayOptions {
   shortcutKey?: string;
   shortcutModifier?: "alt" | "ctrl" | "shift";
   autoInit?: boolean;
-  /** UI language. Defaults to the browser's language when supported, else "en". */
-  locale?: "en" | "es";
+  /**
+   * UI language. "en" and "es" ship today; any other value falls back to
+   * English (and a locale missing individual keys falls back per key).
+   * Typed as string so a host can pass a runtime-detected code without a
+   * cast — an unknown code degrades, it never breaks.
+   */
+  locale?: string;
   /** Auto save/restore comments. Default: "none" (host app persists via callbacks). */
   persistence?: "localStorage" | "none";
   /** Capture a viewport screenshot and environment snapshot on every new comment. Default: true. */
   autoScreenshot?: boolean;
+  /**
+   * Fetch stylesheets the renderer cannot read, so their web fonts survive
+   * into screenshots. Default: false.
+   *
+   * A cross-origin `<link>` (Google Fonts and friends) throws `SecurityError`
+   * on `cssRules`, so its `@font-face` never reaches the capture and the text
+   * is rendered in a fallback face. The fallback's metrics differ, which
+   * shifts glyphs sideways — a drag selection tight around a few letters then
+   * comes back holding the wrong ones. Enabling this re-fetches those sheets
+   * (the same URLs the page already loaded, cached per session) so the
+   * capture matches the page.
+   *
+   * Off by default because a comment widget making third-party requests
+   * should be the host's decision. Leave it off and captures of such a page
+   * stay misaligned; a host can also fix it at the source by self-hosting the
+   * font or adding `crossorigin` to the `<link>`.
+   */
+  embedCrossOriginFonts?: boolean;
   /** Identity used as the author of new comments and replies. */
   user?: { name: string };
   /**
@@ -113,6 +172,27 @@ export interface CommentOverlayOptions {
    * when the host already routes on that name.
    */
   linkParam?: string;
+  /**
+   * Called instead of a full-page load when the widget navigates to another
+   * page (the inbox's "view on its page" jump). Hand it your SPA router's
+   * push so the app's state survives; call `notifyNavigation()` after the
+   * route renders.
+   */
+  navigate?: (page: string) => void;
+  /**
+   * Run `notifyNavigation()` automatically on popstate (back/forward).
+   * Opt-in and popstate-only: pushState routing still needs an explicit
+   * `notifyNavigation()` call from the router's hook. Default: false.
+   */
+  autoDetectNavigation?: boolean;
+  /**
+   * Single subscription point: fires for every change, alongside whichever
+   * specific callback below carries the same event. Handy when a host syncs
+   * everything to one endpoint instead of wiring nine functions. A handler
+   * that throws is caught and warned about — it never rolls back the
+   * mutation that emitted it.
+   */
+  onChange?: (event: ChangeEvent) => void;
   /** Fired after a new comment is saved. */
   onCommentCreated?: (comment: SerializedComment) => void;
   /** Fired after a reply is added to any comment. */
@@ -146,6 +226,8 @@ export interface CommentReply {
 export interface Comment {
   id: CommentId;
   text: string;
+  /** ISO timestamp of the last edit; null when never edited. */
+  editedAt?: string | null;
   /** Live anchor element; null while the comment is orphaned or inactive. */
   container: HTMLElement | null;
   relativeX: number;
@@ -193,7 +275,15 @@ export declare class CommentOverlay {
   constructor(options?: Omit<CommentOverlayOptions, "autoInit">);
 
   toggleCommentMode(): void;
-  addReply(comment: Comment, text: string): CommentReply;
+  /**
+   * `screenshots` are data-URLs attached to the reply. Takes the live
+   * comment or its id; null when an id does not resolve.
+   */
+  addReply(
+    comment: Comment | CommentId,
+    text: string,
+    screenshots?: string[]
+  ): CommentReply | null;
   deleteReply(commentId: CommentId, replyId: CommentId): boolean;
   /** Rewrites a comment's text. False when the id is unknown, the text is blank, or nothing changed. */
   editComment(id: CommentId, text: string): boolean;
@@ -207,7 +297,24 @@ export declare class CommentOverlay {
     orphaned: number;
     inactive: number;
   };
+  /**
+   * Re-syncs the widget after a client-side navigation: reclassifies every
+   * comment against the new pathname, re-resolves anchors against the new
+   * DOM, rebuilds markers and moves the inbox onto the new page. Also the
+   * "re-anchor now" primitive for same-path re-renders.
+   */
+  notifyNavigation(): {
+    anchored: number;
+    orphaned: number;
+    inactive: number;
+  };
   deleteComment(id: CommentId): boolean;
+  /**
+   * Removes every comment at once (markers, memory, and their persisted
+   * entries in localStorage mode). A bulk reset for reconciling against a
+   * backend before loadComments — fires no per-comment callbacks.
+   */
+  clearComments(): void;
   setCommentStatus(id: CommentId, status: CommentStatus): boolean;
   setCommentType(id: CommentId, type: CommentType | null): boolean;
   setCommentPriority(id: CommentId, priority: CommentPriority | null): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helldots",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Drop-in comment overlay for web apps — click anywhere to leave a comment anchored to that element, with an automatic screenshot and environment capture",
   "keywords": [
     "comments",