Add reactive localDevice and isActivated to push hooks

usePushActivation now returns a reactive localDevice (LocalDevice | null)
that initialises from localStorage and updates on activate/deactivate.
usePush now exposes isActivated, derived from a shared store, enabling
components to guard subscription calls without extra wiring. Updated
docs and tests accordingly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: splindsay-92

docs/react-push.md

@@ -56,17 +56,20 @@ The `usePushActivation` hook provides functions to activate and deactivate the c
 import { usePushActivation } from 'ably/react';
 
 const PushActivationComponent = () => {
-  const { activate, deactivate } = usePushActivation();
+  const { activate, deactivate, localDevice } = usePushActivation();
 
   return (
     <div>
+      <p>Status: {localDevice ? `Activated (${localDevice.id})` : 'Not activated'}</p>
       <button onClick={() => activate()}>Enable push notifications</button>
       <button onClick={() => deactivate()}>Disable push notifications</button>
     </div>
   );
 };
 ```
 
+The `localDevice` property is reactive — it updates when `activate()` or `deactivate()` is called. It is also initialised from `localStorage` on mount, so if the device was activated in a prior session, `localDevice` will be populated immediately.
+
 #### Activation lifecycle
 
 Activation registers the device with Ably's push service (on web, this requests browser notification permission and registers a service worker). The device identity is persisted to `localStorage`, so:
@@ -79,19 +82,17 @@ A typical pattern is to call `activate()` once in response to a user action (e.g
 
 ```jsx
 const NotificationBanner = () => {
-  const { activate } = usePushActivation();
-  const [enabled, setEnabled] = useState(false);
+  const { activate, localDevice } = usePushActivation();
 
   const handleEnable = async () => {
     try {
       await activate();
-      setEnabled(true);
     } catch (err) {
       console.error('Push activation failed:', err);
     }
   };
 
-  if (enabled) return null;
+  if (localDevice) return null;
 
   return (
     <div className="banner">
@@ -120,19 +121,28 @@ The `usePush` hook provides functions to manage push notification subscriptions
 import { usePush } from 'ably/react';
 
 const PushSubscriptionComponent = () => {
-  const { subscribeDevice, unsubscribeDevice } = usePush('your-channel-name');
+  const { subscribeDevice, unsubscribeDevice, isActivated } = usePush('your-channel-name');
 
   return (
     <div>
-      <button onClick={() => subscribeDevice()}>Subscribe to channel</button>
-      <button onClick={() => unsubscribeDevice()}>Unsubscribe from channel</button>
+      <button onClick={() => subscribeDevice()} disabled={!isActivated}>
+        Subscribe to channel
+      </button>
+      <button onClick={() => unsubscribeDevice()} disabled={!isActivated}>
+        Unsubscribe from channel
+      </button>
+      {!isActivated && <p>Push must be activated before subscribing.</p>}
     </div>
   );
 };
 ```
 
+#### Activation awareness
+
+`usePush` is aware of whether push has been activated via `usePushActivation`. The `isActivated` property is reactive — when `usePushActivation` calls `activate()` or `deactivate()`, all `usePush` instances update automatically, even if they are in different components. This works via a shared store without requiring any additional providers.
+
 > [!IMPORTANT]
-> The device must be activated (via `usePushActivation`) before calling `subscribeDevice()` or `unsubscribeDevice()`. See [Error Handling](#error-handling) for details on what happens if activation hasn't been completed.
+> The device must be activated (via `usePushActivation`) before calling `subscribeDevice()` or `unsubscribeDevice()`. Use `isActivated` to guard your UI or check before calling. See [Error Handling](#error-handling) for details on what happens if activation hasn't been completed.
 
 #### Subscribe by device or by client
 
@@ -202,7 +212,18 @@ If you call `subscribeDevice()` or `unsubscribeDevice()` before the device has b
 Error: Cannot subscribe from client without deviceIdentityToken (code: 50000)
 ```
 
-Ensure `activate()` has completed successfully before subscribing:
+The recommended way to prevent this is to use the `isActivated` flag from `usePush` to guard your UI:
+
+```jsx
+const { subscribeDevice, isActivated } = usePush('alerts');
+
+// Disable the button until push is activated
+<button onClick={() => subscribeDevice()} disabled={!isActivated}>
+  Subscribe
+</button>
+```
+
+Alternatively, you can sequence activation and subscription imperatively:
 
 ```jsx
 const { activate } = usePushActivation();
@@ -266,18 +287,16 @@ const App = () => (
 );
 
 const PushActivation = () => {
-  const { activate, deactivate } = usePushActivation();
-  const [active, setActive] = useState(false);
+  const { activate, deactivate, localDevice } = usePushActivation();
   const [error, setError] = useState(null);
 
   const handleToggle = async () => {
     try {
-      if (active) {
+      if (localDevice) {
         await deactivate();
       } else {
         await activate();
       }
-      setActive(!active);
       setError(null);
     } catch (err) {
       setError(err.message);
@@ -287,15 +306,19 @@ const PushActivation = () => {
   return (
     <div>
       <button onClick={handleToggle}>
-        {active ? 'Disable' : 'Enable'} push notifications
+        {localDevice ? 'Disable' : 'Enable'} push notifications
       </button>
+      {localDevice && <p>Device ID: {localDevice.id}</p>}
       {error && <p className="error">{error}</p>}
     </div>
   );
 };
 
 const AlertSubscription = () => {
-  const { subscribeDevice, unsubscribeDevice, connectionError, channelError } = usePush('alerts');
+  const {
+    subscribeDevice, unsubscribeDevice,
+    isActivated, connectionError, channelError,
+  } = usePush('alerts');
   const [subscribed, setSubscribed] = useState(false);
 
   if (connectionError) return <p>Connection error: {connectionError.message}</p>;
@@ -315,9 +338,12 @@ const AlertSubscription = () => {
   };
 
   return (
-    <button onClick={handleToggle}>
-      {subscribed ? 'Unsubscribe from' : 'Subscribe to'} alerts
-    </button>
+    <div>
+      <button onClick={handleToggle} disabled={!isActivated}>
+        {subscribed ? 'Unsubscribe from' : 'Subscribe to'} alerts
+      </button>
+      {!isActivated && <p>Activate push notifications first.</p>}
+    </div>
   );
 };
 ```
@@ -334,13 +360,15 @@ function usePushActivation(ablyId?: string): PushActivationResult;
 interface PushActivationResult {
   activate: () => Promise<void>;
   deactivate: () => Promise<void>;
+  localDevice: Ably.LocalDevice | null;
 }
 ```
 
-| Property     | Type                  | Description                                                                 |
-| ------------ | --------------------- | --------------------------------------------------------------------------- |
-| `activate`   | `() => Promise<void>` | Activates the device for push notifications. Persists to `localStorage`.    |
-| `deactivate` | `() => Promise<void>` | Deactivates the device and removes the registration from Ably's servers.    |
+| Property      | Type                     | Description                                                                                              |
+| ------------- | ------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `activate`    | `() => Promise<void>`    | Activates the device for push notifications. Persists to `localStorage`.                                 |
+| `deactivate`  | `() => Promise<void>`    | Deactivates the device and removes the registration from Ably's servers.                                 |
+| `localDevice` | `Ably.LocalDevice\|null` | The current device if activated, `null` otherwise. Reactive — updates on activate/deactivate and is initialised from persisted state. |
 
 ### `usePush`
 
@@ -354,6 +382,7 @@ interface PushResult {
   subscribeClient: () => Promise<void>;
   unsubscribeClient: () => Promise<void>;
   listSubscriptions: (params?: Record<string, string>) => Promise<PaginatedResult<PushChannelSubscription>>;
+  isActivated: boolean;
   connectionError: Ably.ErrorInfo | null;
   channelError: Ably.ErrorInfo | null;
 }
@@ -367,5 +396,6 @@ interface PushResult {
 | `subscribeClient`    | `() => Promise<void>`                              | Subscribes all devices for the current `clientId` to push on this channel.     |
 | `unsubscribeClient`  | `() => Promise<void>`                              | Unsubscribes all devices for the current `clientId` from push on this channel. |
 | `listSubscriptions`  | `(params?) => Promise<PaginatedResult<...>>`       | Lists active push subscriptions for this channel.                              |
+| `isActivated`        | `boolean`                                          | Whether push is currently activated. Reactive — updates across components.     |
 | `connectionError`    | `Ably.ErrorInfo \| null`                           | Current connection error, if any.                                              |
 | `channelError`       | `Ably.ErrorInfo \| null`                           | Current channel error, if any.                                                 |

src/platform/react-hooks/src/PushActivationState.ts

@@ -0,0 +1,30 @@
+import type * as Ably from 'ably';
+
+type Listener = () => void;
+
+const listeners = new Map<string, Set<Listener>>();
+const deviceState = new Map<string, Ably.LocalDevice | null>();
+
+export function getActivatedDevice(ablyId: string): Ably.LocalDevice | null {
+  return deviceState.get(ablyId) ?? null;
+}
+
+export function setActivatedDevice(ablyId: string, device: Ably.LocalDevice | null): void {
+  deviceState.set(ablyId, device);
+  const ablyListeners = listeners.get(ablyId);
+  if (ablyListeners) {
+    for (const listener of ablyListeners) {
+      listener();
+    }
+  }
+}
+
+export function subscribe(ablyId: string, listener: Listener): () => void {
+  if (!listeners.has(ablyId)) {
+    listeners.set(ablyId, new Set());
+  }
+  listeners.get(ablyId)!.add(listener);
+  return () => {
+    listeners.get(ablyId)?.delete(listener);
+  };
+}

src/platform/react-hooks/src/hooks/usePush.test.tsx

@@ -1,11 +1,12 @@
 import React from 'react';
 import type * as Ably from 'ably';
-import { it, beforeEach, describe, expect, vi } from 'vitest';
+import { it, beforeEach, afterEach, describe, expect, vi } from 'vitest';
 import { usePush } from './usePush.js';
 import { renderHook, act } from '@testing-library/react';
 import { FakeAblySdk, FakeAblyChannels } from '../fakes/ably.js';
 import { AblyProvider } from '../AblyProvider.js';
 import { ChannelProvider } from '../ChannelProvider.js';
+import { setActivatedDevice } from '../PushActivationState.js';
 
 const testChannelName = 'testChannel';
 
@@ -28,8 +29,12 @@ describe('usePush', () => {
     ablyClient = new FakeAblySdk().connectTo(channels);
   });
 
+  afterEach(() => {
+    setActivatedDevice('default', null);
+  });
+
   /** @nospec */
-  it('returns the channel and push methods', () => {
+  it('returns the channel, push methods, and isActivated', () => {
     const { result } = renderInCtxProvider(ablyClient);
 
     expect(result.current.channel).toBeDefined();
@@ -38,6 +43,52 @@ describe('usePush', () => {
     expect(result.current.subscribeClient).toBeTypeOf('function');
     expect(result.current.unsubscribeClient).toBeTypeOf('function');
     expect(result.current.listSubscriptions).toBeTypeOf('function');
+    expect(result.current).toHaveProperty('isActivated');
+  });
+
+  /** @nospec */
+  it('isActivated is false when no device is activated', () => {
+    const { result } = renderInCtxProvider(ablyClient);
+
+    expect(result.current.isActivated).toBe(false);
+  });
+
+  /** @nospec */
+  it('isActivated becomes true when device is activated via store', () => {
+    const { result } = renderInCtxProvider(ablyClient);
+
+    expect(result.current.isActivated).toBe(false);
+
+    act(() => {
+      setActivatedDevice('default', {
+        id: 'device-123',
+        deviceSecret: 'secret-456',
+        deviceIdentityToken: 'token-789',
+        listSubscriptions: vi.fn() as any,
+      });
+    });
+
+    expect(result.current.isActivated).toBe(true);
+  });
+
+  /** @nospec */
+  it('isActivated reverts to false when device is deactivated via store', () => {
+    setActivatedDevice('default', {
+      id: 'device-123',
+      deviceSecret: 'secret-456',
+      deviceIdentityToken: 'token-789',
+      listSubscriptions: vi.fn() as any,
+    });
+
+    const { result } = renderInCtxProvider(ablyClient);
+
+    expect(result.current.isActivated).toBe(true);
+
+    act(() => {
+      setActivatedDevice('default', null);
+    });
+
+    expect(result.current.isActivated).toBe(false);
   });
 
   /** @nospec */

src/platform/react-hooks/src/hooks/usePush.ts

@@ -1,8 +1,9 @@
 import type * as Ably from 'ably';
-import { useCallback } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { ChannelParameters } from '../AblyReactHooks.js';
 import { useChannelInstance } from './useChannelInstance.js';
 import { useStateErrors } from './useStateErrors.js';
+import { getActivatedDevice, subscribe } from '../PushActivationState.js';
 
 export interface PushResult {
   channel: Ably.RealtimeChannel;
@@ -11,6 +12,7 @@ export interface PushResult {
   subscribeClient: () => Promise<void>;
   unsubscribeClient: () => Promise<void>;
   listSubscriptions: (params?: Record<string, string>) => Promise<Ably.PaginatedResult<Ably.PushChannelSubscription>>;
+  isActivated: boolean;
   connectionError: Ably.ErrorInfo | null;
   channelError: Ably.ErrorInfo | null;
 }
@@ -21,13 +23,26 @@ export function usePush(channelNameOrNameAndOptions: ChannelParameters): PushRes
       ? channelNameOrNameAndOptions
       : { channelName: channelNameOrNameAndOptions };
 
-  const { channel } = useChannelInstance(params.ablyId, params.channelName);
+  const ablyId = params.ablyId ?? 'default';
+
+  const { channel } = useChannelInstance(ablyId, params.channelName);
   const { connectionError, channelError } = useStateErrors(params);
 
   // Access channel.push eagerly to fail fast if the Push plugin is not loaded.
   // The getter on RealtimeChannel throws a descriptive error when the plugin is missing.
   const push = channel.push;
 
+  // Subscribe to push activation state from the shared store
+  const [localDevice, setLocalDevice] = useState<Ably.LocalDevice | null>(() => getActivatedDevice(ablyId));
+
+  useEffect(() => {
+    return subscribe(ablyId, () => {
+      setLocalDevice(getActivatedDevice(ablyId));
+    });
+  }, [ablyId]);
+
+  const isActivated = localDevice != null;
+
   const subscribeDevice = useCallback(() => push.subscribeDevice(), [push]);
   const unsubscribeDevice = useCallback(() => push.unsubscribeDevice(), [push]);
   const subscribeClient = useCallback(() => push.subscribeClient(), [push]);
@@ -44,6 +59,7 @@ export function usePush(channelNameOrNameAndOptions: ChannelParameters): PushRes
     subscribeClient,
     unsubscribeClient,
     listSubscriptions,
+    isActivated,
     connectionError,
     channelError,
   };