helldots 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+export interface CommentAnchorFingerprint {
+  tagName: string;
+  /** First ~64 chars of the element's normalized textContent. */
+  textSnippet: string;
+  /** Stable attributes only (id, name, role, aria-label, non-framework data-*). */
+  attributes: Record<string, string>;
+  /** 0-based position among same-tag siblings at creation time. */
+  siblingIndex: number;
+  siblingCount: number;
+}
+
+export interface CommentAnchor {
+  version: 1;
+  /** Best-effort unique CSS selector, or null when none could be generated. */
+  selector: string | null;
+  /** Selector for the exact clicked element when deeper than the container. */
+  targetSelector?: string | null;
+  fingerprint: CommentAnchorFingerprint;
+  /** Fraction (0–1) of the anchor element's box, captured at creation. */
+  relativeX: number;
+  relativeY: number;
+}
+
+export type AnchorState = "anchored" | "orphaned" | "inactive";
+
+/** RF09 — comment lifecycle state. */
+export type CommentStatus = "open" | "in_progress" | "resolved";
+
+/** RF3 — comment category. `null` means deliberately unclassified. */
+export type CommentType = "bug" | "suggestion" | "question" | "improvement";
+
+/** RF4 — comment priority. `null` means deliberately unprioritised. */
+export type CommentPriority = "high" | "medium" | "low";
+
+/** RF2 — environment snapshot taken when the comment was created. */
+export interface CommentContext {
+  version: 1;
+  /** Full location.href at creation time. */
+  url: string;
+  viewport: { width: number; height: number };
+  /** Screen resolution (screen.width/height). */
+  screen: { width: number; height: number };
+  devicePixelRatio: number;
+  /** Raw UA — always stored, even when browser/os parsing fails. */
+  userAgent: string;
+  browser: { name: string; version: string };
+  os: { name: string; version: string };
+  language: string;
+}
+
+export interface SerializedComment {
+  id: number;
+  text: string;
+  anchor: CommentAnchor | null;
+  /** location.pathname where the comment was created. */
+  page: string;
+  replies: CommentReply[];
+  author: string;
+  createdAt: string;
+  screenshots: string[];
+  status: CommentStatus;
+  /** RF3 — `null` when deliberately unclassified. */
+  type: CommentType | null;
+  /** RF4 — `null` when deliberately unprioritised. */
+  priority: CommentPriority | null;
+  /**
+   * RF3 — free-form labels. `setCommentTags` normalises them (trimmed,
+   * lowercased, de-duplicated); values loaded via `loadComments` are
+   * trusted as-is and are not renormalised on read.
+   */
+  tags: string[];
+  /** RF5 — set on entering "resolved", cleared on leaving it. */
+  resolvedAt: string | null;
+  /** RF2 — environment snapshot taken at creation. */
+  context: CommentContext | null;
+  /** 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.
+   */
+  reactions?: Record<string, string[]>;
+}
+
+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";
+  /** 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 };
+  /** 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 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;
+  /** Fired after setCommentStatus changes a comment's lifecycle state. */
+  onCommentStatusChanged?: (comment: SerializedComment) => void;
+  /** Fired after type, priority or tags change on any comment. */
+  onCommentUpdated?: (comment: SerializedComment) => void;
+}
+
+export interface CommentReply {
+  id: number;
+  text: string;
+  author: string;
+  timestamp: string;
+  screenshots?: string[];
+}
+
+export interface Comment {
+  id: number;
+  text: string;
+  /** Live anchor element; null while the comment is orphaned or inactive. */
+  container: HTMLElement | null;
+  relativeX: number;
+  relativeY: number;
+  anchor: CommentAnchor | null;
+  anchorState: AnchorState;
+  /** Runtime-only: anchor element currently has zero size (not serialized). */
+  hidden: boolean;
+  /** Runtime-only: exact element the user clicked on (not serialized). */
+  target?: HTMLElement | null;
+  /** location.pathname where the comment was created. */
+  page: string;
+  replies: CommentReply[];
+  author: string;
+  createdAt: string;
+  screenshots: string[];
+  status: CommentStatus;
+  /** RF3 — `null` when deliberately unclassified. */
+  type: CommentType | null;
+  /** RF4 — `null` when deliberately unprioritised. */
+  priority: CommentPriority | null;
+  /**
+   * RF3 — free-form labels. `setCommentTags` normalises them (trimmed,
+   * lowercased, de-duplicated); values loaded via `loadComments` are
+   * trusted as-is and are not renormalised on read.
+   */
+  tags: string[];
+  /** RF5 — set on entering "resolved", cleared on leaving it. */
+  resolvedAt: string | null;
+  /** RF2 — environment snapshot taken at creation. */
+  context: CommentContext | null;
+  /** 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.
+   */
+  reactions?: Record<string, string[]>;
+}
+
+export declare class CommentOverlay {
+  comments: Comment[];
+  commentMode: boolean;
+
+  constructor(options?: Omit<CommentOverlayOptions, "autoInit">);
+
+  toggleCommentMode(): void;
+  addReply(comment: Comment, text: string): CommentReply;
+  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;
+  cleanup(): void;
+}
+
+/**
+ * Creates a CommentOverlay and mounts it. Safe to call before the document
+ * is ready — the instance defers its own DOM work to `DOMContentLoaded`.
+ */
+export declare function createCommentOverlay(
+  options?: CommentOverlayOptions & { autoInit?: true }
+): CommentOverlay;
+/**
+ * With `autoInit: false`, nothing is mounted yet: you get an initializer to
+ * call when you are ready.
+ */
+export declare function createCommentOverlay(
+  options: CommentOverlayOptions & { autoInit: false }
+): () => CommentOverlay;
+
+export default createCommentOverlay;

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "helldots",
+  "version": "0.3.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",
+    "annotations",
+    "feedback",
+    "bug-report",
+    "screenshot",
+    "overlay",
+    "review",
+    "shadow-dom",
+    "widget"
+  ],
+  "homepage": "https://github.com/xKeCo/helldots#readme",
+  "bugs": {
+    "url": "https://github.com/xKeCo/helldots/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xKeCo/helldots.git"
+  },
+  "author": "xKeCo <kevcollazos@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/helldots.esm.js",
+      "default": "./dist/helldots.esm.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "unpkg": "dist/helldots.umd.js",
+  "jsdelivr": "dist/helldots.umd.js",
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "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",
+    "prepublishOnly": "npm run verify",
+    "changeset": "changeset",
+    "release": "changeset version"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.1.9",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.6.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.7.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.9.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "modern-screenshot": "^4.7.0"
+  }
+}