playhtml 2.5.0 → 2.6.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;
@@ -35,6 +37,8 @@ declare class CursorClientAwareness {
     private chat;
     private currentMessage;
     private otherUsersWithMessages;
+    private cursorPresenceChangeCallbacks;
+    private coordinateMode;
     constructor(provider: default_2, options?: CursorOptions);
     private initialize;
     private setupAwarenessHandling;
@@ -77,14 +81,22 @@ 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;
 }
 
+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;
@@ -98,20 +110,46 @@ export declare interface CursorOptions {
     onProximityLeft?: (connectionId: string) => void;
     onCustomCursorRender?: (connectionId: string, element: HTMLElement) => HTMLElement | null;
     enableChat?: boolean;
+    room?: CursorRoom;
+    shouldRenderCursor?: (presence: CursorPresence) => boolean;
+    getCursorStyle?: (presence: CursorPresence) => Partial<CSSStyleDeclaration> | Record<string, string>;
 }
 
 export { CursorPresence }
 
+export declare type CursorRoom = "page" | "domain" | "section" | ((context: {
+    domain: string;
+    pathname: string;
+    search: string;
+}) => string);
+
 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;
@@ -137,7 +175,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>;
@@ -173,8 +211,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
@@ -229,9 +265,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;
@@ -256,6 +292,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;
 
 /**