@dxos/react-client 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/docs/README.md

@@ -168,41 +168,41 @@ dxos/react-client --> dxos/react-async
 
 ## Dependencies
 
-| Module | Direct |
-|---|---|
-| [`@dxos/async`](../../../common/async/docs/README.md) | ✓ |
-| [`@dxos/broadcast`](../../../core/mesh/broadcast/docs/README.md) |  |
-| [`@dxos/client`](../../client/docs/README.md) | ✓ |
-| [`@dxos/client-services`](../../client-services/docs/README.md) | ✓ |
-| [`@dxos/codec-protobuf`](../../../common/codec-protobuf/docs/README.md) | ✓ |
-| [`@dxos/config`](../../config/docs/README.md) | ✓ |
-| [`@dxos/context`](../../../common/context/docs/README.md) |  |
-| [`@dxos/credentials`](../../../core/halo/credentials/docs/README.md) |  |
-| [`@dxos/crypto`](../../../common/crypto/docs/README.md) |  |
-| [`@dxos/debug`](../../../common/debug/docs/README.md) | ✓ |
-| [`@dxos/echo-db`](../../../core/echo/echo-db/docs/README.md) |  |
-| [`@dxos/errors`](../../errors/docs/README.md) |  |
-| [`@dxos/feed-store`](../../../common/feed-store/docs/README.md) |  |
-| [`@dxos/hypercore`](../../../common/hypercore/docs/README.md) |  |
-| [`@dxos/keyring`](../../../core/halo/keyring/docs/README.md) |  |
-| [`@dxos/keys`](../../../common/keys/docs/README.md) | ✓ |
-| [`@dxos/log`](../../../common/log/docs/README.md) | ✓ |
-| [`@dxos/mesh-protocol`](../../../core/mesh/mesh-protocol/docs/README.md) |  |
-| [`@dxos/messaging`](../../../core/mesh/messaging/docs/README.md) | ✓ |
-| [`@dxos/model-factory`](../../../core/echo/model-factory/docs/README.md) |  |
-| [`@dxos/network-generator`](../../../core/mesh/network-generator/docs/README.md) |  |
-| [`@dxos/network-manager`](../../../core/mesh/network-manager/docs/README.md) |  |
-| [`@dxos/document-model`](../../../core/echo/document-model/docs/README.md) |  |
-| [`@dxos/protocol-plugin-presence`](../../../core/mesh/protocol-plugin-presence/docs/README.md) |  |
-| [`@dxos/protocol-plugin-replicator`](../../../core/mesh/protocol-plugin-replicator/docs/README.md) |  |
-| [`@dxos/protocol-plugin-rpc`](../../../core/mesh/protocol-plugin-rpc/docs/README.md) |  |
-| [`@dxos/protocols`](../../../core/protocols/docs/README.md) | ✓ |
-| [`@dxos/random-access-storage`](../../../common/random-access-storage/docs/README.md) |  |
-| [`@dxos/react-async`](../../../common/react-async/docs/README.md) | ✓ |
-| [`@dxos/rpc`](../../../core/mesh/rpc/docs/README.md) | ✓ |
-| [`@dxos/rpc-tunnel`](../../../core/mesh/rpc-tunnel/docs/README.md) | ✓ |
-| [`@dxos/teleport`](../../../core/mesh/teleport/docs/README.md) |  |
-| [`@dxos/teleport-plugin-replicator`](../../../core/mesh/teleport-plugin-replicator/docs/README.md) |  |
-| [`@dxos/text-model`](../../../core/echo/text-model/docs/README.md) |  |
-| [`@dxos/timeframe`](../../../common/timeframe/docs/README.md) |  |
-| [`@dxos/util`](../../../common/util/docs/README.md) | ✓ |
+| Module                                                                                             | Direct  |
+| -------------------------------------------------------------------------------------------------- | ------- |
+| [`@dxos/async`](../../../common/async/docs/README.md)                                              | ✓ |
+| [`@dxos/broadcast`](../../../core/mesh/broadcast/docs/README.md)                                   |         |
+| [`@dxos/client`](../../client/docs/README.md)                                                      | ✓ |
+| [`@dxos/client-services`](../../client-services/docs/README.md)                                    | ✓ |
+| [`@dxos/codec-protobuf`](../../../common/codec-protobuf/docs/README.md)                            | ✓ |
+| [`@dxos/config`](../../config/docs/README.md)                                                      | ✓ |
+| [`@dxos/context`](../../../common/context/docs/README.md)                                          |         |
+| [`@dxos/credentials`](../../../core/halo/credentials/docs/README.md)                               |         |
+| [`@dxos/crypto`](../../../common/crypto/docs/README.md)                                            |         |
+| [`@dxos/debug`](../../../common/debug/docs/README.md)                                              | ✓ |
+| [`@dxos/echo-db`](../../../core/echo/echo-db/docs/README.md)                                       |         |
+| [`@dxos/errors`](../../errors/docs/README.md)                                                      |         |
+| [`@dxos/feed-store`](../../../common/feed-store/docs/README.md)                                    |         |
+| [`@dxos/hypercore`](../../../common/hypercore/docs/README.md)                                      |         |
+| [`@dxos/keyring`](../../../core/halo/keyring/docs/README.md)                                       |         |
+| [`@dxos/keys`](../../../common/keys/docs/README.md)                                                | ✓ |
+| [`@dxos/log`](../../../common/log/docs/README.md)                                                  | ✓ |
+| [`@dxos/mesh-protocol`](../../../core/mesh/mesh-protocol/docs/README.md)                           |         |
+| [`@dxos/messaging`](../../../core/mesh/messaging/docs/README.md)                                   | ✓ |
+| [`@dxos/model-factory`](../../../core/echo/model-factory/docs/README.md)                           |         |
+| [`@dxos/network-generator`](../../../core/mesh/network-generator/docs/README.md)                   |         |
+| [`@dxos/network-manager`](../../../core/mesh/network-manager/docs/README.md)                       |         |
+| [`@dxos/document-model`](../../../core/echo/document-model/docs/README.md)                         |         |
+| [`@dxos/protocol-plugin-presence`](../../../core/mesh/protocol-plugin-presence/docs/README.md)     |         |
+| [`@dxos/protocol-plugin-replicator`](../../../core/mesh/protocol-plugin-replicator/docs/README.md) |         |
+| [`@dxos/protocol-plugin-rpc`](../../../core/mesh/protocol-plugin-rpc/docs/README.md)               |         |
+| [`@dxos/protocols`](../../../core/protocols/docs/README.md)                                        | ✓ |
+| [`@dxos/random-access-storage`](../../../common/random-access-storage/docs/README.md)              |         |
+| [`@dxos/react-async`](../../../common/react-async/docs/README.md)                                  | ✓ |
+| [`@dxos/rpc`](../../../core/mesh/rpc/docs/README.md)                                               | ✓ |
+| [`@dxos/rpc-tunnel`](../../../core/mesh/rpc-tunnel/docs/README.md)                                 | ✓ |
+| [`@dxos/teleport`](../../../core/mesh/teleport/docs/README.md)                                     |         |
+| [`@dxos/teleport-plugin-replicator`](../../../core/mesh/teleport-plugin-replicator/docs/README.md) |         |
+| [`@dxos/text-model`](../../../core/echo/text-model/docs/README.md)                                 |         |
+| [`@dxos/timeframe`](../../../common/timeframe/docs/README.md)                                      |         |
+| [`@dxos/util`](../../../common/util/docs/README.md)                                                | ✓ |

package/moon.yml

@@ -1,11 +1,12 @@
-type: library
+layer: library
 language: typescript
 tags:
-  - e2e
   - ts-build
   - ts-test
+  - ts-test-storybook
   - typedoc
   - pack
+  - storybook
 tasks:
   compile:
     args:

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@dxos/react-client",
-  "version": "0.8.4-main.fd6878d",
+  "version": "0.8.4-staging.60fe92afc8",
   "description": "React client API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     "./devtools": {
@@ -59,70 +63,44 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "devtools": [
-        "dist/types/src/devtools/index.d.ts"
-      ],
-      "echo": [
-        "dist/types/src/echo/index.d.ts"
-      ],
-      "halo": [
-        "dist/types/src/halo/index.d.ts"
-      ],
-      "invitations": [
-        "dist/types/src/invitations/index.d.ts"
-      ],
-      "mesh": [
-        "dist/types/src/mesh/index.d.ts"
-      ],
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ],
-      "worker": [
-        "dist/types/src/worker.d.ts"
-      ]
-    }
-  },
   "dependencies": {
-    "react-error-boundary": "^4.0.13",
-    "@dxos/client": "0.8.4-main.fd6878d",
-    "@dxos/codec-protobuf": "0.8.4-main.fd6878d",
-    "@dxos/context": "0.8.4-main.fd6878d",
-    "@dxos/async": "0.8.4-main.fd6878d",
-    "@dxos/debug": "0.8.4-main.fd6878d",
-    "@dxos/echo": "0.8.4-main.fd6878d",
-    "@dxos/config": "0.8.4-main.fd6878d",
-    "@dxos/echo-schema": "0.8.4-main.fd6878d",
-    "@dxos/echo-signals": "0.8.4-main.fd6878d",
-    "@dxos/node-std": "0.8.4-main.fd6878d",
-    "@dxos/protocols": "0.8.4-main.fd6878d",
-    "@dxos/react-hooks": "0.8.4-main.fd6878d",
-    "@dxos/invariant": "0.8.4-main.fd6878d",
-    "@dxos/util": "0.8.4-main.fd6878d",
-    "@dxos/log": "0.8.4-main.fd6878d"
+    "@dxos/client": "0.8.4-staging.60fe92afc8",
+    "@dxos/async": "0.8.4-staging.60fe92afc8",
+    "@dxos/config": "0.8.4-staging.60fe92afc8",
+    "@dxos/context": "0.8.4-staging.60fe92afc8",
+    "@dxos/debug": "0.8.4-staging.60fe92afc8",
+    "@dxos/echo-protocol": "0.8.4-staging.60fe92afc8",
+    "@dxos/echo": "0.8.4-staging.60fe92afc8",
+    "@dxos/invariant": "0.8.4-staging.60fe92afc8",
+    "@dxos/echo-react": "0.8.4-staging.60fe92afc8",
+    "@dxos/keys": "0.8.4-staging.60fe92afc8",
+    "@dxos/log": "0.8.4-staging.60fe92afc8",
+    "@dxos/node-std": "0.8.4-staging.60fe92afc8",
+    "@dxos/util": "0.8.4-staging.60fe92afc8",
+    "@dxos/react-hooks": "0.8.4-staging.60fe92afc8",
+    "@dxos/codec-protobuf": "0.8.4-staging.60fe92afc8"
   },
   "devDependencies": {
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
     "typedoc": "0.28.1",
-    "@dxos/random": "0.8.4-main.fd6878d",
-    "@dxos/react-ui": "0.8.4-main.fd6878d",
-    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.fd6878d",
-    "@dxos/react-ui-theme": "0.8.4-main.fd6878d",
-    "@dxos/storybook-utils": "0.8.4-main.fd6878d",
-    "@dxos/test-utils": "0.8.4-main.fd6878d"
+    "@dxos/random": "0.8.4-staging.60fe92afc8",
+    "@dxos/react-ui": "0.8.4-staging.60fe92afc8",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-staging.60fe92afc8",
+    "@dxos/test-utils": "0.8.4-staging.60fe92afc8",
+    "@dxos/storybook-utils": "0.8.4-staging.60fe92afc8",
+    "@dxos/ui-theme": "0.8.4-staging.60fe92afc8"
   },
   "peerDependencies": {
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0"
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3"
   },
   "optionalDependencies": {
-    "@dxos/random": "0.8.4-main.fd6878d",
-    "@dxos/react-ui": "0.8.4-main.fd6878d",
-    "@dxos/react-ui-theme": "0.8.4-main.fd6878d"
+    "@dxos/random": "0.8.4-staging.60fe92afc8",
+    "@dxos/react-ui": "0.8.4-staging.60fe92afc8",
+    "@dxos/ui-theme": "0.8.4-staging.60fe92afc8"
   },
   "publishConfig": {
     "access": "public"

package/src/client/ClientProvider.test.tsx

@@ -11,7 +11,6 @@ import { Client, Config, SystemStatus, fromHost } from '@dxos/client';
 import { log } from '@dxos/log';
 
 import { useIdentity } from '../halo';
-
 import { ClientProvider } from './ClientProvider';
 import { useClient } from './useClient';
 

package/src/client/ClientProvider.tsx

@@ -13,13 +13,11 @@ import React, {
 
 import { Client, type ClientOptions, type ClientServicesProvider, SystemStatus } from '@dxos/client';
 import { type Config } from '@dxos/config';
-import { registerSignalsRuntime } from '@dxos/echo-signals/react';
 import { log } from '@dxos/log';
-import { useControlledState } from '@dxos/react-hooks';
+import { useAsyncEffect, useControlledState } from '@dxos/react-hooks';
 import { type MaybePromise, type Provider, getAsyncProviderValue } from '@dxos/util';
 
 import { printBanner } from '../banner';
-
 import { ClientContext, type ClientContextProps } from './context';
 
 /**
@@ -56,12 +54,6 @@ export type ClientProviderProps = Omit<ClientOptions, 'config' | 'services'> &
      */
     fallback?: FunctionComponent<Partial<ClientContextProps>>;
 
-    /**
-     * Enable (by default) registration of Preact signals runtime for reactive ECHO objects.
-     * @see https://www.npmjs.com/package/@preact/signals-react
-     */
-    signalsRuntime?: boolean;
-
     /**
      * Skip the DXOS banner.
      */
@@ -81,24 +73,17 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
   (
     {
       children,
-      config: configProvider,
-      client: clientProvider,
-      services: servicesProvider,
-      status: controlledStatus,
+      config: configProp,
+      client: clientProp,
+      services: servicesProp,
+      status: statusProp,
       fallback: Fallback = () => null,
-      signalsRuntime = true,
       noBanner,
       onInitialized,
       ...options
     },
     forwardedRef,
   ) => {
-    useEffect(() => {
-      // TODO(wittjosiah): Ideally this should be imported asynchronously because it is optional.
-      //   Unfortunately, async import seemed to break signals React instrumentation.
-      signalsRuntime && registerSignalsRuntime();
-    }, []);
-
     // The client is initialized asynchronously.
     // If an error occurs during initialization, it is caught and the state is set.
     // This allows the error to be thrown in the render method.
@@ -109,13 +94,13 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
       throw error;
     }
 
-    const [client, setClient] = useState(clientProvider instanceof Client ? clientProvider : undefined);
+    const [client, setClient] = useState(clientProp instanceof Client ? clientProp : undefined);
 
     // Provide external access.
     useImperativeHandle(forwardedRef, () => client, [client]);
 
     // Client status subscription.
-    const [status, setStatus] = useControlledState(controlledStatus);
+    const [status, setStatus] = useControlledState(statusProp);
     useEffect(() => {
       if (!client) {
         return;
@@ -126,7 +111,7 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
     }, [client]);
 
     // Create and/or initialize client.
-    useEffect(() => {
+    useAsyncEffect(async () => {
       let disposed = false;
       const initialize = async (client: Client) => {
         if (!client.initialized) {
@@ -141,42 +126,38 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
         }
 
         setClient(client);
-
         if (!noBanner) {
           printBanner(client);
         }
       };
 
       let client: Client;
-      const t = setTimeout(async () => {
-        try {
-          if (clientProvider) {
-            // Asynchronously request client.
-            client = await getAsyncProviderValue(clientProvider);
-            await initialize(client);
-          } else {
-            // Asynchronously construct client (config may be undefined).
-            const config = await getAsyncProviderValue(configProvider);
-            log('resolved config', { config });
-            const services = await getAsyncProviderValue(servicesProvider, config);
-            log('created services', { services });
-            client = new Client({ config, services, ...options });
-            log('created client');
-            await initialize(client);
-          }
-        } catch (err) {
-          if (!disposed) {
-            log.catch(err);
-          }
+      try {
+        if (clientProp) {
+          // Asynchronously request client.
+          client = await getAsyncProviderValue(clientProp);
+          await initialize(client);
+        } else {
+          // Asynchronously construct client (config may be undefined).
+          const config = await getAsyncProviderValue(configProp);
+          log('resolved config', { config });
+          const services = await getAsyncProviderValue(servicesProp, config);
+          log('created services', { services });
+          client = new Client({ config, services, ...options });
+          log('created client');
+          await initialize(client);
         }
-      });
+      } catch (err) {
+        if (!disposed) {
+          log.catch(err);
+        }
+      }
 
       return () => {
         log('clean up');
         disposed = true;
-        clearTimeout(t);
         // Only destroy if the client is not provided by the parent.
-        if (!clientProvider) {
+        if (!clientProp) {
           void client
             ?.destroy()
             .then(() => {
@@ -185,7 +166,7 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
             .catch((err) => log.catch(err));
         }
       };
-    }, [configProvider, clientProvider, servicesProvider, noBanner]);
+    }, [configProp, clientProp, servicesProp, noBanner]);
 
     if (!client?.initialized || status !== SystemStatus.ACTIVE) {
       return <Fallback client={client} status={status} />;

package/src/client/useConfig.test.tsx

@@ -9,7 +9,6 @@ import { waitForCondition } from '@dxos/async';
 import { Config, SystemStatus } from '@dxos/client';
 
 import { createClient, createClientContextProvider } from '../testing/util';
-
 import { useConfig } from './useConfig';
 
 // TODO(burdon): Disabled in CI since flaky.

package/src/echo/index.ts

@@ -3,12 +3,13 @@
 //
 
 export * from '@dxos/client/echo';
+export * from '@dxos/echo-react';
 
 export * from './useMembers';
-export * from './useQuery';
-export * from './useQueue';
-export * from './useSchema';
 export * from './useSpaces';
 export * from './useSpaceInvitations';
+export * from './useSpaceProperties';
 export * from './useSubscription';
 export * from './useSyncState';
+export * from './useFeedSyncState';
+export * from './useRegistry';

package/src/echo/useFeedSyncState.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { type SpaceId } from '@dxos/keys';
+
+import { useClient } from '../client';
+
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+
+export type FeedSyncState = {
+  /** Combined blocks to pull + push across namespaces. */
+  pending: number;
+  /** Total blocks stored locally across namespaces. */
+  total: number;
+};
+
+export type FeedSyncStateMap = Record<SpaceId, FeedSyncState>;
+
+/**
+ * Polls queue replication state per space.
+ */
+export const useFeedSyncState = (pollIntervalMs = DEFAULT_POLL_INTERVAL_MS): FeedSyncStateMap => {
+  const client = useClient();
+  const [feedSyncState, setFeedSyncState] = useState<FeedSyncStateMap>({});
+
+  useEffect(() => {
+    const queueService = client.services.services.QueueService;
+    if (!queueService) {
+      return;
+    }
+
+    let cancelled = false;
+
+    const poll = async () => {
+      const spaces = client.spaces.get();
+      const entries = await Promise.all(
+        spaces.map(async (space) => {
+          try {
+            const response = await queueService.getSyncState({ spaceId: space.id });
+            const state = (response.namespaces ?? []).reduce<FeedSyncState>(
+              (acc, entry) => {
+                acc.pending += Number(entry.blocksToPull ?? 0) + Number(entry.blocksToPush ?? 0);
+                acc.total += Number(entry.totalBlocks ?? 0);
+                return acc;
+              },
+              { pending: 0, total: 0 },
+            );
+            return [space.id, state] as const;
+          } catch {
+            return [space.id, { pending: 0, total: 0 }] as const;
+          }
+        }),
+      );
+
+      if (!cancelled) {
+        setFeedSyncState(Object.fromEntries(entries));
+      }
+    };
+
+    void poll();
+    const interval = setInterval(() => void poll(), pollIntervalMs);
+
+    const spacesSubscription = client.spaces.subscribe(() => {
+      void poll();
+    });
+
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+      spacesSubscription.unsubscribe();
+    };
+  }, [client, pollIntervalMs]);
+
+  return feedSyncState;
+};

package/src/echo/useMembers.ts

@@ -3,16 +3,18 @@
 //
 
 import { MulticastObservable } from '@dxos/async';
-import { type PublicKey } from '@dxos/client';
+import { PublicKey, type PublicKeyLike } from '@dxos/client';
 import { HaloSpaceMember, type SpaceMember } from '@dxos/client/echo';
 import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useSpaces } from './useSpaces';
 
-export const useMembers = (spaceKey: PublicKey | undefined): SpaceMember[] => {
+export const useMembers = (spaceKey: PublicKeyLike | undefined): SpaceMember[] => {
   // TODO(dmaretskyi): useSpace hook for spaces that are not ready.
   const spaces = useSpaces({ all: true });
-  const space = spaceKey ? spaces.find((space) => space.key.equals(spaceKey)) : undefined;
+  const space = spaceKey
+    ? spaces.find((space) => (spaceKey instanceof PublicKey ? space.key.equals(spaceKey) : space.id === spaceKey))
+    : undefined;
 
   // EMPTY_OBSERVABLE needs to be a stable reference to avoid re-subscribing on every render.
   const members = useMulticastObservable(space?.members ?? MulticastObservable.empty()) ?? [];

package/src/echo/useRegistry.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Registry } from '@dxos/echo';
+
+import { useClient } from '../client';
+
+/**
+ * Returns the hypergraph registry attached to the current client.
+ */
+export const useRegistry = (): Registry.Registry => {
+  const client = useClient();
+  return client.graph.registry;
+};

package/src/echo/useSpaceInvitations.ts

@@ -6,19 +6,23 @@ import { useMemo } from 'react';
 
 import { MulticastObservable } from '@dxos/async';
 import { type PublicKey } from '@dxos/client';
+import { type SpaceId } from '@dxos/keys';
 import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { type CancellableInvitationObservable, useInvitationStatus } from '../invitations';
-
 import { useSpace } from './useSpaces';
 
-export const useSpaceInvitations = (spaceKey?: PublicKey): CancellableInvitationObservable[] => {
-  const space = useSpace(spaceKey);
+// TODO(wittjosiah): Currently unable to remove `PublicKey` from this api.
+//  When initially joining a space that is all that is returned.
+export const useSpaceInvitations = (spaceId?: SpaceId | PublicKey): CancellableInvitationObservable[] => {
+  const space = useSpace(spaceId);
   return useMulticastObservable(space?.invitations ?? MulticastObservable.empty()) ?? [];
 };
 
-export const useSpaceInvitation = (spaceKey?: PublicKey, invitationId?: string) => {
-  const invitations = useSpaceInvitations(spaceKey);
+// TODO(wittjosiah): Currently unable to remove `PublicKey` from this api.
+//  When initially joining a space that is all that is returned.
+export const useSpaceInvitation = (spaceId?: SpaceId | PublicKey, invitationId?: string) => {
+  const invitations = useSpaceInvitations(spaceId);
   const invitation = useMemo(
     () => invitations.find((invitation) => invitation.get().invitationId === invitationId),
     [invitations],

package/src/echo/useSpaceProperties.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { MulticastObservable } from '@dxos/async';
+import { type SpaceProperties, SpaceState } from '@dxos/client/echo';
+import { type Key, type Obj } from '@dxos/echo';
+import { type ObjectUpdateCallback, useObject } from '@dxos/echo-react';
+import { useMulticastObservable } from '@dxos/react-hooks';
+
+import { useSpace } from './useSpaces';
+
+/**
+ * Subscribe to a space's properties with reactive updates.
+ * Returns undefined if the space is undefined or not ready yet.
+ * Automatically waits for the space to be ready before returning properties.
+ *
+ * @param spaceId - The space ID to get properties from (can be undefined).
+ * @returns A tuple of [snapshot, updateCallback] or [undefined, no-op] if not ready.
+ */
+export const useSpaceProperties = (
+  spaceId: Key.SpaceId | undefined,
+): [Obj.Snapshot<SpaceProperties> | undefined, ObjectUpdateCallback<SpaceProperties>] => {
+  const space = useSpace(spaceId);
+  const spaceState = useMulticastObservable(space?.state ?? MulticastObservable.empty());
+  const properties = spaceState === SpaceState.SPACE_READY ? space?.properties : undefined;
+  return useObject(properties);
+};

package/src/echo/useSpaces.test.tsx

@@ -6,19 +6,18 @@ import { act, renderHook } from '@testing-library/react';
 import { describe, expect, test } from 'vitest';
 
 import { createClient, createClientContextProvider } from '../testing/util';
-
 import { useSpace, useSpaces } from './useSpaces';
 
 describe('useSpaces', () => {
   test('lists existing spaces', async () => {
-    const { client } = await createClient({ createIdentity: true });
+    const { client } = await createClient({ createIdentity: true, createSpace: true });
     const wrapper = await createClientContextProvider(client);
     const { result } = renderHook(() => useSpaces(), { wrapper });
     expect(result.current.length).to.eq(1);
   });
 
   test('updates when new spaces are created', async () => {
-    const { client } = await createClient({ createIdentity: true });
+    const { client } = await createClient({ createIdentity: true, createSpace: true });
     const wrapper = await createClientContextProvider(client);
     const { result, rerender } = renderHook(() => useSpaces(), { wrapper });
     expect(result.current.length).to.eq(1);
@@ -31,23 +30,17 @@ describe('useSpaces', () => {
 });
 
 describe('useSpace', () => {
-  test('gets default space', async () => {
-    const { client } = await createClient();
+  test('returns undefined when no id provided', async () => {
+    const { client } = await createClient({ createIdentity: true });
     const wrapper = await createClientContextProvider(client);
-    const { result, rerender } = renderHook(() => useSpace(), { wrapper });
+    const { result } = renderHook(() => useSpace(undefined), { wrapper });
     expect(result.current).to.be.undefined;
-    await act(async () => {
-      await client.halo.createIdentity();
-      await client.spaces.waitUntilReady();
-    });
-    rerender();
-    expect(result.current).to.not.be.undefined;
   });
 
-  test('gets space by key', async () => {
+  test('gets space by id', async () => {
     const { client, space } = await createClient({ createIdentity: true, createSpace: true });
     const wrapper = await createClientContextProvider(client);
-    const { result } = renderHook(() => useSpace(space!.key), { wrapper });
+    const { result } = renderHook(() => useSpace(space!.id), { wrapper });
     expect(result.current).to.not.be.undefined;
   });
 });