Fingerprint system

EchoPastel's fingerprint system is advanced technology that ensures your annotations remain attached to the right elements, even when the page changes.

Overview

Instead of relying solely on a CSS selector (which can easily break), EchoPastel uses a multi-strategy fingerprint system that stores multiple "fingerprints" of each annotated element.

Identification strategies

1. CSS Selector

The traditional CSS selector using element classes and IDs.

Advantages:

• Fast to generate
• Easy to understand
• Compatible with development tools

Limitations:

• Can break if classes change
• Fragile on dynamic content
• Can be ambiguous if multiple elements share the same classes

2. XPath

An XPath path based on the element's DOM structure.

Advantages:

• More stable than CSS
• Works even if classes change
• Based on structure, not styles

Limitations:

• Can break if DOM structure changes
• More complex to generate
• Can be long for deeply nested elements

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

Advantages:

• Very robust against structure changes
• Works even if the element is moved
• Can find similar elements

Limitations:

• Can be ambiguous if multiple elements have the same content
• Sensitive to text changes
• More computationally expensive

4. Context information

Information about the element's 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.

Advantages:

• Very precise for elements in lists
• Works well with dynamic containers
• Complements other strategies

Limitations:

• Can break if element order changes
• Depends on parent stability

Resolution cascade

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

Step 1: CSS Selector

element = document.querySelector(fingerprint.css)

If the CSS selector works, the element is found immediately.

Step 2: XPath

element = document.evaluate(fingerprint.xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null)

If CSS fails, we try XPath which is more stable.

Step 3: Parent + Index

parent = document.querySelector(fingerprint.context.parentSelector)
element = parent.children[fingerprint.context.siblingIndex]

If previous methods fail, we use relative position in the parent.

Step 4: Content matching

element = findBySimilarContent(fingerprint.content)

As a last resort, we search for an element with similar content.

Robustness against changes

Class changes

If CSS classes change:

• ✅ XPath can still find the element
• ✅ Content fingerprint can identify the element
• ✅ Parent context can locate the element

Structure changes

If DOM structure changes slightly:

• ✅ Content fingerprint can find a similar element
• ✅ Parent context can locate the element if the parent is stable
• ⚠️ The annotation may become orphaned if changes are too significant

Dynamic content

For dynamic content (carousels, sliders):

• ✅ The system automatically detects dynamic containers
• ✅ Specialized observers track changes
• ✅ Annotations are automatically repositioned

Orphaned annotation management

When an annotation becomes orphaned

An annotation becomes orphaned when:

• The element has been deleted from the page
• The structure has changed significantly
• The element has been moved to another part of the DOM

Orphaned annotation behavior

When an annotation is orphaned:

• It is visually marked (reduced opacity, grayscale)
• The screenshot remains accessible
• You can still see and reply to the annotation
• The annotation is not lost

Re-annotate if necessary

If an annotation becomes orphaned:

1. Check the screenshot to see what was annotated
2. If the element still exists in another form, re-annotate it
3. Use the orphaned annotation as historical reference

Performance

Optimizations

The fingerprint system uses several optimizations:

1. Result caching: Found elements are cached
2. Targeted search: Only searches in relevant areas
3. Debouncing: Searches are grouped to avoid excessive calculations
4. Lazy loading: Complex fingerprints are only calculated if necessary

Performance impact

The fingerprint system has minimal performance impact:

• Search time: Generally < 10ms per annotation
• Memory: Minimal fingerprint storage
• CPU: Optimized and cached calculations

Use cases

Static sites

For static sites:

• CSS selector works perfectly
• Annotations remain stable
• Low risk of orphaned annotations

Dynamic sites

For dynamic sites:

• Multi-strategy system ensures robustness
• Annotations follow changes
• Observers maintain positions

SPA applications

For SPA (Single Page Applications):

• The system detects route changes
• Annotations are reloaded for each route
• Fingerprint adapts to dynamic changes

Best practices

Annotate stable elements

Prefer elements with:

• Unique and stable IDs
• Semantic classes that don't change
• Relatively stable DOM structure

Avoid temporary elements

Avoid annotating:

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

Check regularly

Periodically:

• Check your orphaned annotations
• Re-annotate if necessary after major refactorings
• Use orphaned annotations as historical documentation

Next steps

• Discover annotations - Learn more about the annotation system
• Use on mobile - Test on all devices
• Collaborate effectively - Share your feedback