helldots 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -48,9 +48,27 @@ export interface CommentContext {
   language: string;
 }
 
+/**
+ * Identifier of a comment or a reply.
+ *
+ * New ids are 21-character nanoid strings. The `number` arm is not legacy
+ * cruft to be removed later: comments created before that change are still
+ * sitting in hosts' localStorage and in their own back ends, and they keep
+ * resolving. Compare ids with `String(a) === String(b)` rather than `===`
+ * when either side may have crossed a JSON or URL boundary.
+ */
+export type CommentId = string | number;
+
 export interface SerializedComment {
-  id: number;
+  /**
+   * 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. */
+  editedAt?: string | null;
   anchor: CommentAnchor | null;
   /** location.pathname where the comment was created. */
   page: string;
@@ -82,26 +100,113 @@ 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 };
+  /**
+   * Query parameter carrying a comment id in "Copy link" URLs, and read back
+   * on startup to open that comment. Default: "helldotsComment". Override it
+   * 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. */
   onReplyAdded?: (comment: SerializedComment, reply: CommentReply) => void;
+  /** Fired after deleteReply removes a reply. */
+  onReplyDeleted?: (comment: SerializedComment, reply: CommentReply) => void;
+  /** Fired after editComment rewrites a comment's text. */
+  onCommentEdited?: (comment: SerializedComment) => void;
+  /** Fired after editReply rewrites a reply's text. */
+  onReplyEdited?: (comment: SerializedComment, reply: CommentReply) => void;
   /** Fired for each comment that could not be re-anchored by loadComments. */
   onAnchorLost?: (comment: SerializedComment) => void;
   /** Fired after deleteComment removes a comment. */
-  onCommentDeleted?: (id: number) => void;
+  onCommentDeleted?: (id: CommentId) => void;
   /** Fired after setCommentStatus changes a comment's lifecycle state. */
   onCommentStatusChanged?: (comment: SerializedComment) => void;
   /** Fired after type, priority or tags change on any comment. */
@@ -109,16 +214,20 @@ export interface CommentOverlayOptions {
 }
 
 export interface CommentReply {
-  id: number;
+  id: CommentId;
   text: string;
   author: string;
   timestamp: string;
   screenshots?: string[];
+  /** ISO timestamp of the last edit; null when never edited. */
+  editedAt?: string | null;
 }
 
 export interface Comment {
-  id: number;
+  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;
@@ -166,18 +275,50 @@ 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;
+  /** Rewrites a reply's text. Same contract as editComment. */
+  editReply(commentId: CommentId, replyId: CommentId, text: string): boolean;
+  /** The shareable URL for a comment, or null when the id is unknown. */
+  commentLink(id: CommentId): string | null;
   serializeComments(): SerializedComment[];
   loadComments(data: SerializedComment[]): {
     anchored: number;
     orphaned: number;
     inactive: number;
   };
-  deleteComment(id: number): boolean;
-  setCommentStatus(id: number, status: CommentStatus): boolean;
-  setCommentType(id: number, type: CommentType | null): boolean;
-  setCommentPriority(id: number, priority: CommentPriority | null): boolean;
-  setCommentTags(id: number, tags: string[]): boolean;
+  /**
+   * 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;
+  setCommentTags(id: CommentId, tags: string[]): boolean;
   cleanup(): void;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helldots",
-  "version": "0.3.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",
@@ -43,6 +43,7 @@
     "node": ">=18"
   },
   "scripts": {
+    "dev": "npx --yes serve -l 4173 .",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint .",
@@ -65,6 +66,7 @@
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.7.0",
     "jsdom": "^29.1.1",
+    "nanoid": "^6.0.1",
     "prettier": "^3.9.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"