helldots 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -48,9 +48,22 @@ 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;
+  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;
@@ -94,14 +107,26 @@ export interface CommentOverlayOptions {
   autoScreenshot?: 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;
   /** 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,15 +134,17 @@ 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;
   /** Live anchor element; null while the comment is orphaned or inactive. */
   container: HTMLElement | null;
@@ -167,17 +194,24 @@ export declare class CommentOverlay {
 
   toggleCommentMode(): void;
   addReply(comment: Comment, text: string): CommentReply;
+  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;
+  deleteComment(id: CommentId): boolean;
+  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.4.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"