Types

import type {
  Comment,
  SerializedComment,
  CommentReply,
  CommentAnchor,
  CommentAnchorFingerprint,
  CommentContext,
  CommentMetrics,
  CommentId,
  CommentStatus,
  CommentType,
  CommentPriority,
  AnchorState,
  AuditEvent,
  AuditActor,
  AuditEventType,
  PermissionAction,
  PermissionTarget,
  ChangeEvent,
  ChangeMeta,
  ChangeOrigin,
  StatusChangeMeta,
  UpdateMeta,
  ErrorContext,
  CommentOverlayOptions,
} from 'helldots';

type CommentId = string | number;

type CommentStatus = 'open' | 'in_progress' | 'in_review' | 'resolved';
type CommentType = 'bug' | 'suggestion' | 'question' | 'improvement';
type CommentPriority = 'high' | 'medium' | 'low';
type AnchorState = 'anchored' | 'orphaned' | 'inactive';
type ChangeOrigin = 'user' | 'host';
type ErrorContext = 'capture' | 'storage' | 'load' | 'link' | 'transform';
type AuditEventType = 'created' | 'edited' | 'status' | 'classified';
type PermissionAction =
  | 'edit:comment'
  | 'delete:comment'
  | 'edit:reply'
  | 'delete:reply';

interface SerializedComment {
  /** Stamped as 1 by serializeComments; absent on payloads persisted before it existed. */
  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;
  /** Append-only audit trail. Optional and absent by default. */
  history?: AuditEvent[] | null;
  replies: CommentReply[];
  author: string;
  /** From the user.id declared at creation. Never rendered. */
  authorId?: string | null;
  createdAt: string;
  screenshots: string[];
  status: CommentStatus;
  type: CommentType | null;
  priority: CommentPriority | null;
  tags: string[];
  /** Set on entering "resolved", cleared on leaving it. */
  resolvedAt: string | null;
  context: CommentContext | null;
  /** The automatic viewport capture, as a JPEG data URL. */
  contextScreenshot: string | null;
  /** emoji → the actor keys that reacted. Null when nobody has. */
  reactions: Record<string, string[]> | null;
}

interface Comment {
  // …every field of SerializedComment except schemaVersion…

  /** Live anchor element; null while orphaned or inactive. */
  container: HTMLElement | null;
  relativeX: number;
  relativeY: number;
  anchorState: AnchorState;
  /** The anchor element currently has zero size. */
  hidden: boolean;
  /** The exact element the user clicked on. */
  target?: HTMLElement | null;
}

interface CommentReply {
  id: CommentId;
  text: string;
  author: string;
  authorId?: string | null;
  timestamp: string;
  screenshots?: string[];
  editedAt?: string | null;
  reactions?: Record<string, string[]> | null;
}

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;
}

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;
}

interface CommentContext {
  version: 1;
  /** Full location.href at creation time. */
  url: string;
  viewport: { width: number; height: number };
  /** screen.width / screen.height. */
  screen: { width: number; height: number };
  devicePixelRatio: number;
  /** Always stored, even when browser/os parsing fails. */
  userAgent: string;
  browser: { name: string; version: string };
  os: { name: string; version: string };
  language: string;
}

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;
}

interface AuditEvent {
  type: AuditEventType;
  /** ISO timestamp, from the acting client's clock. */
  at: string;
  actor: AuditActor;
  /** "classified" only: which field moved. */
  field?: 'type' | 'priority' | 'tags';
  /** Both ends of the transition. Absent for "created", "edited" and tag changes. */
  from?: string | null;
  to?: string | null;
}

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>;
  /** Only the days that saw activity — gaps are not filled. */
  overTime: Array<{ date: string; count: number }>;
  resolution: {
    resolvedCount: number;
    /** Comments that were resolved, reopened and resolved again. */
    reopenedCount: number;
    /** Of the resolution currently in force; null when nothing is resolved. */
    averageMs: number | null;
    medianMs: number | null;
  };
}

interface PermissionTarget {
  /** Id of the comment or of the reply, matching the action. */
  id: CommentId;
  /** Display name the record was written under. */
  author: string;
  /** Identity it was written under; null when the host declared no user.id. */
  authorId: string | null;
  /** Present only on edit:reply and delete:reply. */
  commentId?: CommentId;
}

interface ChangeMeta {
  origin: ChangeOrigin;
}

interface StatusChangeMeta extends ChangeMeta {
  from: CommentStatus;
  to: CommentStatus;
}

type UpdateMeta = ChangeMeta &
  (
    | { field: 'type'; from: CommentType | null; to: CommentType | null }
    | { field: 'priority'; from: CommentPriority | null; to: CommentPriority | null }
    | { field: 'tags'; from: string[]; to: string[] }
  );