@rtc-agent/component 0.2.7-rc.3 → 0.2.8-rc.0

package/dist/utils/message-virtual-scroll.d.ts

@@ -0,0 +1,595 @@
+/**
+ * Message Virtual Scroll - Inspired by Telegram Web
+ *
+ * Architecture (mirrors Telegram's bubbles.ts + appMessagesManager):
+ * 1. Data layer: external repository = "cache" (like appMessagesManager)
+ * 2. DOM layer: _elementMap = rendered DOM elements (like bubbles)
+ * 3. Viewport slicing: classify into invisibleTop/visible/invisibleBottom
+ * 4. Delete slice: remove off-screen DOM, mark loadedTop/Bottom = false
+ * 5. Restore: when scrolling back, onLoadMore loads from cache using window boundary IDs
+ *
+ * Key Telegram references:
+ * - loadMoreHistory: components/chat/bubbles.ts:4570
+ *   - getRenderedHistory('asc') → [firstMid, ..., lastMid]
+ *   - getHistory1(history[0], true) for top
+ *   - getHistory1(history[last], false, true) for bottom
+ */
+import { VisibilityManager, VisibilityState } from './visibility-manager.js';
+/**
+ * Stateful component interface - components can implement this to preserve state
+ * across virtualization (destroy/restore cycles).
+ */
+export interface StatefulComponent {
+    getState(): Record<string, unknown>;
+    setState(state: Record<string, unknown>): void;
+}
+export interface WindowBoundary {
+    /** First item's ID in current window (undefined if empty) */
+    firstId: string | undefined;
+    /** Last item's ID in current window (undefined if empty) */
+    lastId: string | undefined;
+}
+export interface MessageVirtualScrollOptions<T> {
+    scrollContainer: HTMLElement;
+    innerContainer: HTMLElement;
+    renderItem: (item: T, index: number) => HTMLElement;
+    getItemId: (item: T) => string;
+    /**
+     * Called when scrolling near edge and more messages may be available.
+     * Receives current window boundary - use it to load adjacent messages from cache.
+     * Return empty array to signal no more messages in that direction.
+     *
+     * Mirrors Telegram's loadMoreHistory → getHistory1(maxId, reverse) pattern.
+     */
+    onLoadMore?: (direction: 'top' | 'bottom', boundary: WindowBoundary) => Promise<T[]>;
+    /** CSS selector for message elements (default: '.message') */
+    query?: string;
+    /**
+     * Preload threshold - start loading when this far from edge (px, default: 300).
+     * Telegram uses 300px (onScrollOffset = 300).
+     */
+    preloadThreshold?: number;
+    /** Messages to keep as buffer on each side of viewport (default: 20) */
+    bufferMessages?: number;
+    /** Callback when content size changes (for custom scrollbar) */
+    onSizeChange?: () => void;
+    /**
+     * Extract the "changeable content" from an item for comparison.
+     * Only the returned value is compared to detect changes.
+     * This is more efficient than JSON.stringify on the entire item.
+     *
+     * Example: For messages, return {content, status, timestamp} to ignore
+     * internal fields that don't affect rendering.
+     *
+     * If not provided, falls back to JSON.stringify comparison.
+     */
+    getChangeableContent?: (item: T) => unknown;
+    /**
+     * Update an existing element in-place with new item data.
+     * If provided, updateItemById and updateItems will call this instead of
+     * destroying and recreating the element. This preserves DOM state
+     * (e.g., rendered Markdown) and prevents visual flicker during streaming.
+     *
+     * The callback should update the element's properties to reflect the new item.
+     * If not provided, falls back to destroy-rebuild pattern.
+     */
+    updateItemElement?: (element: HTMLElement, item: T, index: number) => void;
+    /**
+     * Create a skeleton placeholder element for an item being virtualized.
+     * If not provided, uses MessageSkeletonGenerator to create default skeletons.
+     */
+    createPlaceholder?: (item: T, height: number) => HTMLElement;
+    /**
+     * Extract component state before destroying an element (for state preservation).
+     * Called during viewport slicing before replacing with skeleton.
+     */
+    extractComponentState?: (item: T, element: HTMLElement) => Record<string, unknown> | null;
+    /**
+     * Inject component state after restoring an element from skeleton.
+     * Called synchronously before first render to avoid flicker.
+     */
+    injectComponentState?: (item: T, element: HTMLElement, state: Record<string, unknown>) => void;
+    /**
+     * Check if an item is stable (safe to virtualize).
+     * Unstable items (e.g., streaming messages) are not replaced with skeletons.
+     */
+    isItemStable?: (item: T) => boolean;
+}
+export declare class MessageVirtualScroll<T> {
+    private _scrollContainer;
+    private _innerContainer;
+    private _renderItem;
+    private _getItemId;
+    private _onLoadMore?;
+    private _onSizeChange?;
+    private _getChangeableContent?;
+    private _updateItemElement?;
+    private _query;
+    private _preloadThreshold;
+    private _bufferMessages;
+    /** Currently loaded window of items */
+    private _items;
+    /** Map from item index to DOM element */
+    private _elementMap;
+    /** Map from item ID to index for O(1) lookup */
+    private _idToIndex;
+    /**
+     * loadedTop = true means "no more messages above the current window"
+     * loadedBottom = true means "no more messages below the current window"
+     *
+     * When viewport is sliced, these become false, signaling that scrolling
+     * back should trigger onLoadMore to restore destroyed messages.
+     * (Mirrors Telegram's scrollable.loadedAll)
+     */
+    private _loadedTop;
+    private _loadedBottom;
+    private _isLoading;
+    private _scrollHandler;
+    private _sliceDebounceTimer;
+    private _sliceDebounceDelay;
+    /** User interaction state for distinguishing user vs programmatic scrolls */
+    private _isUserInteracting;
+    private _interactionCleanup;
+    /** New callback options for skeleton placeholder support */
+    private _createPlaceholder?;
+    private _extractComponentState?;
+    private _injectComponentState?;
+    private _isItemStable?;
+    /** Height cache: itemId → last known height */
+    private _heightCache;
+    /** Component state cache: itemId → state object */
+    private _componentStateCache;
+    /** Element height tracker using ResizeObserver */
+    private _itemResizeObserver?;
+    /** Capacity limit for component state cache */
+    private readonly MAX_STATE_CACHE;
+    /** S5: Capacity limit for height cache (larger since entries are smaller) */
+    private readonly MAX_HEIGHT_CACHE;
+    /** Pending restoration queue */
+    private _pendingRestorations;
+    /** Whether a batch restoration is already scheduled */
+    private _restorationScheduled;
+    /** Last scroll top for direction detection */
+    private _lastScrollTop;
+    /** Maximum restorations per frame */
+    private readonly MAX_RESTORATIONS_PER_FRAME;
+    /** Visibility manager: tracks VISIBLE/HIDDEN/TRANSITIONING state */
+    private _visibilityManager;
+    /** Skeleton tracker: unified lifecycle management for placeholders */
+    private _skeletonTracker;
+    /** Minimum interval between _sliceViewport calls (ms) */
+    private readonly MIN_SLICE_INTERVAL;
+    /** Timestamp of last _sliceViewport call (prevents double invocation) */
+    private _lastSliceTime;
+    /** Active streaming item IDs - prevents skeletonization during streaming */
+    private _activeStreams;
+    /** ResizeObserver for scroll container - rebuilds placeholder positions on resize */
+    private _containerResizeObserver?;
+    /** Unsubscribe function for visibility manager state changes */
+    private _visibilityUnsubscribe?;
+    /** Cleanup for document visibilitychange listener */
+    private _documentVisibilityCleanup?;
+    /**
+     * Cold storage: historical messages that have been settled out of the hot window.
+     * Items are moved here when _items exceeds MAX_HOT_ITEMS.
+     * The repository serves as the authoritative external cache; we only track a
+     * settled counter for logging — no secondary buffer, to avoid memory leaks.
+     */
+    private _settledCount;
+    /** Maximum items in hot storage before settling to cold */
+    private readonly MAX_HOT_ITEMS;
+    constructor(options: MessageVirtualScrollOptions<T>);
+    /**
+     * Declarative API: Set items and automatically apply optimal DOM operations.
+     *
+     * This is the main entry point for consumers. It internally diffs old vs new items
+     * and applies the minimal DOM operations:
+     * - Empty → items: Full render with scroll to bottom (initial load)
+     * - Items → empty: Clear all
+     * - Items changed: Detect prepend/append/update/middle-insert and apply optimal operations
+     *
+     * Scroll compensation is handled automatically via ScrollSaver.
+     */
+    setItems(newItems: T[]): void;
+    /**
+     * Compute diff between old and new items.
+     * Detects: prepended (before old first), appended (after old last),
+     * middleInserted (between old first and last), removals, and content updates.
+     */
+    private _computeDiff;
+    /**
+     * Prepend items to DOM without updating _items.
+     * Used internally by setItems.
+     */
+    private _prependToDom;
+    /**
+     * Append items to DOM without updating _items.
+     * Used internally by setItems.
+     */
+    private _appendToDom;
+    /**
+     * Shared logic for updating items in place.
+     * Used by both updateItems() and _updateInPlace().
+     */
+    private _applyItemUpdates;
+    /**
+     * Update existing items in place.
+     * Only re-renders items that have changed and are currently in the DOM.
+     * Called internally by setItems() during incremental updates.
+     */
+    private _updateInPlace;
+    /**
+     * Update items in place (e.g., when message status changes from 'syncing' to 'synced').
+     * Only re-renders items that have changed and are currently in the DOM.
+     * More efficient than setItems() which re-renders everything.
+     *
+     * Uses ID-based lookup + deep content comparison to avoid unnecessary DOM recreation.
+     * This is critical for preserving Markdown DOM when tab switching triggers reload()
+     * which returns new array references but identical content.
+     */
+    updateItems(items: T[]): void;
+    /**
+     * Deep compare two items for equality.
+     * If getChangeableContent is provided, only compares the extracted content
+     * using shallow equality (own-property reference check) — avoids the cost
+     * and key-order fragility of JSON.stringify.
+     * Otherwise, falls back to JSON.stringify comparison.
+     */
+    protected _itemsEqual(a: T, b: T): boolean;
+    /**
+     * Shallow equality for plain objects: same own keys, same values (by reference).
+     * Falls back to JSON.stringify for non-object / null values.
+     */
+    private _shallowEqual;
+    /**
+     * Mark that all messages in a direction have been loaded.
+     * Called by the consumer when repository has no more messages.
+     */
+    setFullyLoaded(direction: 'top' | 'bottom', value: boolean): void;
+    /**
+     * Prepend items (older messages) with smooth scroll compensation.
+     * Uses Telegram's ScrollSaver algorithm.
+     *
+     * IMPORTANT: Only inserts new elements at the beginning, does NOT re-render
+     * all elements. This preserves DOM element references for ScrollSaver.
+     */
+    prependItems(items: T[]): void;
+    /**
+     * Append items (newer messages) with smooth scroll compensation.
+     * Uses Telegram's ScrollSaver algorithm with reverse=false.
+     * Anchors to the LAST visible element's bottom position.
+     */
+    appendItems(items: T[]): void;
+    /**
+     * Update a single item by ID.
+     * O(1) lookup using _idToIndex map.
+     *
+     * Phase 5: Correctly handles placeholder state:
+     * - Always updates data model
+     * - If placeholder and content changed, invalidates cached state
+     * - If not placeholder, updates DOM
+     *
+     * @param itemId - The ID of the item to update
+     * @param newItem - The new item data
+     * @returns true if the item was found and updated, false otherwise
+     */
+    updateItemById(itemId: string, newItem: T): boolean;
+    clear(): void;
+    /**
+     * Get current visibility state.
+     * @deprecated Use visibilityManager.state instead
+     */
+    isVisible(): boolean;
+    /**
+     * Public API: Set visibility state.
+     * Called by parent component (rtc-message-list) when Tab visibility changes.
+     *
+     * This is the primary mechanism for the visibility state machine:
+     * - Tab switch → parent calls setVisibility(false/true)
+     * - Browser window blur/focus → parent calls setVisibility(false/true)
+     *
+     * The state machine ensures:
+     * - HIDDEN: pauses all skeletonize/restore operations
+     * - TRANSITIONING: gives browser one frame to stabilize layout
+     * - VISIBLE: synchronously restores visible skeletons before allowing interaction
+     *
+     * @param isVisible Whether the component is currently visible to the user
+     */
+    setVisibility(isVisible: boolean): void;
+    /**
+     * Get the visibility manager (for advanced use cases).
+     */
+    get visibilityManager(): VisibilityManager;
+    /**
+     * Mark an item as actively streaming.
+     * Prevents skeletonization during streaming output.
+     * Call this when WebSocket stream starts for a message.
+     */
+    markStreamStart(itemId: string): void;
+    /**
+     * Mark an item's streaming as ended.
+     * Allows skeletonization after streaming completes.
+     * Call this when WebSocket stream ends for a message.
+     */
+    markStreamEnd(itemId: string): void;
+    /**
+     * Check if an item is currently streaming.
+     */
+    isStreaming(itemId: string): boolean;
+    /**
+     * Check if an item is currently a skeleton placeholder.
+     * Used by scrollToMessage to determine if sync restoration is needed.
+     */
+    isPlaceholder(itemId: string): boolean;
+    /**
+     * Synchronously restore a skeleton placeholder to a real element.
+     * Used by scrollToMessage to ensure the target is visible before scrolling.
+     *
+     * Unlike batch restoration (which uses requestAnimationFrame), this runs
+     * synchronously so the caller can immediately scroll to the restored element.
+     */
+    syncRestorePlaceholder(itemId: string): void;
+    scrollToBottom(): void;
+    /**
+     * Synchronously restore ALL skeleton placeholders.
+     *
+     * This stabilizes scrollHeight before programmatic scrolls (e.g., scrollToBottom),
+     * preventing the "scroll target drift" bug where smooth scroll targets a stale
+     * scrollHeight while skeletons are being restored mid-animation.
+     *
+     * Uses cumulative scroll adjustment to prevent compound drift when multiple
+     * skeletons are restored: captures viewport position once before any DOM mutations,
+     * then adjusts scrollTop by the total height difference of all elements restored
+     * above the viewport in a single operation.
+     *
+     * Call this BEFORE any scrollTo/scrollIntoView to ensure the scroll target is real.
+     */
+    restoreAll(): void;
+    /**
+     * Setup user interaction tracking to distinguish user vs programmatic scrolls.
+     * Tracks pointer (mouse/touch) and keyboard interactions on the scroll container.
+     * This allows _onScroll to skip viewport slicing for programmatic scrolls (auto-scroll).
+     */
+    private _setupInteractionTracking;
+    dispose(): void;
+    getStats(): {
+        totalItems: number;
+        renderedItems: number;
+        placeholderCount: number;
+        pendingRestorationCount: number;
+        visibilityState: VisibilityState;
+        loadedTop: boolean;
+        loadedBottom: boolean;
+        firstId: string | undefined;
+        lastId: string | undefined;
+        heightCacheSize: number;
+        stateCacheSize: number;
+        activeStreamCount: number;
+        isVisible: boolean;
+    };
+    /**
+     * Get current window boundary (like Telegram's getRenderedHistory).
+     */
+    private _getWindowBoundary;
+    private _onScroll;
+    /**
+     * Phase 2: Find and schedule restoration for skeletons in the preload range.
+     * Uses fixed 2× viewport preload distance for simplicity.
+     *
+     * Visibility check: Uses visibility state machine to ensure restoration only
+     * happens when VISIBLE. This prevents the bug where restoration would fail
+     * silently when the component was hidden.
+     *
+     * Skeleton lookup: Uses SkeletonTracker.getInRange() which handles the
+     * "any part in range" check internally (including tall skeletons).
+     *
+     * Dedup: Uses SkeletonTracker's isPendingRestoration flag instead of a
+     * separate _pendingRestorationIds set, avoiding the "dedup deadlock" bug
+     * where failed restorations would never be retried.
+     */
+    private _restoreSkeletonsInRange;
+    /**
+     * Detect scroll direction (up/down) based on last scroll position.
+     */
+    private _getScrollDirection;
+    /**
+     * Schedule batch restoration with frame limit.
+     * Uses requestAnimationFrame for smooth rendering.
+     *
+     * Uses cumulative scroll adjustment: captures viewport position once before
+     * the batch, then adjusts scrollTop by the total height difference of all
+     * elements restored above the viewport in a single operation.
+     *
+     * Visibility check: Uses visibility state machine. If not VISIBLE, the batch
+     * is cancelled and pending items are unmarked so they can be retried later.
+     * This fixes the "dedup deadlock" bug where pending IDs would prevent retry.
+     */
+    private _scheduleBatchRestoration;
+    /**
+     * Classify elements into invisibleTop, visible, invisibleBottom.
+     * Mirrors Telegram's getViewportSlice (helpers/dom/getViewportSlice.ts).
+     */
+    private _getViewportSlice;
+    /**
+     * Check if the scroll container is currently visible.
+     * Uses the visibility state machine as the single source of truth.
+     *
+     * The visibility state machine (VisibilityManager) tracks:
+     * - VISIBLE: component is visible and interactive
+     * - HIDDEN: component is not visible (Tab switch or browser window blur)
+     * - TRANSITIONING: component is transitioning from hidden to visible
+     *
+     * This replaces the previous ad-hoc checks that couldn't detect
+     * visibility: hidden CSS (which preserves layout dimensions).
+     */
+    private _isContainerVisible;
+    /**
+     * Handle visibility state machine transitions.
+     * Called by VisibilityManager when state changes.
+     *
+     * State transitions:
+     * - VISIBLE → HIDDEN: Pause all operations, cancel pending timers
+     * - HIDDEN → TRANSITIONING: Prepare for restore (wait one frame for layout)
+     * - TRANSITIONING → VISIBLE: Rebuild skeleton positions, restore visible skeletons
+     */
+    private _onVisibilityStateChange;
+    /**
+     * Pause all virtual scroll operations when becoming hidden.
+     *
+     * This is the key mechanism that prevents the bug:
+     * - When Tab is hidden (visibility: hidden) or browser window loses focus,
+     *   all skeletonize/restore operations are paused
+     * - No new skeletons are created while hidden
+     * - Pending restoration timers are cancelled
+     * - When becoming visible again, state is rebuilt synchronously
+     */
+    private _pauseOperations;
+    /**
+     * Restore state when becoming visible again.
+     *
+     * This runs synchronously when the state machine transitions to VISIBLE:
+     * 1. Rebuild skeleton Y positions (layout may have changed while hidden)
+     * 2. Synchronously restore all skeletons in the current viewport
+     * 3. Allow subsequent operations
+     *
+     * This fixes the "stale Y coordinates" bug:
+     * - While hidden, layout may change (new messages, container resize)
+     * - Old Y coordinates become stale
+     * - By rebuilding positions synchronously on restore, we ensure accuracy
+     */
+    private _restoreState;
+    /**
+     * Synchronously restore all skeletons in the current viewport.
+     *
+     * Called when transitioning from hidden to visible.
+     * Unlike _restoreSkeletonsInRange (which uses rAF), this runs synchronously
+     * to ensure all visible skeletons are restored before user can interact.
+     */
+    private _restoreVisibleSkeletons;
+    /**
+     * Slice viewport: replace off-screen messages with skeleton placeholders.
+     *
+     * Phase 1: Instead of destroying elements, we replace them with skeleton
+     * placeholders that maintain the scroll height. This provides visual continuity
+     * and prevents scroll position jumps.
+     *
+     * Visibility check: Uses the visibility state machine (shouldPerformOperations)
+     * to ensure slicing only happens when the component is VISIBLE. This prevents
+     * the bug where background tabs (visibility: hidden) would have skeletons
+     * created but never restored.
+     *
+     * I3: Also checks _lastSliceTime to prevent double invocation.
+     */
+    private _sliceViewport;
+    /**
+     * Replace real element with skeleton placeholder.
+     *
+     * This is the core of Phase 1: instead of destroying off-screen elements,
+     * we replace them with skeleton placeholders that maintain the scroll height.
+     *
+     * Steps:
+     * 1. Extract component state (if supported)
+     * 2. Cache the element height
+     * 3. Create skeleton placeholder
+     * 4. Replace DOM element
+     * 5. Track placeholder via SkeletonTracker (unified lifecycle management)
+     * 6. Stop tracking height for this element (skeleton height is fixed)
+     */
+    private _replaceWithSkeleton;
+    /**
+     * Phase 2: Restore a skeleton placeholder to a real element.
+     *
+     * This is the inverse of _replaceWithSkeleton:
+     * 1. Render the real element from item data
+     * 2. Inject cached state synchronously (before first render to avoid flicker)
+     * 3. Replace skeleton with real element in DOM
+     * 4. Start tracking height for the new element
+     * 5. Adjust scroll position if needed (for elements above viewport)
+     *
+     * @param itemId - Stable ID of the item (immune to index shifts from prepend/append)
+     * @param _index - Index at scheduling time (unused; resolved via _idToIndex for correctness)
+     * @param skeletonHeight - Height of the skeleton placeholder (for scroll adjustment)
+     */
+    private _restoreSkeleton;
+    /**
+     * Internal skeleton restoration without scroll adjustment.
+     * Returns height diff info for batch scroll adjustment.
+     *
+     * @param itemId - Stable ID of the item
+     * @param skeletonHeight - Height of the skeleton placeholder
+     * @returns Restoration result or null if skipped
+     */
+    private _restoreSkeletonInternal;
+    /**
+     * Create default skeleton using MessageSkeletonGenerator.
+     * Called when createPlaceholder callback is not provided.
+     */
+    private _createDefaultSkeleton;
+    /**
+     * Determine skeleton type based on item content.
+     * Uses type guard for safe property access on generic T.
+     *
+     * NOTE: This is a fallback method. In production, `createPlaceholder` callback
+     * is always provided by the consumer (rtc-message-list.ts), which uses
+     * MessageSkeletonGenerator.create() with full type information.
+     * This method is only used if createPlaceholder is not provided.
+     */
+    private _getSkeletonType;
+    /**
+     * Cache component state with capacity limit.
+     * When cache exceeds MAX_STATE_CACHE, removes oldest half.
+     * Uses Map iterator for O(1) key access without allocation.
+     */
+    private _cacheComponentState;
+    /**
+     * S5: Set height cache with capacity limit.
+     * When cache exceeds MAX_HEIGHT_CACHE, removes oldest half.
+     * Uses Map iterator for O(1) key access without allocation.
+     */
+    private _setHeightCache;
+    /**
+     * Check if an item is stable (safe to virtualize).
+     * Unstable items should not be replaced with skeletons.
+     */
+    private _checkItemStable;
+    /**
+     * S3: Find element by itemId using O(1) map lookup.
+     * Falls back to DOM query only if not found in maps.
+     * Used for placeholder restoration and scroll-to-message.
+     */
+    protected _findElementByItemId(itemId: string): HTMLElement | null;
+    /**
+     * Find item index by itemId using _idToIndex map - O(1).
+     */
+    protected _findIndexByItemId(itemId: string): number;
+    /**
+     * Handle scroll container resize (e.g., window resize).
+     * Rebuilds all skeleton Y positions via SkeletonTracker since cached coordinates become stale.
+     *
+     * Note: Only rebuilds positions when VISIBLE. When hidden, positions will be rebuilt
+     * by _restoreState() when transitioning back to visible.
+     */
+    private _onContainerResize;
+    /**
+     * Settle excess hot items to cold storage.
+     * Called after items are added to prevent unbounded memory growth.
+     *
+     * When _items exceeds MAX_HOT_ITEMS, the oldest items are evicted and a
+     * settled counter is incremented for logging.
+     * This keeps the hot window small for fast iteration while relying on the
+     * repository as the authoritative cache for older history.
+     *
+     * IMPORTANT: After splicing _items, this method also synchronizes all index
+     * structures (_idToIndex, _elementMap, dataset.messageIndex) and removes
+     * orphaned DOM elements to prevent index drift.
+     */
+    private _settleData;
+    private _renderAll;
+    /**
+     * Rebuild the ID-to-index mapping from current _items array.
+     * Called after operations that change item indices (prepend, slice, etc.)
+     */
+    private _rebuildIdToIndex;
+    private _renderNewItems;
+}
+//# sourceMappingURL=message-virtual-scroll.d.ts.map

package/dist/utils/message-virtual-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-virtual-scroll.d.ts","sourceRoot":"","sources":["../../src/utils/message-virtual-scroll.ts"],"names":[],"mappings":"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"}

package/dist/utils/relative-time.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Relative time formatting utilities
+ *
+ * Uses native Intl.RelativeTimeFormat, no third-party library needed.
+ * Supports Chinese and English, automatically selects the best unit (seconds/minutes/hours/days/weeks/months/years).
+ */
+/**
+ * Format a timestamp as relative time
+ * @param timestamp Millisecond timestamp
+ * @param locale Locale, defaults to Chinese
+ * @returns Relative time string, e.g. "3 minutes ago", "2 hours ago", "5 days ago"
+ */
+export declare function formatRelativeTime(timestamp: number, locale?: 'zh-CN' | 'en-US'): string;
+//# sourceMappingURL=relative-time.d.ts.map

package/dist/utils/relative-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-time.d.ts","sourceRoot":"","sources":["../../src/utils/relative-time.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,OAAO,GAAG,OAAiB,GACpC,MAAM,CAYR"}

package/dist/utils/scroll-saver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ScrollSaver - Preserves scroll position across DOM changes.
+ * Directly ported from Telegram Web's ScrollSaver.
+ *
+ * Key concept:
+ * 1. save(): Record visible elements and their positions
+ * 2. DOM changes (prepend/append/delete)
+ * 3. restore(): Find anchor element, calculate position delta, adjust scrollTop
+ */
+export declare class ScrollSaver {
+    private _container;
+    private _query;
+    private _reverse;
+    private _scrollTop;
+    private _scrollHeight;
+    private _elements;
+    constructor(container: HTMLElement, query?: string, reverse?: boolean);
+    /**
+     * Save current scroll state and visible elements.
+     */
+    save(): void;
+    /**
+     * Restore scroll position after DOM changes.
+     *
+     * Fallback chain (matching Telegram Web's algorithm):
+     * 1. Try the saved anchor element
+     * 2. If anchor disconnected → re-query visible elements, pick new anchor
+     * 3. If still no anchor → fall back to scrollHeight delta
+     */
+    restore(): void;
+    private _findElements;
+    private _getAnchor;
+}
+//# sourceMappingURL=scroll-saver.d.ts.map

package/dist/utils/scroll-saver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-saver.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-saver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,qBAAa,WAAW;IACpB,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAU;IAE1B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,SAAS,CAA+C;gBAEpD,SAAS,EAAE,WAAW,EAAE,KAAK,GAAE,MAAmB,EAAE,OAAO,GAAE,OAAc;IAMvF;;OAEG;IACH,IAAI;IAMJ;;;;;;;OAOG;IACH,OAAO;IA+DP,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,UAAU;CAKrB"}