@microsoft/live-share-react 1.0.2-preview.1 → 1.2.0-preview.0

package/bin/types/ResultTypes.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 import { AzureContainerServices } from "@fluidframework/azure-client";
-import { ITimerConfig, LivePresenceUser, LiveEvent, LivePresence, LiveTimer } from "@microsoft/live-share";
+import { ITimerConfig, LivePresenceUser, LiveEvent, LivePresence, LiveTimer, IFollowModeState, FollowModePresenceUser, LiveFollowMode } from "@microsoft/live-share";
 import { InkingManager, LiveCanvas } from "@microsoft/live-share-canvas";
 import { CoordinationWaitPoint, ExtendedMediaMetadata, MediaPlayerSynchronizer } from "@microsoft/live-share-media";
 import { IFluidContainer, SharedMap } from "fluid-framework";
@@ -25,6 +25,9 @@ export interface ILiveShareContainerResults extends IAzureContainerResults {
      */
     created: boolean;
 }
+/**
+ * Return type of `useSharedMap` hook.
+ */
 export interface IUseSharedMapResults<TData> {
     /**
      * Stateful map of most recent values from `SharedMap`.
@@ -43,6 +46,9 @@ export interface IUseSharedMapResults<TData> {
      */
     sharedMap: SharedMap | undefined;
 }
+/**
+ * Return type of `useLiveEvent` hook.
+ */
 export interface IUseLiveEventResults<TEvent = any> {
     /**
      * The most recent event that has been received in the session.
@@ -63,6 +69,9 @@ export interface IUseLiveEventResults<TEvent = any> {
      */
     liveEvent: LiveEvent | undefined;
 }
+/**
+ * Return type of `useLiveTimer` hook.
+ */
 export interface IUseLiveTimerResults {
     /**
      * The current timer configuration.
@@ -93,6 +102,9 @@ export interface IUseLiveTimerResults {
      */
     pause: OnPauseTimerAction;
 }
+/**
+ * Return type of `useLivePresence` hook.
+ */
 export interface IUseLivePresenceResults<TData extends object = object> {
     /**
      * The local user's presence object.
@@ -118,6 +130,9 @@ export interface IUseLivePresenceResults<TData extends object = object> {
      */
     updatePresence: OnUpdateLivePresenceAction<TData>;
 }
+/**
+ * Return type of `useMediaSynchronizer` hook.
+ */
 export interface IUseMediaSynchronizerResults {
     /**
      * Stateful boolean on whether the session has an active suspension.
@@ -162,6 +177,9 @@ export interface IUseMediaSynchronizerResults {
      */
     mediaSynchronizer: MediaPlayerSynchronizer | undefined;
 }
+/**
+ * Return type of `useLiveCanvas` hook.
+ */
 export interface IUseLiveCanvasResults {
     /**
      * Inking manager for the canvas, which is synchronized by `liveCanvas`. It is set when loaded and undefined while loading.
@@ -172,4 +190,113 @@ export interface IUseLiveCanvasResults {
      */
     liveCanvas: LiveCanvas | undefined;
 }
+/**
+ * Return type of `useLiveFollowMode` hook.
+ */
+export interface IUseLiveFollowModeResults<TData = any> {
+    /**
+     * Gets the current follow mode state.
+     */
+    state: IFollowModeState<TData> | undefined;
+    /**
+     * Local LivePresenceUser.
+     */
+    localUser: FollowModePresenceUser<TData> | undefined;
+    /**
+     * List of non-local user's presence objects.
+     */
+    otherUsers: FollowModePresenceUser<TData>[];
+    /**
+     * List of all user's presence objects.
+     */
+    allUsers: FollowModePresenceUser<TData>[];
+    /**
+     * LiveFollowMode DDS
+     */
+    liveFollowMode: LiveFollowMode<TData> | undefined;
+    /**
+     * Broadcast a new custom data value for the local user's current state.
+     *
+     * @remarks
+     * Each user has their own state value, though it will differ from what is shown in {@link state} depending on the value of {@link FollowModeType}.
+     * Will cause the user to become out of sync if another user is presenting or the local user is following another user.
+     * To see each user's state, use the {@link getUsers} API, or listen to "presenceChanged" updates.
+     *
+     * @param newValue the state value for the local user's presence record.
+     *
+     * @returns a void promise that resolves once the update event has been sent to the server.
+     *
+     * @throws error if initialization has not yet succeeded.
+     */
+    update: (stateValue: TData) => Promise<void>;
+    /**
+     * Start presenting the local user's state.
+     *
+     * @remarks
+     * If another user is already presenting, the local user will take control of presenting from the previous presenter.
+     * To update the local user's state that both the local and remote users will reference, use the {@link update} function.
+     * This API will override any `followingUserId` value that was set through {@link followUser} until presenting has stopped.
+     * To stop presenting, use the {@link stopPresenting} API.
+     *
+     * @returns a void promise that resolves once the event has been sent to the server.
+     *
+     * @throws error if initialization has not yet succeeded.
+     * @throws error if the local user is already the presenter.
+     * @throws error if the local user does not have the required roles to present.
+     */
+    startPresenting: () => Promise<void>;
+    /**
+     * Stop presenting the presenting user's current state.
+     *
+     * @remarks
+     * This API allows any user with valid roles to cancel presenting, though we generally recommend only allowing the active presenter to do so.
+     * To start presenting, use the {@link startPresenting} API.
+     *
+     * @returns a void promise that resolves once the event has been sent to the server.
+     *
+     * @throws error if initialization has not yet succeeded.
+     * @throws error if the local user does not have the required roles to stop presenting.
+     */
+    stopPresenting: () => Promise<void>;
+    /**
+     * Temporarily stop following presenter/follower.
+     *
+     * @returns a void promise once the operation succeeds.
+     *
+     * @throws error if initialization has not yet succeeded.
+     */
+    beginSuspension: () => Promise<void>;
+    /**
+     * Resume following presenter/follower.
+     *
+     * @returns a void promise once the operation succeeds.
+     *
+     * @throws error if initialization has not yet succeeded.
+     */
+    endSuspension: () => Promise<void>;
+    /**
+     * Follows another user in the session.
+     *
+     * @remarks
+     * If another user is presenting, {@link state} will not reflect following this user until there is no longer a presenter.
+     *
+     * @param userId the userId for the user to follow.
+     *
+     * @returns a void promise that resolves once the event has been sent to the server.
+     *
+     * @throws error if initialization has not yet succeeded.
+     * @throws error if attempting to follow a user that is not recognized by this object's `LivePresence` instance.
+     * @throws error if the `userId` provided is equal to the local user's `userId`.
+     */
+    followUser: (userId: string) => Promise<void>;
+    /**
+     * Stop following the currently following user.
+     *
+     * @returns a void promise that resolves once the event has been sent to the server.
+     *
+     * @throws error if initialization has not yet succeeded.
+     * @throws error if the user is not already following another user.
+     */
+    stopFollowing: () => Promise<void>;
+}
 //# sourceMappingURL=ResultTypes.d.ts.map

package/bin/types/ResultTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResultTypes.d.ts","sourceRoot":"","sources":["../../src/types/ResultTypes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ResultTypes.d.ts","sourceRoot":"","sources":["../../src/types/ResultTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EACH,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,EACH,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACH,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,EACtB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,sBAAsB;IACnC;;OAEG;IACH,SAAS,EAAE,eAAe,CAAC;IAC3B;;OAEG;IACH,QAAQ,EAAE,sBAAsB,CAAC;CACpC;AAED,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACtE;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACvC;;OAEG;IACH,GAAG,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAChC;;OAEG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9C;;OAEG;IACH,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;OAEG;IACH,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,MAAM,GAAG,GAAG;IAC9C;;OAEG;IACH,WAAW,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACnD;;OAEG;IACH,SAAS,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;IACvC;;;;OAIG;IACH,SAAS,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACvC;;OAEG;IACH,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC;;OAEG;IACH,WAAW,EAAE,YAAY,GAAG,SAAS,CAAC;IACtC;;OAEG;IACH,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;OAEG;IACH,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,KAAK,EAAE,kBAAkB,CAAC;IAC1B;;;OAGG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;OAGG;IACH,KAAK,EAAE,kBAAkB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAClE;;OAEG;IACH,SAAS,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAC/C;;OAEG;IACH,UAAU,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC;;OAEG;IACH,QAAQ,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;IACpC;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAC9C;;;;;OAKG;IACH,cAAc,EAAE,0BAA0B,CAAC,KAAK,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IACzC;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;OAGG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B;;;;OAIG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC;;;;OAIG;IACH,QAAQ,EAAE,CACN,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,MAAM,GAAG,IAAI,KACpD,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;;;OAMG;IACH,eAAe,EAAE,CAAC,SAAS,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC7D;;OAEG;IACH,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,uBAAuB,GAAG,SAAS,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,aAAa,EAAE,aAAa,GAAG,SAAS,CAAC;IACzC;;OAEG;IACH,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,KAAK,GAAG,GAAG;IAClD;;OAEG;IACH,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAC3C;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IACrD;;OAEG;IACH,UAAU,EAAE,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;IAC5C;;OAEG;IACH,QAAQ,EAAE,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1C;;OAEG;IACH,cAAc,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAClD;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;;;;;;;;;;;OAcG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;;;;;;;;;;;OAWG;IACH,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;;;;;;;;;;;OAaG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/live-share-react",
-  "version": "1.0.2-preview.1",
+  "version": "1.2.0-preview.0",
   "description": "Build collaborative React apps using Microsoft's Fluid & Live Share frameworks with ease.",
   "author": "Microsoft",
   "license": "SEE LICENSE IN LICENSE",
@@ -12,7 +12,7 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@microsoft/live-share-turbo": "1.0.2-preview.1",
+    "@microsoft/live-share-turbo": "1.2.0-preview.0",
     "url": "^0.11.0",
     "uuid": "^9.0.0"
   },
@@ -20,9 +20,9 @@
     "@babel/core": "^7.21.8",
     "@fluidframework/azure-client": "^1.1.1",
     "@fluidframework/test-client-utils": "^1.3.6",
-    "@microsoft/live-share": "1.0.2",
-    "@microsoft/live-share-canvas": "1.0.2",
-    "@microsoft/live-share-media": "1.0.2",
+    "@microsoft/live-share": "1.2.0",
+    "@microsoft/live-share-canvas": "1.2.0",
+    "@microsoft/live-share-media": "1.2.0",
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
     "@types/uuid": "^9.0.1",
@@ -32,9 +32,9 @@
   },
   "peerDependencies": {
     "@fluidframework/azure-client": "^1.0.0",
-    "@microsoft/live-share": "1.0.2",
-    "@microsoft/live-share-canvas": "1.0.2",
-    "@microsoft/live-share-media": "1.0.2",
+    "@microsoft/live-share": "1.2.0",
+    "@microsoft/live-share-canvas": "1.2.0",
+    "@microsoft/live-share-media": "1.2.0",
     "fluid-framework": "^1.2.3",
     "react": "^16.8.0 || ^17 || ^18",
     "react-dom": "^16.8.0 || ^17 || ^18"

package/src/live-hooks/index.ts

@@ -1,4 +1,5 @@
 export * from "./useLivePresence";
+export * from "./useLiveFollowMode";
 export * from "./useLiveState";
 export * from "./useMediaSynchronizer";
 export * from "./useLiveEvent";

package/src/live-hooks/useLiveEvent.ts

@@ -7,6 +7,7 @@ import {
     LiveEventEvents,
     UserMeetingRole,
     LiveEvent,
+    LiveDataObjectInitializeState,
 } from "@microsoft/live-share";
 import React from "react";
 import {
@@ -116,7 +117,9 @@ export function useLiveEvent<TEvent = any>(
             setLatestReceived(received);
         };
         liveEvent.on(LiveEventEvents.received, onEventReceived);
-        if (!liveEvent.isInitialized) {
+        if (
+            liveEvent.initializeState === LiveDataObjectInitializeState.needed
+        ) {
             // Start live event
             liveEvent.initialize(allowedRoles);
         }

package/src/live-hooks/useLiveFollowMode.ts

@@ -0,0 +1,315 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Live Share SDK License.
+ */
+
+import {
+    LivePresenceUser,
+    UserMeetingRole,
+    LiveDataObjectInitializeState,
+    LiveFollowMode,
+    IFollowModePresenceUserData,
+    IFollowModeState,
+} from "@microsoft/live-share";
+import React from "react";
+import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
+import { IUseLiveFollowModeResults } from "../types";
+
+/**
+ * React hook for using a Live Share `LiveFollowMode`.
+ *
+ * @remarks
+ * Use this hook if you want to add the ability to follow specific users or let a user present to everyone in the session.
+ * Each user has their own `stateValue`, which is the value other users will reference when that user is presenting or being followed.
+ * The `state` response includes the user's `value` that the local user is "following", whether it be their own or someone else's.
+ *
+ * @template TData Optional typing for the custom user presence data object. Default is `object` type.
+ *
+ * @param uniqueKey The unique key for `LiveFollowMode`. If one does not yet exist, a new one will be created.
+ * @param initialData The initial value for the local user's `stateValue`.
+ * @param allowedRoles Optional. The user roles that are allowed to present to use `startPresenting()` or `stopPresenting()`.
+ * @returns `IUseLiveFollowModeResults` results, which contains React stateful objects and callbacks.
+ */
+export function useLiveFollowMode<TData = any>(
+    uniqueKey: string,
+    initialData: TData | (() => TData),
+    allowedRoles?: UserMeetingRole[]
+): IUseLiveFollowModeResults<TData> {
+    /**
+     * Stateful follow state.
+     */
+    const [state, setState] = React.useState<IFollowModeState<TData>>();
+    /**
+     * Stateful all user presence list and its non-user-facing setter method.
+     */
+    const [allUsers, setAllUsers] = React.useState<
+        LivePresenceUser<IFollowModePresenceUserData<TData>>[]
+    >([]);
+    /**
+     * User facing: dynamically load the DDS for the given unique key.
+     */
+    const { dds: liveFollowMode } = useDynamicDDS<LiveFollowMode<TData>>(
+        uniqueKey,
+        LiveFollowMode<TData>
+    );
+
+    /**
+     * User facing: list of non-local user's presence objects.
+     */
+    const otherUsers = allUsers.filter((user) => !user.isLocalUser);
+
+    /**
+     * User facing: local user's presence object.
+     */
+    const localUser = allUsers.find((user) => user.isLocalUser);
+
+    const { container } = useFluidObjectsContext();
+
+    /**
+     * User facing: callback to update the local user's custom data for their follow state.
+     */
+    const update = React.useCallback(
+        async (stateValue: TData) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "liveFollowMode",
+                    "updateState"
+                );
+            }
+            if (liveFollowMode === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveFollowMode",
+                    "updateState"
+                );
+            }
+            if (!liveFollowMode.isInitialized) {
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveFollowMode",
+                    "updateState"
+                );
+            }
+            return await liveFollowMode.update(stateValue);
+        },
+        [container, liveFollowMode]
+    );
+
+    /**
+     * User facing: callback to start presenting.
+     */
+    const startPresenting = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "liveFollowMode",
+                "updateState"
+            );
+        }
+        if (liveFollowMode === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "liveFollowMode",
+                "updateState"
+            );
+        }
+        if (!liveFollowMode.isInitialized) {
+            throw new ActionLiveDataObjectInitializedError(
+                "liveFollowMode",
+                "updateState"
+            );
+        }
+        return await liveFollowMode.startPresenting();
+    }, [container, liveFollowMode]);
+
+    /**
+     * User facing: callback to stop presenting.
+     */
+    const stopPresenting = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "liveFollowMode",
+                "stopPresenting"
+            );
+        }
+        if (liveFollowMode === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "liveFollowMode",
+                "stopPresenting"
+            );
+        }
+        if (!liveFollowMode.isInitialized) {
+            throw new ActionLiveDataObjectInitializedError(
+                "liveFollowMode",
+                "stopPresenting"
+            );
+        }
+        return await liveFollowMode.stopPresenting();
+    }, [container, liveFollowMode]);
+
+    /**
+     * User facing: callback to suspend sync.
+     */
+    const beginSuspension = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "liveFollowMode",
+                "syncToPresenter"
+            );
+        }
+        if (liveFollowMode === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "liveFollowMode",
+                "syncToPresenter"
+            );
+        }
+        if (!liveFollowMode.isInitialized) {
+            throw new ActionLiveDataObjectInitializedError(
+                "liveFollowMode",
+                "syncToPresenter"
+            );
+        }
+        return await liveFollowMode.beginSuspension();
+    }, [container, liveFollowMode]);
+
+    /**
+     * User facing: callback to end current suspension.
+     */
+    const endSuspension = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "liveFollowMode",
+                "syncToPresenter"
+            );
+        }
+        if (liveFollowMode === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "liveFollowMode",
+                "syncToPresenter"
+            );
+        }
+        if (!liveFollowMode.isInitialized) {
+            throw new ActionLiveDataObjectInitializedError(
+                "liveFollowMode",
+                "syncToPresenter"
+            );
+        }
+        return await liveFollowMode.endSuspension();
+    }, [container, liveFollowMode]);
+
+    /**
+     * User facing: callback to follow a specific user.
+     */
+    const followUser = React.useCallback(
+        async (userId: string) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "liveFollowMode",
+                    "followUser"
+                );
+            }
+            if (liveFollowMode === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveFollowMode",
+                    "followUser"
+                );
+            }
+            if (!liveFollowMode.isInitialized) {
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveFollowMode",
+                    "followUser"
+                );
+            }
+            return await liveFollowMode.followUser(userId);
+        },
+        [container, liveFollowMode]
+    );
+
+    /**
+     * User facing: callback to stop following a user.
+     */
+    const stopFollowing = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "liveFollowMode",
+                "stopFollowing"
+            );
+        }
+        if (liveFollowMode === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "liveFollowMode",
+                "stopFollowing"
+            );
+        }
+        if (!liveFollowMode.isInitialized) {
+            throw new ActionLiveDataObjectInitializedError(
+                "liveFollowMode",
+                "stopFollowing"
+            );
+        }
+        return await liveFollowMode.stopFollowing();
+    }, [container, liveFollowMode]);
+
+    /**
+     * Setup change listeners and start `LiveFollowMode` if needed
+     */
+    React.useEffect(() => {
+        if (liveFollowMode === undefined) return;
+
+        const onPresenceChanged = () => {
+            const updatedLocalUsers: LivePresenceUser<
+                IFollowModePresenceUserData<TData>
+            >[] = [];
+            liveFollowMode?.getUsers().forEach((user) => {
+                updatedLocalUsers.push(user);
+            });
+            setAllUsers(updatedLocalUsers);
+        };
+        liveFollowMode.on("presenceChanged", onPresenceChanged);
+        const onStateChanged = () => {
+            setState(liveFollowMode?.state);
+        };
+        liveFollowMode.on("stateChanged", onStateChanged);
+
+        if (
+            liveFollowMode.initializeState ===
+            LiveDataObjectInitializeState.needed
+        ) {
+            liveFollowMode.initialize(
+                isInitialDataCallback<TData>(initialData)
+                    ? initialData()
+                    : initialData,
+                allowedRoles
+            );
+        } else {
+            onPresenceChanged();
+            onStateChanged();
+        }
+
+        return () => {
+            liveFollowMode?.off("presenceChanged", onPresenceChanged);
+            liveFollowMode?.off("stateChanged", onStateChanged);
+        };
+    }, [liveFollowMode]);
+
+    return {
+        state,
+        localUser,
+        otherUsers,
+        allUsers,
+        liveFollowMode,
+        update,
+        startPresenting,
+        stopPresenting,
+        beginSuspension,
+        endSuspension,
+        followUser,
+        stopFollowing,
+    };
+}
+
+function isInitialDataCallback<TData>(value: any): value is () => TData {
+    return typeof value === "function";
+}

package/src/live-hooks/useLivePresence.ts

@@ -8,6 +8,7 @@ import {
     PresenceState,
     LivePresence,
     UserMeetingRole,
+    LiveDataObjectInitializeState,
 } from "@microsoft/live-share";
 import React from "react";
 import { IUseLivePresenceResults, OnUpdateLivePresenceAction } from "../types";
@@ -28,8 +29,7 @@ import {
  * user data. This is useful for rendering a list of users, profile pictures, cursor positions, and more.
  *
  * @template TData Optional typing for the custom user presence data object. Default is `object` type.
- * @param uniqueKey The unique key for `LivePresence`. If one does not yet exist, a new one
- * @param userId Optional. The unique ID for a user. If none is provided, a random UUID will be generated.
+ * @param uniqueKey The unique key for `LivePresence`. If one does not yet exist, a new one will be created.
  * @param initialData Optional. Initial presence data object for the user. Can be value or a function to get the value.
  * @param initialPresenceState Optional. Initial status of the user's presence. Default is online.
  * @param allowedRoles Optional. the user roles that are allowed to mutate the synchronized state
@@ -112,7 +112,10 @@ export function useLivePresence<TData extends object = object>(
         };
         livePresence.on("presenceChanged", onPresenceChanged);
 
-        if (!livePresence.isInitialized) {
+        if (
+            livePresence.initializeState ===
+            LiveDataObjectInitializeState.needed
+        ) {
             livePresence.initialize(
                 isInitialDataCallback<TData>(initialData)
                     ? initialData()

package/src/live-hooks/useLiveState.ts

@@ -3,7 +3,11 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import { LiveState, UserMeetingRole } from "@microsoft/live-share";
+import {
+    LiveDataObjectInitializeState,
+    LiveState,
+    UserMeetingRole,
+} from "@microsoft/live-share";
 import React from "react";
 import { SetLiveStateAction } from "../types";
 import { useDynamicDDS } from "../shared-hooks";
@@ -87,7 +91,9 @@ export function useLiveState<TState = any>(
             setCurrentState(state);
         };
         liveState.on("stateChanged", onStateChanged);
-        if (!liveState.isInitialized) {
+        if (
+            liveState.initializeState === LiveDataObjectInitializeState.needed
+        ) {
             liveState.initialize(initialState, allowedRoles);
         }
         if (JSON.stringify(liveState.state) !== JSON.stringify(initialState)) {

package/src/live-hooks/useLiveTimer.ts

@@ -8,6 +8,7 @@ import {
     LiveTimerEvents,
     UserMeetingRole,
     LiveTimer,
+    LiveDataObjectInitializeState,
 } from "@microsoft/live-share";
 import React from "react";
 import {
@@ -154,7 +155,9 @@ export function useLiveTimer(
         liveTimer.on(LiveTimerEvents.played, onDidPlay);
         liveTimer.on(LiveTimerEvents.paused, onDidPause);
         liveTimer.on(LiveTimerEvents.onTick, onDidTick);
-        if (!liveTimer.isInitialized) {
+        if (
+            liveTimer.initializeState === LiveDataObjectInitializeState.needed
+        ) {
             // Start live event
             liveTimer.initialize(allowedRoles);
         }

package/src/live-hooks/useMediaSynchronizer.ts

@@ -3,7 +3,10 @@
  * Licensed under the Microsoft Live Share SDK License.
  */
 
-import { UserMeetingRole } from "@microsoft/live-share";
+import {
+    LiveDataObjectInitializeState,
+    UserMeetingRole,
+} from "@microsoft/live-share";
 import React from "react";
 import {
     CoordinationWaitPoint,
@@ -211,7 +214,10 @@ export function useMediaSynchronizer(
             synchronizer.viewOnly = viewOnly;
         }
 
-        if (!mediaSession.isInitialized) {
+        if (
+            mediaSession.initializeState ===
+            LiveDataObjectInitializeState.needed
+        ) {
             // Start synchronizing the media session
             mediaSession.initialize(allowedRoles ?? []);
         } else if (initialTrack) {