helldots 0.4.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;
@@ -60,6 +126,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. */
@@ -67,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;
@@ -89,30 +183,124 @@ 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 ten 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;
+    }
+  /** `reply` is null when the reaction is on the root comment. */
+  | {
+      type: "reaction:toggled";
+      comment: SerializedComment;
+      reply: CommentReply | null;
+    };
+
 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;
-  /** Identity used as the author of new comments and replies. */
-  user?: { name: string };
+  /**
+   * 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.
+   *
+   * `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
    * 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. */
@@ -131,21 +319,49 @@ 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 {
   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;
@@ -158,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;
@@ -180,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 {
@@ -193,7 +434,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,11 +456,62 @@ 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;
+  /**
+   * 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.4.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",