@veltdev/sdk 4.5.6-beta.15 → 4.5.6-beta.16

package/app/models/data/anchor-record.data.model.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Content hash for secure, privacy-preserving element validation.
+ */
+export interface ContentHash {
+    /** MD5 hash value (base36 encoded, ~12 characters) */
+    value: string;
+    /** Hashing algorithm (always 'md5') */
+    algorithm: 'md5';
+    /** Source of hash (always 'textContent') */
+    source: 'textContent';
+}
+/**
+ * Robust anchor record for reliable DOM element re-location.
+ *
+ * Survives:
+ * - Page reloads
+ * - Framework re-renders (React, Vue, Angular)
+ * - Dynamic ID changes
+ * - Minor DOM restructuring
+ *
+ * Does not survive:
+ * - Major redesigns
+ * - Content reordering (sort, filter)
+ * - Element removal
+ *
+ * **Resolution Strategy (priority order):**
+ * 1. id (90) - Stable, non-dynamic ID
+ * 2. css (80/60) - Attribute selector
+ * 3. robustXPath (50) - Attribute-based path
+ * 4. containerHints (40) - Scoped search
+ * 5. xPath variants (32-28) - Structural fallback
+ * 6. contentHash (15) - Hash-based scan
+ *
+ * **Validation boosts:** tagName (+10), contentHash (+30)
+ *
+ * **Security:** No plaintext storage, MD5 hash only.
+ */
+export interface AnchorRecord {
+    /** Schema version (current: "1.0") */
+    version: '1.0';
+    /**
+     * Stable element ID (non-dynamic only).
+     *
+     * Excluded patterns:
+     * - yui_* (YUI framework)
+     */
+    id?: string;
+    /** Tag name (uppercase, e.g., 'DIV', 'BUTTON') */
+    tagName: string;
+    /**
+     * CSS selector from stable attributes.
+     *
+     * Example: `[data-testid='submit-btn'][role='button']`
+     */
+    elementSelector?: string;
+    /**
+     * XPath variants (in order of stability):
+     *
+     * 1. robustXPath - Attribute-based (MOST STABLE)
+     *    - Prioritizes: data-* > role > stable ID > aria-* > position
+     *    - Example: `//div[@role='main']/.../li[5]/span`
+     *    - Ignores dynamic IDs
+     *    - Stops at landmarks (main, nav, etc.)
+     *
+     * 2. xPath - Basic XPath (uses IDs when available)
+     * 3. cfXPath - Positional with class hints
+     * 4. fXPath - Pure positional (most fragile)
+     */
+    robustXPath?: string;
+    xPath?: string;
+    fXPath?: string;
+    cfXPath?: string;
+    /**
+     * Content hash for secure validation.
+     */
+    contentHash?: ContentHash;
+    /** Creation timestamp (milliseconds since epoch) */
+    createdAt?: number;
+    /** Parent element anchor record */
+    parent?: AnchorRecord;
+}
+/**
+ * Result of anchor resolution.
+ */
+export interface AnchorResolution {
+    /** Resolved element (null if not found) */
+    element: Element | null;
+    /**
+     * Resolution method used.
+     * Values: 'id', 'css', 'robustXPath', 'xPath', 'cfXPath', 'fXPath', 'contentHash', 'ancestor+tag'
+     */
+    matchedBy?: string;
+    /**
+     * Confidence score (0-120+).
+     *
+     * - 90+: High (unique ID)
+     * - 80-89: Good (unique CSS, stable attributes)
+     * - 40-79: Moderate (scoped search, multiple candidates)
+     * - 15-39: Low (XPath, hash-based fallback)
+     */
+    score?: number;
+    /**
+     * Score breakdown.
+     */
+    scoreBreakdown?: {
+        method: string;
+        score: number;
+    }[];
+}

package/app/models/data/target-element.data.model.d.ts

@@ -1,3 +1,4 @@
+import { AnchorRecord } from './anchor-record.data.model';
 export declare class TargetElement {
     /**
      * Xpath of target element
@@ -19,4 +20,8 @@ export declare class TargetElement {
      * Relative left position of cursor on target element
      */
     leftPercentage: number;
+    /**
+     * Robust anchor descriptor for the element
+     */
+    anchor?: AnchorRecord | null;
 }

package/app/models/data/target-text-range.data.model.d.ts

@@ -1,3 +1,4 @@
+import { AnchorRecord } from "./anchor-record.data.model";
 export declare class TargetTextRange {
     /**
      * Xpath of common Ancestor Container
@@ -11,6 +12,10 @@ export declare class TargetTextRange {
      * Full xpath of common Ancestor Container with class names
      */
     commonAncestorContainerCFXpath?: string;
+    /**
+     * Anchor of common Ancestor Container
+     */
+    commonAncestorContainerAnchor?: AnchorRecord;
     /**
      * Selected text
      */

package/models.d.ts

@@ -1,4 +1,5 @@
 export * from './app/utils/enums';
+export * from './app/models/data/anchor-record.data.model';
 export * from './app/models/data/attachment.model';
 export * from './app/models/data/area-annotation.data.model';
 export * from './app/models/data/arrow-annotation.data.model';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@veltdev/sdk",
-    "version": "4.5.6-beta.15",
+    "version": "4.5.6-beta.16",
     "description": "Velt is an SDK to add collaborative features to your product within minutes. Example: Comments like Figma, Frame.io, Google docs or sheets, Recording like Loom, Huddles like Slack and much more.",
     "homepage": "https://velt.dev",
     "keywords": [