@veltdev/lexical-velt-comments 4.5.2-beta.2 → 5.0.0-beta.1

package/cjs/types/src/adapters/host/doc.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Lexical document adapter
+ *
+ * This module bridges Lexical's document model with the core system's needs.
+ * It handles selection extraction, occurrence finding, and document change tracking.
+ *
+ * CRITICAL: This is ONE of ONLY TWO places where Lexical types may be imported.
+ * The other is types/host.ts.
+ *
+ * Migrated from src/editor.ts EditorService selection and occurrence logic.
+ */
+import { type LexicalEditor } from 'lexical';
+import type { AnnotationChange, DocumentChangeEvent, OccurrenceMatch, SelectionContext } from '@/types/host';
+import type { AnnotationData } from '@/types/state';
+/**
+ * Get current selection context from editor
+ *
+ * @param editor - Lexical editor instance
+ * @returns SelectionContext with text and position info, or null if no selection
+ */
+export declare const getCurrentSelectionContext: (editor: LexicalEditor) => SelectionContext | null;
+/**
+ * Find all occurrences of text in document (by text only)
+ * Helper function that doesn't require full SelectionContext
+ *
+ * @param editor - Lexical editor instance
+ * @param text - Text to search for
+ * @returns Array of occurrence matches
+ */
+export declare const findOccurrencesByText: (editor: LexicalEditor, text: string) => OccurrenceMatch[];
+/**
+ * Find all occurrences of selected text in document
+ *
+ * @param editor - Lexical editor instance
+ * @param context - Selection context to find occurrences for
+ * @returns Array of occurrence matches
+ */
+export declare const findOccurrences: (editor: LexicalEditor, context: SelectionContext) => OccurrenceMatch[];
+/**
+ * Subscribe to document changes
+ *
+ * @param editor - Lexical editor instance
+ * @param callback - Function called when document changes
+ * @returns Unsubscribe function
+ */
+export declare const subscribeToDocumentChanges: (editor: LexicalEditor, callback: (event: DocumentChangeEvent) => void) => (() => void);
+/**
+ * Get document text content
+ *
+ * @param editor - Lexical editor instance
+ * @returns Full document text
+ */
+export declare const getDocumentText: (editor: LexicalEditor) => string;
+/**
+ * Map position through document changes
+ *
+ * @param oldPos - Original position
+ * @param changes - Document change event
+ * @returns New position or null if position no longer exists
+ */
+export declare const mapPositionThroughChanges: (oldPos: number, changes: DocumentChangeEvent) => number | null;
+/**
+ * Get editor ID from Lexical editor instance
+ *
+ * Checks editor config namespace first, then falls back to DOM attributes.
+ *
+ * @param editor - Lexical editor instance
+ * @returns Editor ID string or null if not found
+ */
+export declare const getEditorId: (editor: LexicalEditor) => string | null;
+/**
+ * Resets the editor selection by focusing the editor.
+ * Uses Lexical's focus API to reset selection/focus after comment operations.
+ *
+ * @param editor The editor instance (typed as unknown to avoid importing editor types in feature modules)
+ * @returns void
+ *
+ * @remarks
+ * - This function abstracts editor-specific selection reset logic
+ * - For Lexical, uses the focus API: `editor.focus()`
+ * - Fails silently if focus API is unavailable
+ */
+export declare const resetEditorSelection: (editor: unknown) => void;
+/**
+ * Detect document changes by collecting CommentNodes and analyzing them
+ * Similar to Tiptap's detectDocumentChanges and old Lexical's onTransaction logic
+ *
+ * @param editor - Lexical editor instance
+ * @param getAnnotationData - Function to get annotation data from state
+ * @returns Map of annotation ID to AnnotationChange
+ */
+export declare const detectDocumentChanges: (editor: LexicalEditor, getAnnotationData: (annotationId: string) => {
+    annotation: AnnotationData;
+    originalText: string;
+    originalOccurrence: number;
+    targetTextNodeId: string;
+} | null) => Map<string, AnnotationChange>;

package/cjs/types/src/adapters/host/marks.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Lexical comment marks adapter
+ *
+ * This module manages visual representation of annotations in the editor.
+ * It handles creating, updating, and removing CommentNodes (Lexical's equivalent of marks).
+ *
+ * CRITICAL: This is ONE of ONLY TWO places where Lexical types may be imported.
+ * The other is types/host.ts.
+ *
+ * Migrated from src/editor.ts EditorService comment node operations.
+ */
+import { ElementNode, type EditorConfig, type LexicalEditor, type LexicalNode, type NodeKey, type SerializedElementNode, type Spread } from 'lexical';
+import { Constants } from '@/constants/common';
+import type { AnnotationChange } from '@/types/host';
+import type { AnnotationData } from '@/types/state';
+/**
+ * CommentNode - Lexical node for representing comment annotations
+ * Migrated from src/comment-node.ts
+ */
+type SerializedCommentNode = Spread<{
+    annotationId?: string;
+    multiThreadAnnotationId?: string;
+    type: typeof Constants.NODE_TYPE;
+    version: 1;
+}, SerializedElementNode>;
+export declare class CommentNode extends ElementNode {
+    __annotationId?: string;
+    __multiThreadAnnotationId?: string;
+    static getType(): string;
+    static clone(node: CommentNode): CommentNode;
+    constructor(annotationId?: string, multiThreadAnnotationId?: string, key?: NodeKey);
+    createDOM(config: EditorConfig): HTMLElement;
+    updateDOM(_prevNode: CommentNode, _dom: HTMLElement, _config: EditorConfig): boolean;
+    static importJSON(serializedNode: SerializedCommentNode): CommentNode;
+    exportJSON(): SerializedCommentNode;
+    isInline(): boolean;
+}
+export declare const $createCommentNode: (annotationId?: string, multiThreadAnnotationId?: string) => CommentNode;
+export declare const $isCommentNode: (node: LexicalNode | null | undefined) => node is CommentNode;
+/**
+ * Applies an annotation mark to the editor document at the specified position.
+ * This is a unified adapter function that matches TipTap's signature.
+ *
+ * @param editor The editor instance (typed as unknown to avoid importing editor types in feature modules)
+ * @param annotationId The annotation ID to mark
+ * @param multiThreadAnnotationId Optional multi-thread annotation ID
+ * @param from Start position of the mark
+ * @param to End position of the mark
+ * @returns True if mark was successfully applied, false otherwise
+ */
+export declare const applyAnnotationMark: (editor: unknown, annotationId: string, multiThreadAnnotationId: string | undefined, from: number, to: number, occurrence?: number) => boolean;
+/**
+ * Apply comment marks (CommentNodes) for a set of annotations
+ *
+ * @param editor - Lexical editor instance
+ * @param annotations - Annotations to render as comment marks
+ */
+export declare const applyAnnotationMarks: (editor: LexicalEditor, annotations: AnnotationData[]) => void;
+/**
+ * Remove comment marks (CommentNodes) for specific annotation IDs
+ *
+ * @param editor - Lexical editor instance
+ * @param annotationIds - Array of annotation IDs to remove
+ */
+export declare const removeAnnotationMarks: (editor: LexicalEditor, annotationIds: string[]) => void;
+/**
+ * Update comment marks efficiently
+ * Uses diff-based updates to minimize DOM changes
+ *
+ * @param editor - Lexical editor instance
+ * @param annotations - Updated annotations
+ */
+export declare const updateAnnotationMarks: (editor: LexicalEditor, annotations: AnnotationData[]) => void;
+/**
+ * Clear all annotation comment marks from editor
+ *
+ * @param editor - Lexical editor instance
+ */
+export declare const clearAllAnnotationMarks: (editor: LexicalEditor) => void;
+/**
+ * Updates marks based on annotation changes.
+ * Currently a no-op: mark updates are handled through applyAnnotationMarks
+ * called from handleContentUpdate after state is updated.
+ *
+ * @param editor The Lexical editor instance
+ * @param changes Map of annotation ID to AnnotationChange
+ */
+export declare const updateMarks: (editor: LexicalEditor, changes: Map<string, AnnotationChange>) => void;
+export {};

package/cjs/types/src/adapters/host/storage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Storage adapter for editor-specific storage access.
+ *
+ * Purpose: Abstracts away editor-specific storage patterns.
+ * This allows the codebase to be more generic and reusable across different editor implementations.
+ *
+ * Key responsibilities:
+ * - Get persistVeltMarks setting (for Lexical, always returns true - marks are always applied)
+ * - Determine if marks should be applied
+ *
+ * Dependencies:
+ * - lexical (ONLY place allowed to import LexicalEditor types for storage access)
+ */
+import type { LexicalEditor } from 'lexical';
+/**
+ * Gets persistVeltMarks setting from storage.
+ * For Lexical, marks are always applied, so this always returns true.
+ *
+ * @param editor The editor instance
+ * @param storageKey The storage key (unused for Lexical, kept for API compatibility)
+ * @returns persistVeltMarks boolean value (always true for Lexical)
+ */
+export declare const getPersistVeltMarks: (editor: LexicalEditor, storageKey?: string) => boolean;
+/**
+ * Determines if marks should be applied based on persistVeltMarks setting.
+ * This is a unified adapter function that abstracts the mark application logic.
+ *
+ * @param editor The editor instance (typed as unknown to avoid importing editor types in feature modules)
+ * @param storageKey The storage key (default: 'lexicalVeltComments')
+ * @returns boolean indicating if marks should be applied
+ *
+ * @remarks
+ * - For TipTap: checks persistVeltMarks setting (apply if FALSE)
+ * - For Lexical: always returns true (always apply marks)
+ * - Defaults to true if storage is unavailable
+ */
+export declare const shouldApplyMark: (editor: unknown, storageKey?: string) => boolean;

package/cjs/types/src/adapters/velt.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Velt SDK adapter.
+ *
+ * Purpose: High-level Velt SDK wrapper with comprehensive error handling.
+ * This is the ONLY place where @veltdev/types and window.Velt may be accessed.
+ *
+ * Key responsibilities:
+ * - Wrap all Velt SDK calls with error handling
+ * - Provide clean interface for features layer
+ * - Handle SDK unavailability gracefully
+ * - Manage subscriptions to Velt events
+ *
+ * Dependencies:
+ * - @veltdev/types (ONLY place allowed to import Velt types)
+ * - types/common.ts (for CommentAnnotationContext)
+ * - types/velt.ts (for re-exported Velt types)
+ */
+import type { CommentElement, CommentAnnotation, Location } from '@veltdev/types';
+import type { CommentAnnotationContext } from '@/types/common';
+/**
+ * Gets the Velt comment element from the SDK.
+ * Returns null if SDK is unavailable or comment element cannot be accessed.
+ *
+ * @returns CommentElement or null if unavailable
+ */
+export declare const getCommentElement: () => CommentElement | null;
+/**
+ * Adds a comment via the Velt SDK.
+ *
+ * @param params Object containing context and optional location
+ * @returns Promise resolving to CommentAnnotation or null if failed
+ */
+export declare const addVeltComment: (params: {
+    context: CommentAnnotationContext;
+    location?: Location;
+}) => Promise<{
+    annotation: CommentAnnotation | null;
+    result: unknown;
+}>;
+/**
+ * Updates the context of an existing annotation in the Velt SDK.
+ *
+ * @param annotationId The annotation ID to update
+ * @param context The new context to set
+ */
+export declare const updateAnnotationContext: (annotationId: string, context: CommentAnnotationContext) => void;
+/**
+ * Subscribes to changes in selected annotations from the Velt SDK.
+ * Returns an unsubscribe function.
+ *
+ * @param callback Function called when selected annotations change
+ * @param subscriberId Optional unique ID for this subscriber
+ * @returns Unsubscribe function
+ */
+export declare const subscribeToSelectedAnnotations: (callback: (selectedIds: Set<string>) => void, subscriberId?: string) => (() => void);

package/cjs/types/src/constants/common.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared constants for Lexical-Velt Comments integration
+ *
+ * This module contains all magic strings and configuration constants
+ * used across the application. Migrated from src/constants.ts
+ */
+export declare const Constants: {
+    /**
+     * DOM attribute names used for editor identification and location tracking.
+     */
+    readonly ATTRIBUTES: {
+        readonly EDITOR_ID: "data-editor-id";
+        readonly LOCATION_ID: "data-velt-location-id";
+        readonly ANNOTATION_ID: "annotation-id";
+        readonly MULTI_THREAD_ANNOTATION_ID: "multi-thread-annotation-id";
+    };
+    /**
+     * Mark/extension name constant.
+     * Generic constant name, value is Lexical-specific for this package.
+     */
+    readonly MARK_NAME: "lexicalVeltComments";
+    /**
+     * Storage key constant.
+     * Generic constant name, value is Lexical-specific for this package.
+     */
+    readonly STORAGE_KEY: "lexicalVeltComments";
+    /**
+     * Custom element tag name for comment nodes.
+     * CRITICAL: Must be 'velt-comment-text' to match Tiptap/Lexical/Slate implementations.
+     */
+    readonly TAG_NAME: "velt-comment-text";
+    /**
+     * Default extension name for error messages.
+     */
+    readonly DEFAULT_EXTENSION_NAME: "VeltComments";
+    /**
+     * Lexical node type name for comment nodes.
+     * Lexical-specific constant for CommentNode type.
+     */
+    readonly NODE_TYPE: "comment";
+    /**
+     * Default editor ID used when no editor ID is provided.
+     * Uses '__default__' to avoid collision with user-provided values.
+     */
+    readonly DEFAULT_EDITOR_ID: "__default__";
+    /**
+     * Terminal status type for resolved/closed comments.
+     */
+    readonly STATUS_TERMINAL: "terminal";
+    /**
+     * Log prefix for console messages.
+     */
+    readonly LOG_PREFIX: "LexicalVeltComments: ";
+    /**
+     * Session storage key for debug mode.
+     */
+    readonly DEBUG_MODE_KEY: "debugMode";
+    /**
+     * Session storage key for forced debug mode.
+     */
+    readonly FORCE_DEBUG_MODE_KEY: "forceDebugMode";
+    /**
+     * Block-level node types in Lexical that should have newline breaks after them.
+     * Used for text content collection and block boundary detection.
+     */
+    readonly BLOCK_TYPES: readonly ["paragraph", "heading", "listitem", "quote", "code"];
+};

package/cjs/types/src/core/extension.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Core extension module.
+ *
+ * Purpose: Manages document change listeners and editor setup for Lexical editors.
+ * This module handles the lifecycle of document change subscriptions.
+ *
+ * Key responsibilities:
+ * - Set up document change listeners for editors
+ * - Wire up document change handler to updateContent feature
+ * - Manage document change listener lifecycle
+ * - Orchestrate editor setup (registration + listeners)
+ *
+ * Dependencies: adapters/host/doc.ts, features/updateContent.ts, core/registry.ts
+ */
+import type { LexicalEditor } from 'lexical';
+/**
+ * Ensures document change listeners are set up for an editor.
+ * This is called by lazy registration (addComment/renderComments) to ensure content updates work.
+ *
+ * @param editorId Editor identifier
+ * @param editor Lexical editor instance
+ * @returns true if listeners were set up (or already existed), false if setup failed
+ */
+export declare const ensureDocumentChangeListeners: (editorId: string, editor: LexicalEditor) => boolean;
+/**
+ * Ensures editor is set up (registered and document listeners configured).
+ * This is a unified orchestration function that handles both registration and setup.
+ *
+ * @param editorId Optional editor ID (will be resolved from editor if not provided)
+ * @param editor The editor instance (typed as unknown to avoid importing editor types in feature modules)
+ * @returns Object with editorId string
+ *
+ * @remarks
+ * - This function abstracts editor-specific setup logic
+ * - For Lexical, ensures editor is registered and document change listeners are set up
+ * - Fails silently if setup fails
+ */
+export declare const ensureEditorSetup: (editorId: string | undefined, editor: unknown) => {
+    editorId: string;
+};

package/cjs/types/src/core/registry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Core registry module.
+ *
+ * Purpose: Maintains a registry mapping editorId → editor context.
+ * Replaces the singleton pattern from legacy Plugin class with a proper registry.
+ *
+ * Key responsibilities:
+ * - Register editor instances with their configuration
+ * - Retrieve editor contexts by ID
+ * - Unregister editors when they're destroyed
+ * - Extract editor IDs from editor instances
+ *
+ * CRITICAL: This module must NOT import Lexical or Velt types directly.
+ * It uses adapter interfaces from types/* instead.
+ *
+ * CRITICAL: This module is PURE registry logic - no document change listeners,
+ * no feature imports, no adapter imports. Document change handling belongs in extension.ts.
+ *
+ * Dependencies: types/common.ts, core/state.ts, adapters/host/doc.ts
+ */
+import type { EditorContext, ExtensionConfig } from '@/types/common';
+/**
+ * Registers an editor instance in the registry.
+ * Creates initial state for the editor.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param editor The editor instance
+ * @param config Extension configuration options
+ * @returns EditorContext for the registered editor
+ */
+export declare const registerEditor: <TEditor = unknown>(editorId: string, editor: TEditor, config?: ExtensionConfig) => EditorContext<TEditor>;
+/**
+ * Retrieves the editor context for a given editor ID.
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns EditorContext or null if not found
+ */
+export declare const getEditorContext: <TEditor = unknown>(editorId: string) => EditorContext<TEditor> | null;
+/**
+ * Unregisters an editor from the registry and cleans up its state.
+ *
+ * @param editorId Unique identifier for the editor
+ */
+export declare const unregisterEditor: (editorId: string) => void;
+/**
+ * Ensures an editor is registered (lazy registration helper).
+ * Gets existing registration if available, creates new if not found.
+ *
+ * NOTE: This does NOT set up document change listeners - that belongs in extension.ts.
+ * This is pure registry logic only.
+ *
+ * @param editorId Editor identifier (optional, will be resolved from editor if not provided)
+ * @param editor Editor instance
+ * @param config Optional configuration
+ * @returns EditorContext
+ */
+export declare const ensureEditorRegistered: <TEditor = unknown>(editorId: string | undefined, editor: TEditor, config?: ExtensionConfig) => EditorContext<TEditor>;
+/**
+ * Extracts the editor ID from an editor instance.
+ * Checks editor storage first, then DOM attributes.
+ *
+ * @param editor The editor instance
+ * @returns Editor ID or null if not found
+ */
+export declare const getEditorIdFromEditor: (editor: unknown) => string | null;
+/**
+ * Gets all registered editor IDs.
+ *
+ * @returns Array of editor IDs
+ */
+export declare const getAllEditorIds: () => string[];

package/cjs/types/src/core/state.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Core state management module.
+ *
+ * Purpose: Single source of truth for annotation state per editor.
+ * This module manages annotation data and selected annotations for each editor instance.
+ *
+ * Key responsibilities:
+ * - Create and manage per-editor annotation state
+ * - CRUD operations for annotations
+ * - Track selected annotations
+ * - Ensure state isolation between editor instances
+ *
+ * CRITICAL: This module must NOT import Lexical or Velt types.
+ * It only depends on types/*, constants/*, and utils/*.
+ */
+import type { AnnotationData, AnnotationState } from '@/types/state';
+import type { CommentAnnotation } from '@/types/velt';
+/**
+ * Create a new annotation state for an editor
+ *
+ * @param editorId - Unique identifier for the editor instance
+ * @returns New AnnotationState instance
+ */
+export declare const createAnnotationState: (editorId: string) => AnnotationState;
+/**
+ * Updates annotations in state from Velt SDK data.
+ * Converts CommentAnnotation[] to AnnotationData[] and stores them.
+ *
+ * This matches Tiptap's pattern where conversion happens in updateAnnotations,
+ * not in the feature module (renderComments).
+ *
+ * @param editorId Unique identifier for the editor
+ * @param annotations Array of CommentAnnotation from Velt SDK
+ */
+export declare const updateAnnotations: (editorId: string, annotations: CommentAnnotation[]) => void;
+/**
+ * Gets all annotations for an editor.
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns Map of annotation ID to AnnotationData
+ */
+export declare const getAllAnnotations: (editorId: string) => Map<string, AnnotationData>;
+/**
+ * Get a specific annotation by ID
+ *
+ * @param editorId - Editor identifier
+ * @param annotationId - Annotation ID
+ * @returns Annotation or null if not found
+ */
+export declare const getAnnotation: (editorId: string, annotationId: string) => AnnotationData | null;
+/**
+ * Remove a specific annotation
+ *
+ * @param editorId - Editor identifier
+ * @param annotationId - Annotation ID to remove
+ */
+export declare const removeAnnotation: (editorId: string, annotationId: string) => void;
+/**
+ * Clears all state for an editor (used during cleanup).
+ * Matches Tiptap's clearState function signature.
+ *
+ * @param editorId Unique identifier for the editor
+ */
+export declare const clearState: (editorId: string) => void;
+/**
+ * Gets the set of selected annotation IDs for an editor.
+ *
+ * @param editorId - Unique identifier for the editor
+ * @returns Set of selected annotation IDs
+ */
+export declare const getSelectedAnnotations: (editorId: string) => Set<string>;
+/**
+ * Updates the set of selected annotation IDs for an editor.
+ *
+ * @param editorId - Unique identifier for the editor
+ * @param selectedIds - Set of selected annotation IDs
+ */
+export declare const setSelectedAnnotations: (editorId: string, selectedIds: Set<string>) => void;
+/**
+ * Get all comment annotations (with status) for an editor.
+ * Returns the full CommentAnnotation[] array stored in state.
+ *
+ * @param editorId Unique identifier for the editor
+ * @returns Array of CommentAnnotation with status field, or empty array if none
+ */
+export declare const getCommentAnnotations: (editorId: string) => CommentAnnotation[];

package/cjs/types/src/features/addComment.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Add comment feature module.
+ *
+ * Purpose: End-to-end add comment orchestration.
+ * Orchestrates adapters and core to implement the add comment flow.
+ *
+ * Key responsibilities:
+ * - Get Velt comment element
+ * - Extract selection context from editor
+ * - Create comment via Velt SDK
+ * - Apply mark to editor document
+ * - Update state with annotation data
+ *
+ * Dependencies:
+ * - adapters/velt.ts (for Velt SDK calls)
+ * - adapters/host/doc.ts (for selection extraction, editor setup, and selection reset)
+ * - adapters/host/marks.ts (for mark application)
+ * - adapters/host/storage.ts (for mark application configuration)
+ * - core/state.ts (for state updates)
+ * - types/common.ts (for CommentAnnotationContext)
+ *
+ * IMPORTANT: This module MUST NOT import editor or Velt types directly.
+ * All SDK access goes through adapters.
+ */
+import type { AddCommentRequest } from '@/types/common';
+/**
+ * Adds a comment to the currently selected text in the editor.
+ *
+ * This is the main entry point for adding comments. It handles:
+ * - Extracting selection context from the editor
+ * - Creating the comment via Velt SDK
+ * - Applying marks to the editor if configured
+ * - Updating state with annotation data
+ *
+ * @param request - Object containing editorId (optional), editor, and context (optional)
+ * @returns Promise that resolves when the comment is added (or fails silently)
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * await addComment({ editor });
+ *
+ * // With editor ID
+ * await addComment({ editorId: 'my-editor', editor });
+ *
+ * // With custom context
+ * await addComment({
+ *   editorId: 'my-editor',
+ *   editor,
+ *   context: {
+ *     userId: 'user123',
+ *     metadata: { source: 'web-app' }
+ *   }
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires text to be selected in the editor
+ * - Requires Velt SDK to be available (window.Velt)
+ * - Marks are only applied if persistVeltMarks is FALSE in extension config (matching legacy behavior)
+ * - Fails silently if Velt SDK is unavailable or selection is invalid
+ */
+export declare function addComment({ editorId, editor, context: clientContext, }: AddCommentRequest): Promise<void>;

package/cjs/types/src/features/commentRenderer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Comment renderer module.
+ *
+ * Purpose: Handle filtering, comparison, and mark updates for comment annotations.
+ * This module manages the rendering state and applies marks based on resolved/selected status.
+ *
+ * Key responsibilities:
+ * - Filter annotations based on status (terminal/resolved) and selected state
+ * - Compare previous vs current filtered annotations to detect removals
+ * - Remove marks for annotations that should no longer be shown
+ * - Re-apply marks for all filtered annotations
+ *
+ * Dependencies:
+ * - core/state.ts (for reading annotations and selected state)
+ * - adapters/host/marks.ts (for applying/removing marks)
+ * - types/velt.ts (for CommentAnnotation)
+ * - types/state.ts (for AnnotationData)
+ *
+ * IMPORTANT: This module MUST NOT import editor or Velt types directly.
+ * All SDK access goes through adapters.
+ */
+import type { CommentAnnotation } from '@/types/velt';
+/**
+ * Updates comments for an editor by filtering, comparing, removing, and re-applying marks.
+ * This is the core rendering logic that handles resolved comment filtering.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param editor The editor instance
+ * @param annotations All CommentAnnotation from Velt SDK (with status)
+ */
+export declare const updateComments: (editorId: string, editor: unknown, annotations: CommentAnnotation[]) => void;
+/**
+ * Updates comments when selected annotations change.
+ * Re-reads annotations from state and triggers re-rendering.
+ *
+ * @param editorId Unique identifier for the editor
+ * @param selectedIds Set of selected annotation IDs (already updated in state)
+ */
+export declare const updateSelection: (editorId: string, selectedIds: Set<string>) => void;
+/**
+ * Cleans up renderer store for an editor.
+ * Should be called when editor is destroyed.
+ *
+ * @param editorId Unique identifier for the editor
+ */
+export declare const cleanupRenderer: (editorId: string) => void;