@dxos/react-client 0.8.4-main.ae835ea → 0.8.4-main.bc674ce

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@dxos/react-client",
-  "version": "0.8.4-main.ae835ea",
+  "version": "0.8.4-main.bc674ce",
   "description": "React client API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     "./devtools": {
@@ -86,42 +90,42 @@
   },
   "dependencies": {
     "react-error-boundary": "^4.0.13",
-    "@dxos/async": "0.8.4-main.ae835ea",
-    "@dxos/codec-protobuf": "0.8.4-main.ae835ea",
-    "@dxos/config": "0.8.4-main.ae835ea",
-    "@dxos/debug": "0.8.4-main.ae835ea",
-    "@dxos/context": "0.8.4-main.ae835ea",
-    "@dxos/echo": "0.8.4-main.ae835ea",
-    "@dxos/echo-signals": "0.8.4-main.ae835ea",
-    "@dxos/client": "0.8.4-main.ae835ea",
-    "@dxos/invariant": "0.8.4-main.ae835ea",
-    "@dxos/log": "0.8.4-main.ae835ea",
-    "@dxos/node-std": "0.8.4-main.ae835ea",
-    "@dxos/protocols": "0.8.4-main.ae835ea",
-    "@dxos/react-hooks": "0.8.4-main.ae835ea",
-    "@dxos/util": "0.8.4-main.ae835ea"
+    "@dxos/async": "0.8.4-main.bc674ce",
+    "@dxos/client": "0.8.4-main.bc674ce",
+    "@dxos/codec-protobuf": "0.8.4-main.bc674ce",
+    "@dxos/context": "0.8.4-main.bc674ce",
+    "@dxos/config": "0.8.4-main.bc674ce",
+    "@dxos/debug": "0.8.4-main.bc674ce",
+    "@dxos/echo": "0.8.4-main.bc674ce",
+    "@dxos/echo-react": "0.8.4-main.bc674ce",
+    "@dxos/log": "0.8.4-main.bc674ce",
+    "@dxos/protocols": "0.8.4-main.bc674ce",
+    "@dxos/invariant": "0.8.4-main.bc674ce",
+    "@dxos/react-hooks": "0.8.4-main.bc674ce",
+    "@dxos/node-std": "0.8.4-main.bc674ce",
+    "@dxos/util": "0.8.4-main.bc674ce"
   },
   "devDependencies": {
-    "@types/react": "~19.2.2",
-    "@types/react-dom": "~19.2.2",
-    "react": "~19.2.0",
-    "react-dom": "~19.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.ae835ea",
-    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.ae835ea",
-    "@dxos/react-ui": "0.8.4-main.ae835ea",
-    "@dxos/react-ui-theme": "0.8.4-main.ae835ea",
-    "@dxos/storybook-utils": "0.8.4-main.ae835ea",
-    "@dxos/test-utils": "0.8.4-main.ae835ea"
+    "@dxos/random": "0.8.4-main.bc674ce",
+    "@dxos/react-ui": "0.8.4-main.bc674ce",
+    "@dxos/storybook-utils": "0.8.4-main.bc674ce",
+    "@dxos/test-utils": "0.8.4-main.bc674ce",
+    "@dxos/ui-theme": "0.8.4-main.bc674ce",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.bc674ce"
   },
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3"
   },
   "optionalDependencies": {
-    "@dxos/random": "0.8.4-main.ae835ea",
-    "@dxos/react-ui": "0.8.4-main.ae835ea",
-    "@dxos/react-ui-theme": "0.8.4-main.ae835ea"
+    "@dxos/random": "0.8.4-main.bc674ce",
+    "@dxos/ui-theme": "0.8.4-main.bc674ce",
+    "@dxos/react-ui": "0.8.4-main.bc674ce"
   },
   "publishConfig": {
     "access": "public"

package/src/client/ClientProvider.tsx

@@ -13,7 +13,6 @@ 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 { useAsyncEffect, useControlledState } from '@dxos/react-hooks';
 import { type MaybePromise, type Provider, getAsyncProviderValue } from '@dxos/util';
@@ -56,12 +55,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 +74,17 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
   (
     {
       children,
-      config: configParam,
-      client: clientParam,
-      services: servicesParam,
-      status: statusParam,
+      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 +95,13 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
       throw error;
     }
 
-    const [client, setClient] = useState(clientParam instanceof Client ? clientParam : undefined);
+    const [client, setClient] = useState(clientProp instanceof Client ? clientProp : undefined);
 
     // Provide external access.
     useImperativeHandle(forwardedRef, () => client, [client]);
 
     // Client status subscription.
-    const [status, setStatus] = useControlledState(statusParam);
+    const [status, setStatus] = useControlledState(statusProp);
     useEffect(() => {
       if (!client) {
         return;
@@ -148,15 +134,15 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
 
       let client: Client;
       try {
-        if (clientParam) {
+        if (clientProp) {
           // Asynchronously request client.
-          client = await getAsyncProviderValue(clientParam);
+          client = await getAsyncProviderValue(clientProp);
           await initialize(client);
         } else {
           // Asynchronously construct client (config may be undefined).
-          const config = await getAsyncProviderValue(configParam);
+          const config = await getAsyncProviderValue(configProp);
           log('resolved config', { config });
-          const services = await getAsyncProviderValue(servicesParam, config);
+          const services = await getAsyncProviderValue(servicesProp, config);
           log('created services', { services });
           client = new Client({ config, services, ...options });
           log('created client');
@@ -172,7 +158,7 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
         log('clean up');
         disposed = true;
         // Only destroy if the client is not provided by the parent.
-        if (!clientParam) {
+        if (!clientProp) {
           void client
             ?.destroy()
             .then(() => {
@@ -181,7 +167,7 @@ export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps
             .catch((err) => log.catch(err));
         }
       };
-    }, [configParam, clientParam, servicesParam, noBanner]);
+    }, [configProp, clientProp, servicesProp, noBanner]);
 
     if (!client?.initialized || status !== SystemStatus.ACTIVE) {
       return <Fallback client={client} status={status} />;

package/src/echo/index.ts

@@ -3,12 +3,12 @@
 //
 
 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';

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/useQueue.ts

@@ -6,7 +6,7 @@ import { useEffect, useMemo, useRef } from 'react';
 
 import { type Queue } from '@dxos/client/echo';
 import { raise } from '@dxos/debug';
-import { type Obj, type Relation } from '@dxos/echo';
+import { type Entity } from '@dxos/echo';
 import { type DXN } from '@dxos/keys';
 
 import { useClient } from '../client';
@@ -24,7 +24,7 @@ export type UseQueueOptions = {
 // TODO(dmaretskyi): Move into client package.
 // TODO(dmaretskyi): Consider passing the space into the hook to support queue DXNs without space id.
 // TODO(ZaymonFC): If queue is unchanged returned object should be refferentially stable on poll.
-export const useQueue = <T extends Obj.Any | Relation.Any>(
+export const useQueue = <T extends Entity.Unknown>(
   queueDxn?: DXN,
   options: UseQueueOptions = {},
 ): Queue<T> | undefined => {

package/src/echo/useSpaceInvitations.ts

@@ -6,19 +6,24 @@ import { useMemo } from 'react';
 
 import { MulticastObservable } from '@dxos/async';
 import { type PublicKey } from '@dxos/client';
+import { type SpaceId } from '@dxos/client/echo';
 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

@@ -47,7 +47,7 @@ describe('useSpace', () => {
   test('gets space by key', 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;
   });
 });

package/src/echo/useSpaces.ts

@@ -4,37 +4,45 @@
 
 import { useState } from 'react';
 
-import { type PublicKeyLike } from '@dxos/client';
-import { type Space, SpaceState } from '@dxos/client/echo';
+import { PublicKey } from '@dxos/client';
+import { type Space, type SpaceId, SpaceState } from '@dxos/client/echo';
 import { useAsyncEffect, useMulticastObservable } from '@dxos/react-hooks';
 
 import { useClient } from '../client';
 
 /**
- * Get a specific Space using its key.
+ * Get a specific Space using its id.
  * The space is not guaranteed to be in the ready state.
- * Returns the default space if no key is provided.
+ * Returns the default space if no id is provided.
  * Requires a ClientProvider somewhere in the parent tree.
  *
- * @param spaceKeyLike the key of the space to look for
+ * @param spaceId the id of the space to look for
  */
-export const useSpace = (spaceKeyLike?: PublicKeyLike): Space | undefined => {
+// TODO(wittjosiah): Currently unable to remove `PublicKey` from this api.
+//  When initially joining a space that is all that is returned.
+export const useSpace = (spaceId?: SpaceId | PublicKey): Space | undefined => {
   const client = useClient();
   const spaces = useMulticastObservable<Space[]>(client.spaces);
   const [ready, setReady] = useState(false);
 
   useAsyncEffect(async () => {
     // Only wait for ready if looking for the default space.
-    if (spaceKeyLike) {
+    if (spaceId) {
       return;
     }
 
     await client.spaces.waitUntilReady();
     setReady(true);
-  }, [client, spaceKeyLike]);
+  }, [client, spaceId]);
 
-  if (spaceKeyLike) {
-    return spaces.find((space) => space.key.equals(spaceKeyLike) || space.id === spaceKeyLike);
+  if (spaceId) {
+    return spaces.find((space) => {
+      if (spaceId instanceof PublicKey) {
+        return space.key.equals(spaceId);
+      }
+
+      return space.id === spaceId;
+    });
   }
 
   if (ready && client.halo.identity.get()) {
@@ -42,7 +50,20 @@ export const useSpace = (spaceKeyLike?: PublicKeyLike): Space | undefined => {
   }
 };
 
-export type UseSpacesParams = {
+/**
+ * Get a Space database by the id of the space.
+ * The space is not guaranteed to be in the ready state.
+ * Returns the default space if no id is provided.
+ * Requires a ClientProvider somewhere in the parent tree.
+ *
+ * @param spaceId the id of the space to look for
+ */
+export const useDatabase = (spaceId?: SpaceId): Space['db'] | undefined => {
+  const space = useSpace(spaceId);
+  return space?.db;
+};
+
+export type UseSpacesProps = {
   /**
    * Return uninitialized spaces as well.
    */
@@ -55,7 +76,7 @@ export type UseSpacesParams = {
  * By default, only ready spaces are returned.
  * @returns an array of Spaces
  */
-export const useSpaces = ({ all = false }: UseSpacesParams = {}): Space[] => {
+export const useSpaces = ({ all = false }: UseSpacesProps = {}): Space[] => {
   const client = useClient();
   const spaces = useMulticastObservable<Space[]>(client.spaces);
 

package/src/echo/useSyncState.ts

@@ -30,7 +30,7 @@ export const useSyncState = (): SpaceSyncStateMap => {
         }
 
         ctx.onDispose(
-          space.db.subscribeToSyncState(ctx, ({ peers = [] }) => {
+          space.internal.db.subscribeToSyncState(ctx, ({ peers = [] }) => {
             const syncState = peers.find((state) => isEdgePeerId(state.peerId, space.id));
             if (syncState) {
               setSpaceState((spaceState) => ({ ...spaceState, [space.id]: syncState }));
@@ -62,7 +62,7 @@ export const useSpaceSyncState = (space: Space): PeerSyncState | undefined => {
 
   useEffect(() => {
     const ctx = new Context();
-    space.db.subscribeToSyncState(ctx, ({ peers = [] }) => {
+    space.internal.db.subscribeToSyncState(ctx, ({ peers = [] }) => {
       const syncState = peers.find((state) => isEdgePeerId(state.peerId, space.id));
       if (syncState) {
         setSpaceState(syncState);

package/src/playwright/playwright.config.ts

@@ -10,7 +10,7 @@ export default defineConfig({
   ...e2ePreset(import.meta.dirname),
   // TODO(wittjosiah): Avoid hard-coding ports.
   webServer: {
-    command: 'moon run storybook:serve-e2e -- --port=9000',
+    command: 'moon run storybook-react:serve-e2e -- --port=9000',
     port: 9000,
     reuseExistingServer: false,
   },

package/src/testing/ClientRepeater.stories.tsx

@@ -5,6 +5,7 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
+import { Obj } from '@dxos/echo';
 import { Input } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
 import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
@@ -32,9 +33,9 @@ const ClientStory = () => {
   return <JsonPanel value={client.toJSON()} />;
 };
 
-const ClientSpace = ({ spaceKey }: ClientRepeatedComponentProps) => {
+const ClientSpace = ({ spaceId }: ClientRepeatedComponentProps) => {
   const client = useClient();
-  const space = useSpace(spaceKey);
+  const space = useSpace(spaceId);
   if (!space?.isOpen) {
     return null;
   }
@@ -45,7 +46,11 @@ const ClientSpace = ({ spaceKey }: ClientRepeatedComponentProps) => {
         <Input.TextInput
           placeholder='Name'
           value={space.properties.name}
-          onChange={(event) => (space.properties.name = event.target.value)}
+          onChange={(event) =>
+            Obj.change(space.properties, (p) => {
+              p.name = event.target.value;
+            })
+          }
         />
       </Input.Root>
       <JsonPanel value={client.toJSON()} />

package/src/testing/ClientRepeater.tsx

@@ -2,20 +2,20 @@
 // Copyright 2022 DXOS.org
 //
 
-import React, { type FC, useEffect, useRef, useState } from 'react';
+import React, { type FC, useRef, useState } from 'react';
 
-import { Client, type PublicKey } from '@dxos/client';
+import { Client } from '@dxos/client';
 import { TestBuilder, performInvitation } from '@dxos/client/testing';
-import { type TypedObject } from '@dxos/echo/internal';
-import { registerSignalsRuntime } from '@dxos/echo-signals/react';
+import { type Type } from '@dxos/echo';
 import { faker } from '@dxos/random';
 import { useAsyncEffect } from '@dxos/react-hooks';
 
 import { ClientProvider } from '../client';
+import { type SpaceId } from '../echo';
 
 import { type WithClientProviderProps } from './withClientProvider';
 
-export type ClientRepeatedComponentProps = { id: number; count: number; spaceKey?: PublicKey };
+export type ClientRepeatedComponentProps = { id: number; count: number; spaceId?: SpaceId };
 
 export type ClientRepeaterControlsProps = { clients: Client[] };
 
@@ -26,7 +26,7 @@ export type ClientRepeaterProps<P extends ClientRepeatedComponentProps> = {
   controls?: FC<ClientRepeaterControlsProps>;
   count?: number;
   clients?: Client[];
-  types?: TypedObject[];
+  types?: Type.Obj.Any[];
   args?: Omit<P, 'id' | 'count'>;
 } & Pick<WithClientProviderProps, 'createIdentity' | 'createSpace' | 'onCreateSpace'>;
 
@@ -50,12 +50,9 @@ export const ClientRepeater = <P extends ClientRepeatedComponentProps>(props: Cl
     createSpace,
     onCreateSpace,
   } = props;
-  useEffect(() => {
-    registerSignalsRuntime();
-  }, []);
 
   const [clients, setClients] = useState(props.clients ?? []);
-  const [spaceKey, setSpaceKey] = useState<PublicKey>();
+  const [spaceId, setSpaceId] = useState<SpaceId>();
 
   const testBuilder = useRef(new TestBuilder());
   useAsyncEffect(async () => {
@@ -71,7 +68,7 @@ export const ClientRepeater = <P extends ClientRepeatedComponentProps>(props: Cl
     if (createSpace) {
       const client = clients[0];
       const space = await client.spaces.create({ name: faker.commerce.productName() });
-      setSpaceKey(space.key);
+      setSpaceId(space.id);
       await onCreateSpace?.({ client, space }, {});
       await Promise.all(clients.slice(1).flatMap((client) => performInvitation({ host: space, guest: client.spaces })));
     }
@@ -88,7 +85,7 @@ export const ClientRepeater = <P extends ClientRepeatedComponentProps>(props: Cl
       {Controls && <Controls clients={clients} />}
       {clients.map((client, index) => (
         <ClientProvider key={index} client={client}>
-          <Component id={index} count={clients.length} spaceKey={spaceKey} {...{ ...props.args }} />
+          <Component id={index} count={clients.length} spaceId={spaceId} {...{ ...props.args }} />
         </ClientProvider>
       ))}
     </>

package/src/testing/context.tsx

@@ -4,16 +4,17 @@
 
 import { createContext, useContext } from 'react';
 
-import { type Space } from '@dxos/client/echo';
+import { type Space, type SpaceId } from '@dxos/client/echo';
 import { raise } from '@dxos/debug';
 
 export type ClientStory = {
+  index?: number;
+  spaceId?: SpaceId;
   space?: Space;
 };
 
-// TODO(wittjosiah): Add to multi-client as well.
 export const ClientStory = createContext<ClientStory | undefined>(undefined);
 
-export const useClientProvider = (): ClientStory => {
+export const useClientStory = (): ClientStory => {
   return useContext(ClientStory) ?? raise(new Error('Missing ClientStory'));
 };