helldots 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export interface CommentAnchor {
 export type AnchorState = "anchored" | "orphaned" | "inactive";
 
 /** RF09 — comment lifecycle state. */
-export type CommentStatus = "open" | "in_progress" | "resolved";
+export type CommentStatus = "open" | "in_progress" | "in_review" | "resolved";
 
 /** RF3 — comment category. `null` means deliberately unclassified. */
 export type CommentType = "bug" | "suggestion" | "question" | "improvement";
@@ -32,6 +32,72 @@ export type CommentType = "bug" | "suggestion" | "question" | "improvement";
 /** RF4 — comment priority. `null` means deliberately unprioritised. */
 export type CommentPriority = "high" | "medium" | "low";
 
+/**
+ * Aggregate figures over a corpus of comments. Every bucket is present even
+ * when empty, so a consumer can index it without guarding — an absent key and
+ * a zero would otherwise be indistinguishable.
+ */
+export interface CommentMetrics {
+  total: number;
+  byStatus: Record<CommentStatus, number>;
+  /** `unset` holds the comments left deliberately unclassified. */
+  byType: Record<CommentType | "unset", number>;
+  /** `unset` holds the comments left deliberately unprioritised. */
+  byPriority: Record<CommentPriority | "unset", number>;
+  /**
+   * Comments created per day, oldest first, in `YYYY-MM-DD`. Only days that
+   * saw activity get an entry: filling the gaps would put a year of empty
+   * buckets between two comments twelve months apart.
+   */
+  overTime: Array<{ date: string; count: number }>;
+  resolution: {
+    resolvedCount: number;
+    /** Comments that were resolved, reopened and resolved again. */
+    reopenedCount: number;
+    /** Mean and median of the resolution currently in force, or null when nothing is resolved. */
+    averageMs: number | null;
+    medianMs: number | null;
+  };
+}
+
+/** Who performed an audited action, as the host declared them at the time. */
+export interface AuditActor {
+  /** From `user.id`, when the host supplies one. Never rendered. */
+  id?: string;
+  /** The display name at the time of the action. */
+  name: string;
+}
+
+/**
+ * The four actions worth auditing. Replies carry their own author and
+ * timestamp already, and reactions are high-frequency signal with no audit
+ * value — neither produces an entry.
+ */
+export type AuditEventType = "created" | "edited" | "status" | "classified";
+
+/** One entry of a comment's append-only audit trail. */
+export interface AuditEvent {
+  type: AuditEventType;
+  /**
+   * ISO timestamp, from the acting client's clock. Merge corpora written on
+   * machines whose clocks disagree and an entry can predate the comment it
+   * belongs to; durations derived from these are clamped at zero rather than
+   * rendered negative.
+   */
+  at: string;
+  actor: AuditActor;
+  /** "classified" only: which field moved. */
+  field?: "type" | "priority" | "tags";
+  /**
+   * Both ends of the transition, for "status" and for "classified" on type or
+   * priority. `null` is a value, not an absence — it is how type and priority
+   * read when deliberately unset. Absent for "created", "edited", and for a
+   * tag change, which is a list with no two-value transition.
+   */
+  from?: string | null;
+  to?: string | null;
+}
+
 /** RF2 — environment snapshot taken when the comment was created. */
 export interface CommentContext {
   version: 1;
@@ -72,8 +138,31 @@ export interface SerializedComment {
   anchor: CommentAnchor | null;
   /** location.pathname where the comment was created. */
   page: string;
+  /**
+   * Append-only audit trail: who created, edited, moved or reclassified this
+   * comment, and when. Optional and absent by default — records written
+   * before it existed simply have none, so no migration is involved, and
+   * `null` rather than `[]` keeps an untouched corpus free of extra bytes.
+   *
+   * Every resolution the comment has had is derivable from the `status`
+   * entries, which is why no separate resolution history is stored.
+   */
+  history?: AuditEvent[] | null;
   replies: CommentReply[];
   author: string;
+  /**
+   * Stable identifier of the author, from the `user.id` the host supplied at
+   * creation. Optional and absent by default: records written before it
+   * existed simply have none, so no migration is involved.
+   *
+   * Never rendered — `author` is the display name and stays what any UI
+   * shows — it travels with the record, so a store that holds nothing but
+   * comments renders every author without a lookup. The id is opaque to
+   * HellDots: whether it points into the host's user table, into a
+   * comments-only database, or nowhere at all is the host's business. What it
+   * buys is telling two teammates who share a display name apart.
+   */
+  authorId?: string | null;
   createdAt: string;
   screenshots: string[];
   status: CommentStatus;
@@ -94,17 +183,19 @@ export interface SerializedComment {
   /** RF1 — automatic viewport capture (JPEG data-URL). */
   contextScreenshot: string | null;
   /**
-   * RF6 — emoji → authors who reacted. Reserved, not implemented yet.
-   * Optional and absent by default, so shipping it later needs no migration.
+   * RF6 — emoji → the actor keys that reacted (see the `user` option). Always
+   * one of the six emoji in the fixed set; anything else is dropped on load.
+   * Null when nobody has reacted, so an untouched corpus carries no extra
+   * payload.
    */
-  reactions?: Record<string, string[]>;
+  reactions: Record<string, string[]> | null;
 }
 
 /**
  * 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
+ * The ten specific callbacks below carry exactly the same events at
  * exactly the same moments; subscribe either way, or both.
  */
 export type ChangeEvent =
@@ -129,6 +220,12 @@ export type ChangeEvent =
       type: "reply:edited";
       comment: SerializedComment;
       reply: CommentReply;
+    }
+  /** `reply` is null when the reaction is on the root comment. */
+  | {
+      type: "reaction:toggled";
+      comment: SerializedComment;
+      reply: CommentReply | null;
     };
 
 export interface CommentOverlayOptions {
@@ -164,8 +261,19 @@ export interface CommentOverlayOptions {
    * font or adding `crossorigin` to the `<link>`.
    */
   embedCrossOriginFonts?: boolean;
-  /** Identity used as the author of new comments and replies. */
-  user?: { name: string };
+  /**
+   * Identity used as the author of new comments and replies.
+   *
+   * `name` is what gets displayed. `id` is optional and never rendered: it
+   * is persisted as `authorId` on the comments and replies this user creates,
+   * and it is what a reaction is keyed on — so two teammates who share a
+   * display name are still told apart. Without it the name is used, and
+   * without any `user` at all every actor collapses into one.
+   *
+   * HellDots authenticates nobody: whatever the host declares here is taken
+   * at face value and recorded as-is.
+   */
+  user?: { name: string; id?: string };
   /**
    * Query parameter carrying a comment id in "Copy link" URLs, and read back
    * on startup to open that comment. Default: "helldotsComment". Override it
@@ -211,16 +319,42 @@ export interface CommentOverlayOptions {
   onCommentStatusChanged?: (comment: SerializedComment) => void;
   /** Fired after type, priority or tags change on any comment. */
   onCommentUpdated?: (comment: SerializedComment) => void;
+  /**
+   * Fired after a reaction is added to or removed from a comment or a reply.
+   * `reply` is null when the reaction is on the root comment.
+   */
+  onReactionToggled?: (
+    comment: SerializedComment,
+    reply: CommentReply | null
+  ) => void;
 }
 
 export interface CommentReply {
   id: CommentId;
   text: string;
   author: string;
+  /**
+   * Stable identifier of the author, from the `user.id` the host supplied at
+   * creation. Optional and absent by default: records written before it
+   * existed simply have none, so no migration is involved.
+   *
+   * Never rendered — `author` is the display name and stays what any UI
+   * shows — it travels with the record, so a store that holds nothing but
+   * comments renders every author without a lookup. The id is opaque to
+   * HellDots: whether it points into the host's user table, into a
+   * comments-only database, or nowhere at all is the host's business. What it
+   * buys is telling two teammates who share a display name apart.
+   */
+  authorId?: string | null;
   timestamp: string;
   screenshots?: string[];
   /** ISO timestamp of the last edit; null when never edited. */
   editedAt?: string | null;
+  /**
+   * RF6 — emoji → the actor keys that reacted. Same shape and same rules as a
+   * comment's; null when nobody has reacted.
+   */
+  reactions?: Record<string, string[]> | null;
 }
 
 export interface Comment {
@@ -240,8 +374,31 @@ export interface Comment {
   target?: HTMLElement | null;
   /** location.pathname where the comment was created. */
   page: string;
+  /**
+   * Append-only audit trail: who created, edited, moved or reclassified this
+   * comment, and when. Optional and absent by default — records written
+   * before it existed simply have none, so no migration is involved, and
+   * `null` rather than `[]` keeps an untouched corpus free of extra bytes.
+   *
+   * Every resolution the comment has had is derivable from the `status`
+   * entries, which is why no separate resolution history is stored.
+   */
+  history?: AuditEvent[] | null;
   replies: CommentReply[];
   author: string;
+  /**
+   * Stable identifier of the author, from the `user.id` the host supplied at
+   * creation. Optional and absent by default: records written before it
+   * existed simply have none, so no migration is involved.
+   *
+   * Never rendered — `author` is the display name and stays what any UI
+   * shows — it travels with the record, so a store that holds nothing but
+   * comments renders every author without a lookup. The id is opaque to
+   * HellDots: whether it points into the host's user table, into a
+   * comments-only database, or nowhere at all is the host's business. What it
+   * buys is telling two teammates who share a display name apart.
+   */
+  authorId?: string | null;
   createdAt: string;
   screenshots: string[];
   status: CommentStatus;
@@ -262,10 +419,12 @@ export interface Comment {
   /** RF1 — automatic viewport capture (JPEG data-URL). */
   contextScreenshot: string | null;
   /**
-   * RF6 — emoji → authors who reacted. Reserved, not implemented yet.
-   * Optional and absent by default, so shipping it later needs no migration.
+   * RF6 — emoji → the actor keys that reacted (see the `user` option). Always
+   * one of the six emoji in the fixed set; anything else is dropped on load.
+   * Null when nobody has reacted, so an untouched corpus carries no extra
+   * payload.
    */
-  reactions?: Record<string, string[]>;
+  reactions: Record<string, string[]> | null;
 }
 
 export declare class CommentOverlay {
@@ -315,10 +474,44 @@ export declare class CommentOverlay {
    * backend before loadComments — fires no per-comment callbacks.
    */
   clearComments(): void;
+  /**
+   * Aggregate figures over every comment the widget holds. Unfiltered: the
+   * dashboard inside the inbox measures whatever that panel is showing, but a
+   * host has no notion of those filters.
+   */
+  getMetrics(): CommentMetrics;
+  /**
+   * Downloads the corpus as CSV, one row per comment. Screenshots and the
+   * automatic context capture stay out. Defaults to every comment.
+   */
+  exportCommentsCsv(comments?: SerializedComment[]): void;
+  /**
+   * Downloads the aggregate figures as CSV in long format — `section, key,
+   * value` — so the column count does not change with the corpus.
+   */
+  exportMetricsCsv(comments?: SerializedComment[]): void;
+  /**
+   * Opens the browser's print dialog on a report of the figures, which is
+   * where "save as PDF" lives. The report is built in its own document, so
+   * what prints is the report rather than the host page.
+   */
+  printMetricsReport(comments?: SerializedComment[], scope?: string): 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;
+  /**
+   * RF6 — flips the current actor's reaction on a comment: present, it is
+   * removed; absent, it is added. The actor is `user.id ?? user.name`.
+   * Returns false when the id or the emoji is unknown.
+   */
+  toggleCommentReaction(id: CommentId, emoji: string): boolean;
+  /** Same contract as toggleCommentReaction, one level down. */
+  toggleReplyReaction(
+    commentId: CommentId,
+    replyId: CommentId,
+    emoji: string
+  ): boolean;
   cleanup(): void;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helldots",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -53,9 +53,11 @@
     "build": "node scripts/build.mjs",
     "size": "node scripts/check-size.mjs",
     "verify": "npm run lint && npm run typecheck && npm run format:check && npm test && npm run build && npm run size",
+    "check:commit": "node scripts/check-commit-msg.mjs",
     "prepublishOnly": "npm run verify",
     "changeset": "changeset",
-    "release": "changeset version"
+    "release": "changeset version",
+    "prepare": "node scripts/install-hooks.mjs"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",