diff --git a/.changeset/cursor-awareness-api-improvements.md b/.changeset/cursor-awareness-api-improvements.md deleted file mode 100644 index 2a2686a1..00000000 --- a/.changeset/cursor-awareness-api-improvements.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -"playhtml": minor -"@playhtml/common": minor -"@playhtml/react": minor ---- - -Add cursor presence and stable awareness APIs with improved element awareness scoping - -This release adds new APIs for accessing cursor positions and per-user awareness data keyed by stable user IDs, eliminating the need to access internal providers directly. - -**New Cursor Presence APIs:** - -```typescript -// Get all cursor presences (slim shape, keyed by stable ID) -const presences = playhtml.cursorClient.getCursorPresences(); - -// Subscribe to cursor presence changes -const unsubscribe = playhtml.cursorClient.onCursorPresencesChange((presences) => { - // presences is Map -}); - -// Get my stable player identity -const identity = playhtml.cursorClient.getMyPlayerIdentity(); -const stableId = identity.publicKey; // Persists across sessions -``` - -**New Awareness API - awarenessByStableId:** - -Element awareness is now provided keyed by stable user ID in addition to the array format: - -```typescript -// Core playhtml -updateElementAwareness: ({ awareness, awarenessByStableId }) => { - const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; -} - -// React withSharedState -withSharedState(({ data, awareness, awarenessByStableId, myAwareness }) => { - const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; - // ... -}); -``` - -**New React Hook:** - -```typescript -import { useCursorPresences } from "@playhtml/react"; - -function MyComponent() { - const cursorPresences = useCursorPresences(); - // Map keyed by stable ID -} -``` - -**Breaking Change - Awareness Scope:** - -Element awareness now follows cursor scope instead of always being page-specific: -- If cursors are configured with `room: "domain"`, element awareness is domain-wide -- If cursors are configured with `room: "page"`, element awareness is page-specific -- If cursors are configured with `room: "section"`, element awareness is section-specific - -This is more intuitive (your user state follows you) but may affect apps that relied on the old behavior. To restore page-specific awareness when cursors are domain-wide, you can configure cursors to use page scope separately. - -**Benefits:** - -- Stable user IDs (`playerIdentity.publicKey`) persist across page refreshes -- No need to access `(playhtml.cursorClient as any).provider` - use clean public APIs -- Easier to correlate cursor positions with user-specific awareness data -- Awareness scope matches cursor scope for more intuitive behavior diff --git a/.changeset/cursor-room-support.md b/.changeset/cursor-room-support.md deleted file mode 100644 index 8ec6e0c8..00000000 --- a/.changeset/cursor-room-support.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"playhtml": minor -"@playhtml/common": minor -"@playhtml/react": minor ---- - -Add composable cursor room configuration with filtering and styling options. diff --git a/.changeset/remove-element-data.md b/.changeset/remove-element-data.md deleted file mode 100644 index 094067e7..00000000 --- a/.changeset/remove-element-data.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -"@playhtml/react": minor -"playhtml": minor ---- - -Add `removeElementData` API for cleaning up orphaned element data - -This release adds a new `removeElementData(tag, elementId)` function to both the core `playhtml` package and the React wrapper. This function allows you to clean up orphaned data when elements are deleted, preventing accumulation of stale data in the database. - -**Usage:** - -```tsx -import { removeElementData } from "@playhtml/react"; - -// Or access via playhtml object -import { playhtml } from "@playhtml/react"; -playhtml.removeElementData("can-move", elementId); -``` diff --git a/packages/common/CHANGELOG.md b/packages/common/CHANGELOG.md index 0ac27b37..bdbf0c7f 100644 --- a/packages/common/CHANGELOG.md +++ b/packages/common/CHANGELOG.md @@ -1,5 +1,78 @@ # @playhtml/common +## 0.4.0 + +### Minor Changes + +- 1427a62: Add cursor presence and stable awareness APIs with improved element awareness scoping + + This release adds new APIs for accessing cursor positions and per-user awareness data keyed by stable user IDs, eliminating the need to access internal providers directly. + + **New Cursor Presence APIs:** + + ```typescript + // Get all cursor presences (slim shape, keyed by stable ID) + const presences = playhtml.cursorClient.getCursorPresences(); + + // Subscribe to cursor presence changes + const unsubscribe = playhtml.cursorClient.onCursorPresencesChange( + (presences) => { + // presences is Map + } + ); + + // Get my stable player identity + const identity = playhtml.cursorClient.getMyPlayerIdentity(); + const stableId = identity.publicKey; // Persists across sessions + ``` + + **New Awareness API - awarenessByStableId:** + + Element awareness is now provided keyed by stable user ID in addition to the array format: + + ```typescript + // Core playhtml + updateElementAwareness: ({ awareness, awarenessByStableId }) => { + const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; + }; + + // React withSharedState + withSharedState(({ data, awareness, awarenessByStableId, myAwareness }) => { + const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; + // ... + }); + ``` + + **New React Hook:** + + ```typescript + import { useCursorPresences } from "@playhtml/react"; + + function MyComponent() { + const cursorPresences = useCursorPresences(); + // Map keyed by stable ID + } + ``` + + **Breaking Change - Awareness Scope:** + + Element awareness now follows cursor scope instead of always being page-specific: + + - If cursors are configured with `room: "domain"`, element awareness is domain-wide + - If cursors are configured with `room: "page"`, element awareness is page-specific + - If cursors are configured with `room: "section"`, element awareness is section-specific + + This is more intuitive (your user state follows you) but may affect apps that relied on the old behavior. To restore page-specific awareness when cursors are domain-wide, you can configure cursors to use page scope separately. + + **Benefits:** + + - Stable user IDs (`playerIdentity.publicKey`) persist across page refreshes + - No need to access `(playhtml.cursorClient as any).provider` - use clean public APIs + - Easier to correlate cursor positions with user-specific awareness data + - Awareness scope matches cursor scope for more intuitive behavior + +- 3e385c7: Add composable cursor room configuration with filtering and styling options. + ## 0.3.1 ### Patch Changes diff --git a/packages/common/package.json b/packages/common/package.json index 666272a4..95bc4be9 100644 --- a/packages/common/package.json +++ b/packages/common/package.json @@ -1,7 +1,7 @@ { "name": "@playhtml/common", "description": "Common types for playhtml packages", - "version": "0.3.1", + "version": "0.4.0", "license": "MIT", "type": "module", "author": "Spencer Chang ", diff --git a/packages/extension/CHANGELOG.md b/packages/extension/CHANGELOG.md index 13f489b4..549bb6c7 100644 --- a/packages/extension/CHANGELOG.md +++ b/packages/extension/CHANGELOG.md @@ -1,5 +1,16 @@ # @playhtml/extension +## 0.1.6 + +### Patch Changes + +- Updated dependencies [1427a62] +- Updated dependencies [3e385c7] +- Updated dependencies [7cc91bd] + - playhtml@2.6.0 + - @playhtml/common@0.4.0 + - @playhtml/react@0.8.0 + ## 0.1.5 ### Patch Changes diff --git a/packages/extension/package.json b/packages/extension/package.json index fa8d5f3c..f7fc2ca3 100644 --- a/packages/extension/package.json +++ b/packages/extension/package.json @@ -1,6 +1,6 @@ { "name": "@playhtml/extension", - "version": "0.1.5", + "version": "0.1.6", "private": true, "type": "module", "scripts": { diff --git a/packages/playhtml/CHANGELOG.md b/packages/playhtml/CHANGELOG.md index 1251a006..067fb887 100644 --- a/packages/playhtml/CHANGELOG.md +++ b/packages/playhtml/CHANGELOG.md @@ -1,5 +1,97 @@ # Change Log +## 2.6.0 + +### Minor Changes + +- 1427a62: Add cursor presence and stable awareness APIs with improved element awareness scoping + + This release adds new APIs for accessing cursor positions and per-user awareness data keyed by stable user IDs, eliminating the need to access internal providers directly. + + **New Cursor Presence APIs:** + + ```typescript + // Get all cursor presences (slim shape, keyed by stable ID) + const presences = playhtml.cursorClient.getCursorPresences(); + + // Subscribe to cursor presence changes + const unsubscribe = playhtml.cursorClient.onCursorPresencesChange( + (presences) => { + // presences is Map + } + ); + + // Get my stable player identity + const identity = playhtml.cursorClient.getMyPlayerIdentity(); + const stableId = identity.publicKey; // Persists across sessions + ``` + + **New Awareness API - awarenessByStableId:** + + Element awareness is now provided keyed by stable user ID in addition to the array format: + + ```typescript + // Core playhtml + updateElementAwareness: ({ awareness, awarenessByStableId }) => { + const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; + }; + + // React withSharedState + withSharedState(({ data, awareness, awarenessByStableId, myAwareness }) => { + const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; + // ... + }); + ``` + + **New React Hook:** + + ```typescript + import { useCursorPresences } from "@playhtml/react"; + + function MyComponent() { + const cursorPresences = useCursorPresences(); + // Map keyed by stable ID + } + ``` + + **Breaking Change - Awareness Scope:** + + Element awareness now follows cursor scope instead of always being page-specific: + + - If cursors are configured with `room: "domain"`, element awareness is domain-wide + - If cursors are configured with `room: "page"`, element awareness is page-specific + - If cursors are configured with `room: "section"`, element awareness is section-specific + + This is more intuitive (your user state follows you) but may affect apps that relied on the old behavior. To restore page-specific awareness when cursors are domain-wide, you can configure cursors to use page scope separately. + + **Benefits:** + + - Stable user IDs (`playerIdentity.publicKey`) persist across page refreshes + - No need to access `(playhtml.cursorClient as any).provider` - use clean public APIs + - Easier to correlate cursor positions with user-specific awareness data + - Awareness scope matches cursor scope for more intuitive behavior + +- 3e385c7: Add composable cursor room configuration with filtering and styling options. +- 7cc91bd: Add `removeElementData` API for cleaning up orphaned element data + + This release adds a new `removeElementData(tag, elementId)` function to both the core `playhtml` package and the React wrapper. This function allows you to clean up orphaned data when elements are deleted, preventing accumulation of stale data in the database. + + **Usage:** + + ```tsx + import { removeElementData } from "@playhtml/react"; + + // Or access via playhtml object + import { playhtml } from "@playhtml/react"; + playhtml.removeElementData("can-move", elementId); + ``` + +### Patch Changes + +- Updated dependencies [1427a62] +- Updated dependencies [3e385c7] + - @playhtml/common@0.4.0 + ## 2.5.1 ### Patch Changes diff --git a/packages/playhtml/package.json b/packages/playhtml/package.json index a7c89216..7d047f42 100644 --- a/packages/playhtml/package.json +++ b/packages/playhtml/package.json @@ -2,7 +2,7 @@ "name": "playhtml", "title": "playhtml", "description": "Create interactive, collaborative html elements with a single attribute", - "version": "2.5.1", + "version": "2.6.0", "license": "MIT", "type": "module", "keywords": [ @@ -61,7 +61,7 @@ "happy-dom": "^15.11.6" }, "dependencies": { - "@playhtml/common": "0.3.1", + "@playhtml/common": "0.4.0", "@syncedstore/core": "^0.6.0", "y-partykit": "^0.0.31", "yjs": "13.6.18" diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md index b1cc52ed..9955e03d 100644 --- a/packages/react/CHANGELOG.md +++ b/packages/react/CHANGELOG.md @@ -1,5 +1,99 @@ # Change Log +## 0.8.0 + +### Minor Changes + +- 1427a62: Add cursor presence and stable awareness APIs with improved element awareness scoping + + This release adds new APIs for accessing cursor positions and per-user awareness data keyed by stable user IDs, eliminating the need to access internal providers directly. + + **New Cursor Presence APIs:** + + ```typescript + // Get all cursor presences (slim shape, keyed by stable ID) + const presences = playhtml.cursorClient.getCursorPresences(); + + // Subscribe to cursor presence changes + const unsubscribe = playhtml.cursorClient.onCursorPresencesChange( + (presences) => { + // presences is Map + } + ); + + // Get my stable player identity + const identity = playhtml.cursorClient.getMyPlayerIdentity(); + const stableId = identity.publicKey; // Persists across sessions + ``` + + **New Awareness API - awarenessByStableId:** + + Element awareness is now provided keyed by stable user ID in addition to the array format: + + ```typescript + // Core playhtml + updateElementAwareness: ({ awareness, awarenessByStableId }) => { + const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; + }; + + // React withSharedState + withSharedState(({ data, awareness, awarenessByStableId, myAwareness }) => { + const userDrunkLevel = awarenessByStableId.get(stableId)?.drunkLevel; + // ... + }); + ``` + + **New React Hook:** + + ```typescript + import { useCursorPresences } from "@playhtml/react"; + + function MyComponent() { + const cursorPresences = useCursorPresences(); + // Map keyed by stable ID + } + ``` + + **Breaking Change - Awareness Scope:** + + Element awareness now follows cursor scope instead of always being page-specific: + + - If cursors are configured with `room: "domain"`, element awareness is domain-wide + - If cursors are configured with `room: "page"`, element awareness is page-specific + - If cursors are configured with `room: "section"`, element awareness is section-specific + + This is more intuitive (your user state follows you) but may affect apps that relied on the old behavior. To restore page-specific awareness when cursors are domain-wide, you can configure cursors to use page scope separately. + + **Benefits:** + + - Stable user IDs (`playerIdentity.publicKey`) persist across page refreshes + - No need to access `(playhtml.cursorClient as any).provider` - use clean public APIs + - Easier to correlate cursor positions with user-specific awareness data + - Awareness scope matches cursor scope for more intuitive behavior + +- 3e385c7: Add composable cursor room configuration with filtering and styling options. +- 7cc91bd: Add `removeElementData` API for cleaning up orphaned element data + + This release adds a new `removeElementData(tag, elementId)` function to both the core `playhtml` package and the React wrapper. This function allows you to clean up orphaned data when elements are deleted, preventing accumulation of stale data in the database. + + **Usage:** + + ```tsx + import { removeElementData } from "@playhtml/react"; + + // Or access via playhtml object + import { playhtml } from "@playhtml/react"; + playhtml.removeElementData("can-move", elementId); + ``` + +### Patch Changes + +- Updated dependencies [1427a62] +- Updated dependencies [3e385c7] +- Updated dependencies [7cc91bd] + - playhtml@2.6.0 + - @playhtml/common@0.4.0 + ## 0.7.0 ### Minor Changes diff --git a/packages/react/package.json b/packages/react/package.json index fe049a18..ef7222ff 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -1,7 +1,7 @@ { "name": "@playhtml/react", "description": "Create interactive, collaborative html elements in React", - "version": "0.7.0", + "version": "0.8.0", "license": "MIT", "type": "module", "keywords": [ @@ -61,9 +61,9 @@ "vitest": "^3.1.1" }, "dependencies": { - "@playhtml/common": "^0.3.0", + "@playhtml/common": "^0.4.0", "classnames": "^2.3.2", - "playhtml": "^2.5.0", + "playhtml": "^2.6.0", "react": "^16.8.0 || ^17.0.0 || ^18.2.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.2.0 || ^19.0.0" },