Annotations

This guide explains in detail how EchoPastel's annotation system works and its advanced features.

Overview

EchoPastel's annotation system uses advanced multi-strategy fingerprinting technology to ensure your annotations remain attached to the right elements, even when the page changes.

Multi-strategy fingerprint system

Unlike systems that use only a CSS selector (which can easily break), EchoPastel uses multiple identification strategies:

1. CSS Selector

The traditional CSS selector using element classes and IDs. This is the fastest method but can be fragile if classes change.

2. XPath

An XPath path based on the DOM structure. More stable than CSS, it works even if classes change.

3. Content fingerprint

A signature based on element characteristics:

• Tag name: div, button, img, etc.
• Attributes: id, class, data-*, aria-*, etc.
• Text content: The visible text of the element
• Internal HTML: The internal HTML structure

4. Context information

Information about parent-child relationships:

• Parent selector: How to identify the parent
• Sibling index: Position of the element among its siblings
• Dynamic container detection: Identification of carousels, sliders, etc.

Resolution cascade

When EchoPastel needs to relocate an annotated element, it tries multiple strategies in order:

1. CSS Selector - Fastest method
2. XPath - More stable, works even if classes change
3. Parent + Index - Uses relative position in the parent
4. Content matching - Finds the element by content similarity

This cascade ensures maximum reliability: if one method fails, others can still find the element.

Dynamic content handling

Automatic detection

EchoPastel automatically detects elements in dynamic containers:

• Carousels: Swiper, Slick, Splide, etc.
• Scrollable containers: Areas with overflow
• Custom sliders: Custom implementations

Detection is done by checking:

• Class names containing carousel keywords
• Data attributes (e.g., data-carousel, data-swiper)
• CSS overflow properties

Smart observers

For elements in dynamic containers, the system attaches specialized observers:

1. ResizeObserver - Detects size changes
2. MutationObserver - Monitors DOM modifications
3. Scroll listeners - Tracks scrolling within containers
4. IntersectionObserver - Detects visibility changes

These observers automatically reposition annotations when:

• Carousel slides change
• Elements are animated
• Content is lazy-loaded
• Page layout shifts

Annotation states

Active annotation

The element has been found and the annotation is correctly positioned. This is the normal state of an annotation.

Orphaned annotation

The annotated element no longer exists on the page. In this case:

• The annotation is marked as "orphaned"
• It is displayed with reduced opacity and in grayscale
• The screenshot is still accessible
• You can still see and reply to the annotation

Important: Orphaned annotations are not lost! They retain their screenshot and remain accessible for reference.

Dynamic annotation

The annotation is in a carousel/slider and is actively tracked. The system automatically adjusts its position during changes.

Automatic screenshots

Each annotation automatically generates a screenshot that:

• Preserves the visual context of your feedback
• Shows the annotated element at the time of creation
• Remains accessible even if the element disappears (orphaned annotation)
• Helps understand the context even after page changes

Screenshots are generated automatically and require no action on your part.

Relative position

Each annotation stores its position as a percentage (0-1) relative to the element's dimensions:

• x: Horizontal position (0 = left, 1 = right)
• y: Vertical position (0 = top, 1 = bottom)

This allows:

• Multiple annotations on the same element at different positions
• Accurate repositioning even if element size changes
• Preserving pin location during responsive design changes

Best practices

Annotate stable elements

Prefer elements with:

• Unique IDs
• Semantic classes
• Stable DOM structure

Avoid temporary elements

Avoid annotating:

• Dynamically generated elements without stable identifiers
• Elements in uncontrolled iframes
• Elements that frequently change structure

Check orphaned annotations

Periodically check your orphaned annotations:

• They may indicate significant changes on your site
• Use them to document the evolution of your interface
• Re-annotate if necessary after major refactorings

Performance optimizations

EchoPastel uses several optimizations to ensure optimal performance:

1. Debounced repositioning - Prevents excessive recalculations during rapid DOM changes
2. Targeted observers - Only observes containers that have annotations
3. Passive listeners - Scroll events use passive mode for better performance
4. Throttled updates - Annotation positions update at most every 50-100ms

Browser compatibility

The annotation system works on:

• ✅ Chrome/Edge: Full support
• ✅ Firefox: Full support
• ✅ Safari: Full support
• ❌ IE11: Not supported (uses modern APIs)

Next steps

• Discover collaboration - Share and collaborate on your annotations
• Explore the fingerprint system - Understand in detail how identification works
• Use on mobile - Test your interfaces on all devices