@uselay/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,493 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+type CommentStatus = 'open' | 'resolved' | 'archived';
+interface Author {
+    id: string | null;
+    name: string;
+    avatar: string | null;
+}
+interface ElementFingerprint {
+    tag: string;
+    textContent: string;
+    attributes: Record<string, string>;
+    siblingIndex: number;
+    siblingCount: number;
+    parentTag: string;
+    grandparentTag: string;
+}
+interface ElementMetadata {
+    computed_styles: Record<string, string>;
+    accessibility: {
+        role: string | null;
+        aria_label: string | null;
+        contrast_ratio: number | null;
+        contrast_passes_aa: boolean | null;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    device: string;
+    fingerprint?: ElementFingerprint;
+}
+interface AIContextReview {
+    ai_context_version: 2 | 3;
+    mode: 'review';
+    category: 'visual' | 'accessibility' | 'layout' | 'copy' | 'interaction';
+    /** v3: single interpretation sentence replacing suggestions + accessibility_issues */
+    interpretation?: string;
+    /** @deprecated v2 only — replaced by interpretation in v3 */
+    suggestions?: string[];
+    /** @deprecated v2 only — replaced by interpretation in v3 */
+    accessibility_issues?: string[];
+    /** @deprecated v2 only — removed in v3 */
+    confidence?: number;
+    enriched_at: string;
+}
+interface AIContextSupport {
+    ai_context_version: 2 | 3;
+    mode: 'support';
+    intent: 'confusion' | 'bug_report' | 'feature_request' | 'complaint' | 'question' | 'praise' | 'other';
+    urgency: 'low' | 'medium' | 'high';
+    summary: string;
+    suggested_response: string;
+    /** @deprecated v2 only — removed in v3 */
+    confidence?: number;
+    enriched_at: string;
+}
+type AIContext = AIContextReview | AIContextSupport;
+declare function isAIContextReview(ctx: AIContext): ctx is AIContextReview;
+declare function isAIContextSupport(ctx: AIContext): ctx is AIContextSupport;
+interface ElementBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface Comment {
+    id: string;
+    project_id: string;
+    thread_id: string | null;
+    author: Author;
+    content: string;
+    status: CommentStatus;
+    dom_path: string;
+    url_path: string;
+    element_metadata: ElementMetadata | null;
+    resolved_by: Author | null;
+    resolved_at: string | null;
+    archived_at: string | null;
+    ai_context: AIContext | null;
+    screenshot_url: string | null;
+    element_bounds: ElementBounds | null;
+    created_at: string;
+    updated_at: string;
+}
+type NewComment = Omit<Comment, 'id' | 'created_at' | 'updated_at'>;
+
+type Unsubscribe = () => void;
+interface CommentUpdate {
+    status?: CommentStatus;
+    resolved_by?: Author | null;
+    resolved_at?: string | null;
+    archived_at?: string | null;
+    /** Updated CSS selector path (used by M6 self-healing) */
+    dom_path?: string;
+}
+type CommentEventType = 'INSERT' | 'UPDATE';
+interface CommentEvent {
+    type: CommentEventType;
+    comment: Comment;
+}
+interface AdapterOptions {
+    /** Session token for support-mode authentication */
+    sessionToken?: string;
+}
+interface LayAdapter {
+    getConfig(projectId: string): Promise<RemoteConfig>;
+    getComments(projectId: string, urlPath: string, options?: AdapterOptions): Promise<Comment[]>;
+    addComment(comment: NewComment, options?: AdapterOptions): Promise<Comment>;
+    updateComment(id: string, update: CommentUpdate, options?: AdapterOptions): Promise<Comment>;
+    uploadScreenshot(projectId: string, commentId: string, blob: Blob, bounds: ElementBounds, options?: AdapterOptions): Promise<void>;
+    subscribe(projectId: string, callback: (event: CommentEvent) => void, options?: AdapterOptions): Unsubscribe;
+}
+
+/** Project mode: review (team feedback) or support (end-user help) */
+type ProjectMode = 'review' | 'support';
+/** Starter chip for the Two-Speed Composer */
+interface StarterChip {
+    /** Display label on the chip */
+    label: string;
+    /** Comment content submitted when chip is tapped (defaults to label if omitted) */
+    value?: string;
+}
+/** Remote configuration fetched from the dashboard */
+interface RemoteConfig {
+    mode: ProjectMode;
+    active: boolean;
+}
+interface LayConfig {
+    /** Unique identifier for the project */
+    projectId: string;
+    /** Optional user identity. If not provided, comments are anonymous. */
+    user?: Author;
+    /** HMAC-SHA256 hash of user.id, created server-side with LAY_SECRET_KEY. Required for verified identity in support mode. */
+    userHash?: string;
+    /** Optional custom adapter. If not provided, auto-selects based on projectId. */
+    adapter?: LayAdapter;
+    /** Optional API base URL for the hosted backend. Defaults to https://uselay.com. Used for local development. */
+    apiUrl?: string;
+    /** Optional version string. Changing this archives previous comments. */
+    version?: string;
+    /** Enable AI enrichment on comments. Defaults to true. Set false to show metadata only (no AI interpretation). */
+    ai?: boolean;
+    /** Override mode from dashboard. If omitted, uses dashboard setting. */
+    mode?: ProjectMode;
+    /** Override active state. If omitted, uses dashboard setting. false = widget renders nothing. */
+    active?: boolean;
+    /** Starter chips for quick feedback. Defaults to ["Visual bug", "Copy issue", "Love this"]. Set to [] to disable chips. */
+    starterChips?: StarterChip[];
+    /** Capture viewport screenshots on comment creation. Defaults to true. Set false to disable. */
+    screenshots?: boolean;
+}
+
+type LayAction = {
+    type: 'TOGGLE_COMMENT_MODE';
+} | {
+    type: 'SET_COMMENT_MODE';
+    payload: boolean;
+} | {
+    type: 'SET_COMMENTS';
+    payload: Comment[];
+} | {
+    type: 'ADD_COMMENT';
+    payload: Comment;
+} | {
+    type: 'UPDATE_COMMENT';
+    payload: Comment;
+};
+interface LayContextValue {
+    isCommentMode: boolean;
+    comments: Comment[];
+    adapter: LayAdapter;
+    config: LayConfig;
+    dispatch: React.Dispatch<LayAction>;
+    portalRoot: HTMLDivElement | null;
+    mode: ProjectMode;
+    remoteConfigLoaded: boolean;
+    detachedDomPaths: Set<string>;
+    setDetachedDomPaths: React.Dispatch<React.SetStateAction<Set<string>>>;
+}
+interface LayProviderProps extends LayConfig {
+    children: ReactNode;
+}
+declare function LayProvider({ children, projectId, user, userHash, adapter: customAdapter, apiUrl, version, ai, mode: modeProp, active: activeProp, starterChips, screenshots, }: LayProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function LayToggle(): React.ReactPortal | null;
+
+interface ElementHighlighterProps {
+    hoveredElement: Element | null;
+    selectedElement: Element | null;
+}
+declare function ElementHighlighter({ hoveredElement, selectedElement, }: ElementHighlighterProps): React.ReactPortal | null;
+
+interface CommentAnchorProps {
+    selectedElement: Element | null;
+    onClearSelection: () => void;
+}
+declare function CommentAnchor({ selectedElement, onClearSelection, }: CommentAnchorProps): React.ReactPortal | null;
+
+/**
+ * Owns the shared element selector state and renders both the
+ * highlight overlay and the comment input popover.
+ */
+declare function CommentLayer(): react_jsx_runtime.JSX.Element;
+
+interface CommentDotProps {
+    domPath: string;
+    comments: Comment[];
+    isResolved?: boolean;
+    isNew?: boolean;
+    onDidResolve?: () => void;
+    /** Pre-resolved element from 3-layer resolution (M6). Falls back to querySelector if not provided. */
+    resolvedElement?: Element | null;
+}
+declare const CommentDot: React.NamedExoticComponent<CommentDotProps>;
+
+/**
+ * Renders a CommentDot for each unique dom_path that has comments.
+ * Hides dots for fully-archived dom_paths. Mutes dots for fully-resolved ones.
+ * Runs 3-layer element resolution and tracks detached comments.
+ * Always visible — dots show regardless of comment mode.
+ */
+declare function CommentDots(): react_jsx_runtime.JSX.Element | null;
+
+interface CommentThreadProps {
+    comments: Comment[];
+    dotRect: DOMRect;
+    onClose: () => void;
+    onDidResolve?: () => void;
+}
+declare function CommentThread({ comments, dotRect, onClose, onDidResolve, }: CommentThreadProps): React.ReactPortal | null;
+
+interface CommentItemProps {
+    comment: Comment;
+    isReply?: boolean;
+    actions?: ReactNode;
+}
+declare function CommentItem({ comment, isReply, actions }: CommentItemProps): react_jsx_runtime.JSX.Element;
+
+interface CommentActionsProps {
+    comment: Comment;
+    onResolve: (comment: Comment) => void;
+    onReopen: (comment: Comment) => void;
+    onArchive: (comment: Comment) => void;
+}
+declare function CommentActions({ comment, onResolve, onReopen, onArchive, }: CommentActionsProps): react_jsx_runtime.JSX.Element | null;
+
+interface ArchivedThreadsPanelProps {
+    onClose: () => void;
+}
+declare function ArchivedThreadsPanel({ onClose }: ArchivedThreadsPanelProps): React.ReactPortal | null;
+
+interface DetachedCommentsPanelProps {
+    onClose: () => void;
+}
+declare function DetachedCommentsPanel({ onClose }: DetachedCommentsPanelProps): React.ReactPortal | null;
+
+interface AIContextCardProps {
+    elementMetadata: ElementMetadata | null;
+    aiContext: AIContext | null;
+    aiEnabled?: boolean;
+}
+declare function AIContextCard({ elementMetadata, aiContext, aiEnabled, }: AIContextCardProps): react_jsx_runtime.JSX.Element | null;
+
+interface ReplyInputProps {
+    /** The root comment of the thread to reply to */
+    rootComment: Comment;
+    /** Called after a reply is successfully submitted */
+    onReplySubmitted?: () => void;
+}
+declare function ReplyInput({ rootComment, onReplySubmitted }: ReplyInputProps): react_jsx_runtime.JSX.Element;
+
+declare function useLayContext(): LayContextValue;
+
+declare function useCommentMode(): {
+    isCommentMode: boolean;
+    toggleCommentMode: () => void;
+    setCommentMode: (active: boolean) => void;
+};
+
+interface ElementSelectorState {
+    /** The element currently under the cursor (comment mode only) */
+    hoveredElement: Element | null;
+    /** The element the user clicked to comment on */
+    selectedElement: Element | null;
+}
+interface UseElementSelectorReturn extends ElementSelectorState {
+    /** Clear the selected element (dismiss comment input) */
+    clearSelection: () => void;
+}
+/**
+ * Tracks hovered and selected elements via event delegation on document.body.
+ * Only active when comment mode is on. Cleans up all listeners when mode is off.
+ */
+declare function useElementSelector(): UseElementSelectorReturn;
+
+interface CommentGroup {
+    domPath: string;
+    comments: Comment[];
+}
+interface ThreadItem {
+    root: Comment;
+    replies: Comment[];
+}
+interface ThreadGroup {
+    domPath: string;
+    threads: ThreadItem[];
+    allComments: Comment[];
+}
+/**
+ * Convenience hook that reads comments from context and provides
+ * grouping/filtering helpers. State is owned by LayProvider.
+ */
+declare function useComments(): {
+    comments: Comment[];
+    groupedByDomPath: CommentGroup[];
+    threadsByDomPath: ThreadGroup[];
+    archivedThreads: ThreadItem[];
+    archivedCount: number;
+    detachedThreads: ThreadItem[];
+    detachedCount: number;
+    isDomPathFullyResolved: (domPath: string) => boolean;
+    isDomPathFullyArchived: (domPath: string) => boolean;
+};
+
+/**
+ * Generate a CSS selector path for an element by walking up the DOM tree.
+ *
+ * Priority order for each segment (highest to lowest):
+ * 1. data-feedback-id="X"  → [data-feedback-id="X"]  (stop walking)
+ * 2. data-testid="X"       → [data-testid="X"]       (stop walking)
+ * 3. id="X"                → #X                       (stop walking)
+ * 4. Stable class names    → tag.my-button (skip generated/hashed classes)
+ * 5. Tag + nth-child       → div:nth-child(3)         (fallback)
+ */
+declare function generateDomPath(element: Element): string;
+/**
+ * Heuristic to detect framework-generated class names.
+ * Returns true for classes that are likely unstable across builds.
+ */
+declare function isGeneratedClassName(name: string): boolean;
+/**
+ * Check if an element should be excluded from the commentable surface.
+ * Excludes Lay UI elements and non-visible elements.
+ */
+declare function isCommentable(element: Element): boolean;
+
+/**
+ * Element fingerprinting for anchoring hardening (M6).
+ *
+ * Captures a structural fingerprint of a DOM element that can be used
+ * to re-find the element when its CSS selector path breaks due to
+ * DOM changes between deploys.
+ */
+
+/**
+ * Generate a fingerprint for a DOM element.
+ * Captures tag, text content, key attributes, and structural position.
+ */
+declare function generateFingerprint(element: Element): ElementFingerprint;
+/**
+ * Score how well a stored fingerprint matches a candidate element.
+ * Returns 0-100. Tag mismatch = 0 (required match).
+ */
+declare function scoreFingerprintMatch(stored: ElementFingerprint, candidate: Element): number;
+interface FingerprintMatchResult {
+    element: Element | null;
+    score: number;
+}
+/**
+ * Find the best matching element on the page for a stored fingerprint.
+ * Scans all elements of the same tag type and returns the highest-scoring match.
+ *
+ * @param fingerprint - The stored fingerprint to match against
+ * @param threshold - Minimum score to consider a match (default: 40)
+ * @returns The best matching element and its score, or null if below threshold
+ */
+declare function findByFingerprint(fingerprint: ElementFingerprint, threshold?: number): FingerprintMatchResult;
+
+/**
+ * Three-layer element resolution for anchoring hardening (M6).
+ *
+ * Resolution order:
+ * 1. data-feedback-id lookup (if dom_path contains one)
+ * 2. CSS selector (document.querySelector)
+ * 3. Fingerprint matching (fuzzy structural match)
+ *
+ * Returns the resolved element and which method succeeded.
+ */
+
+type ResolveMethod = 'feedback-id' | 'selector' | 'fingerprint' | 'detached';
+interface ResolveResult {
+    element: Element | null;
+    method: ResolveMethod;
+    /** Fingerprint match score (only set when method is 'fingerprint') */
+    score?: number;
+}
+/**
+ * Resolve a DOM element using 3-layer strategy.
+ *
+ * @param domPath - The stored CSS selector path
+ * @param fingerprint - Optional element fingerprint for fuzzy matching
+ * @returns The resolved element and the method that found it
+ */
+declare function resolveElement(domPath: string, fingerprint?: ElementFingerprint | null): ResolveResult;
+
+/**
+ * Summarize a stored CSS selector path into a human-readable string.
+ * Used in the detached comments panel to show "Was on: button in #pricing".
+ *
+ * @param domPath - A CSS selector like "body > div > main > section#pricing > button:nth-child(2)"
+ * @returns A human-readable summary like "button in #pricing"
+ */
+declare function summarizeDomPath(domPath: string): string;
+
+/**
+ * Format an ISO timestamp as a human-readable relative time string.
+ *
+ * Examples: "just now", "2 min ago", "1 hr ago", "Yesterday", "Feb 12"
+ */
+declare function formatRelativeTime(isoTimestamp: string): string;
+
+/**
+ * Walk up the DOM tree from `element` to find the first ancestor with
+ * a non-transparent computed background-color. Returns the CSS color string.
+ * Falls back to white (#FFFFFF) if all ancestors are transparent.
+ */
+declare function resolveEffectiveBackground(element: Element): string;
+/**
+ * Compute the WCAG 2.1 contrast ratio between a foreground and background color.
+ *
+ * Returns the ratio (≥1) and whether the combination passes WCAG AA.
+ * AA threshold: 4.5:1 for normal text, 3:1 for large text (≥18px or bold ≥14px).
+ * We default to the 4.5:1 threshold (normal text) since font-size context
+ * is not always reliably available here.
+ */
+declare function computeContrastRatio(fgColor: string, bgColor: string): {
+    ratio: number;
+    passesAA: boolean;
+};
+/**
+ * Parse a user agent string into a readable device string.
+ * Returns "iPhone", "iPad", "Android", "Chrome on macOS", etc.
+ */
+declare function parseUserAgent(ua: string): string;
+/**
+ * Capture technical metadata from a DOM element.
+ *
+ * Collects computed styles, accessibility data (contrast ratio, ARIA),
+ * viewport dimensions, and device info. All reads are synchronous —
+ * no network calls, no DOM mutations, no layout thrashing.
+ */
+declare function captureElementMetadata(element: Element): ElementMetadata;
+
+interface GuestAuthor {
+    name: string;
+}
+/**
+ * Read the saved guest author name from localStorage.
+ * Returns null if no name is saved or localStorage is unavailable.
+ */
+declare function getGuestAuthor(): GuestAuthor | null;
+/**
+ * Persist a guest author name to localStorage.
+ * Silently fails if localStorage is unavailable.
+ */
+declare function saveGuestAuthor(name: string): void;
+
+/**
+ * Resolve the author for a comment based on whether the developer
+ * provided a user identity (identified mode) or not (guest mode).
+ *
+ * In identified mode, returns `config.user`.
+ * In guest mode, returns a guest author from the name field,
+ * or ANONYMOUS_AUTHOR if the name is blank.
+ */
+declare function resolveAuthor(config: LayConfig, guestName: string): Author;
+/**
+ * Persist the guest name to localStorage if non-empty.
+ * No-op in identified mode — the caller decides when to call this.
+ */
+declare function persistGuestName(name: string): void;
+
+declare function createMemoryAdapter(): LayAdapter;
+
+interface HostedAdapterOptions {
+    apiUrl?: string;
+    ai?: boolean;
+}
+declare function createHostedAdapter(options?: string | HostedAdapterOptions): LayAdapter;
+
+export { type AIContext, AIContextCard, type AIContextReview, type AIContextSupport, type AdapterOptions, ArchivedThreadsPanel, type Author, type Comment, CommentActions, CommentAnchor, CommentDot, CommentDots, type CommentEvent, type CommentEventType, type CommentGroup, CommentItem, CommentLayer, type CommentStatus, CommentThread, type CommentUpdate, DetachedCommentsPanel, type ElementBounds, type ElementFingerprint, ElementHighlighter, type ElementMetadata, type LayAdapter, type LayConfig, type LayContextValue, LayProvider, LayToggle, type NewComment, type ProjectMode, type RemoteConfig, ReplyInput, type ResolveMethod, type ResolveResult, type StarterChip, type ThreadGroup, type ThreadItem, type Unsubscribe, captureElementMetadata, computeContrastRatio, createHostedAdapter, createMemoryAdapter, findByFingerprint, formatRelativeTime, generateDomPath, generateFingerprint, getGuestAuthor, isAIContextReview, isAIContextSupport, isCommentable, isGeneratedClassName, parseUserAgent, persistGuestName, resolveAuthor, resolveEffectiveBackground, resolveElement, saveGuestAuthor, scoreFingerprintMatch, summarizeDomPath, useCommentMode, useComments, useElementSelector, useLayContext };