playhtml 2.5.1 → 2.7.0

package/dist/main.d.ts

@@ -1,6 +1,7 @@
 import { Cursor } from '../../common/src';
 import { CursorEvents } from '../../../common/src';
 import { CursorPresence } from '../../common/src';
+import { CursorPresenceView } from '../../../common/src';
 import { default as default_2 } from 'y-partykit/provider';
 import { ElementAwarenessEventHandlerData } from '../../common/src';
 import { ElementData } from '../../common/src';
@@ -11,10 +12,10 @@ import { EventMessage } from '../../common/src';
 import { MappedTypeDescription } from '@syncedstore/core/types/doc';
 import { ModifierKey } from '../../common/src';
 import { PlayerIdentity } from '../../common/src';
+import { PlayerIdentity as PlayerIdentity_2 } from '../../../common/src';
 import { PlayEvent } from '../../common/src';
 import { RegisteredPlayEvent } from '../../common/src';
 import { TagType } from '../../common/src';
-import * as Y from 'yjs';
 
 export { Cursor }
 
@@ -22,6 +23,7 @@ declare class CursorClientAwareness {
     private provider;
     private options;
     private cursors;
+    private cursorAnimators;
     private spatialGrid;
     private proximityUsers;
     private currentCursor;
@@ -31,10 +33,13 @@ declare class CursorClientAwareness {
     private visibilityThreshold;
     private isStylesAdded;
     private globalApiListeners;
+    private activeAnimationCleanups;
     private allPlayerColors;
     private chat;
     private currentMessage;
     private otherUsersWithMessages;
+    private cursorPresenceChangeCallbacks;
+    private coordinateMode;
     constructor(provider: default_2, options?: CursorOptions);
     private initialize;
     private setupAwarenessHandling;
@@ -44,6 +49,7 @@ declare class CursorClientAwareness {
     private checkProximityOptimized;
     private addCursorStyles;
     private setupCursorTracking;
+    private repositionAllCursors;
     private throttledUpdateCursorAwareness;
     private updateCursorAwareness;
     private updateCursor;
@@ -77,14 +83,29 @@ declare class CursorClientAwareness {
     on<K extends keyof CursorEvents>(event: K, callback: (value: CursorEvents[K]) => void): void;
     off<K extends keyof CursorEvents>(event: K, callback: (value: CursorEvents[K]) => void): void;
     getSnapshot(): CursorEvents;
+    getMyPlayerIdentity(): PlayerIdentity_2;
+    getProvider(): default_2;
+    getCursorPresences(): Map<string, CursorPresenceView>;
+    onCursorPresencesChange(callback: (presences: Map<string, CursorPresenceView>) => void): () => void;
+    private notifyCursorPresenceListeners;
+    /**
+     * Apply a CSS class to a specific cursor element identified by the player's stableId (publicKey).
+     * The class is added to the actual rendered cursor DOM element and removed after `durationMs`.
+     * Returns true if the cursor element was found and the animation was applied.
+     */
+    triggerCursorAnimation(stableId: string, animationClass: string, durationMs?: number): boolean;
+    private triggerSelfCursorAnimation;
 }
 
+export declare type CursorCoordinateMode = "relative" | "absolute";
+
 export declare interface CursorOptions {
     enabled?: boolean;
     playerIdentity?: PlayerIdentity;
     proximityThreshold?: number;
     visibilityThreshold?: number;
     cursorStyle?: string;
+    coordinateMode?: CursorCoordinateMode;
     onProximityEntered?: (playerIdentity?: PlayerIdentity, positions?: {
         ours: {
             x: number;
@@ -115,12 +136,29 @@ declare interface DefaultRoomOptions {
     includeSearch?: boolean;
 }
 
+/**
+ * Completely deletes all shared collaborative data for an element.
+ * This is a destructive operation that removes data across all clients.
+ * This includes:
+ * - SyncedStore data (store.play[tag][elementId])
+ * - Observer subscriptions
+ * - Element handlers
+ *
+ * Use this when you want to permanently delete an element's data.
+ * For just removing a DOM element while keeping data, use removePlayElement instead.
+ *
+ * @param tag - The capability tag (e.g., "can-move", "can-toggle")
+ * @param elementId - The element ID
+ */
+declare function deleteElementData(tag: string, elementId: string): void;
+
 declare function dispatchPlayEvent(message: EventMessage): void;
 
 declare class ElementHandler<T = any, U = any, V = any> {
     defaultData: T;
     localData: U;
     awareness: V[];
+    awarenessByStableId: Map<string, V>;
     selfAwareness?: V;
     element: HTMLElement;
     _data: T;
@@ -146,7 +184,7 @@ declare class ElementHandler<T = any, U = any, V = any> {
      * (e.g. calling `updateElement` and `onChange`)
      */
     set __data(data: T);
-    set __awareness(data: V[]);
+    updateAwareness(data: V[], byStableId: Map<string, V>): void;
     getEventHandlerData(): ElementEventHandlerData<T, U, V>;
     getAwarenessEventHandlerData(): ElementAwarenessEventHandlerData<T, U, V>;
     getSetupData(): ElementSetupData<T, U>;
@@ -182,8 +220,6 @@ declare class ElementHandler<T = any, U = any, V = any> {
     reset(): void;
 }
 
-declare let globalData: Y.Map<any>;
-
 export declare interface InitOptions<T = unknown> {
     /**
      * The room to connect users to (this should be a string that matches the other users
@@ -238,9 +274,9 @@ export declare interface PlayHTMLComponents {
     setupPlayElements: typeof setupElements;
     setupPlayElement: typeof setupPlayElement;
     removePlayElement: typeof removePlayElement;
+    deleteElementData: typeof deleteElementData;
     setupPlayElementForTag: typeof setupPlayElementForTag;
     syncedStore: (typeof store)["play"];
-    globalData: typeof globalData;
     elementHandlers: Map<string, Map<string, ElementHandler>>;
     eventHandlers: Map<string, Array<RegisteredPlayEvent>>;
     dispatchPlayEvent: typeof dispatchPlayEvent;
@@ -265,6 +301,13 @@ export declare interface PlayHTMLComponents {
  */
 declare function registerPlayEventListener(type: string, event: Omit<PlayEvent, "type">): string;
 
+/**
+ * Removes the element handler for a DOM element from local state.
+ * This unregisters the element but preserves all shared collaborative data.
+ * Use this when a DOM element is removed/unmounted but you want to keep the data.
+ *
+ * @param element - The DOM element to unregister
+ */
 declare function removePlayElement(element: Element | null): void;
 
 /**