@dxos/plugin-space 0.10.0 → 0.11.1

package/src/capabilities/navigation-handler/navigation-handler.ts

@@ -3,17 +3,23 @@
 //
 
 import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { AppCapabilities } from '@dxos/app-toolkit';
+import { AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
+import { Identity } from '@dxos/halo';
 import { log } from '@dxos/log';
-import { ClientCapabilities } from '@dxos/plugin-client';
+import { HaloServicesLayer } from '@dxos/plugin-client';
+
+import { meta } from '#meta';
 
 import { SpaceOperation } from '../../operations';
 
 export type NavigationHandlerOptions = {
   invitationProp?: string;
+  /** Set false when another plugin (e.g. plugin-onboarding) owns the invitation URL param. */
+  invitationUrlHandler?: boolean;
 };
 
 /**
@@ -21,21 +27,23 @@ export type NavigationHandlerOptions = {
  * Handles ?spaceInvitationCode=X → join space via invitation.
  */
 export default Capability.makeModule(
-  Effect.fnUntraced(function* ({ invitationProp = 'spaceInvitationCode' }: NavigationHandlerOptions = {}) {
+  Effect.fnUntraced(function* ({
+    invitationProp = 'spaceInvitationCode',
+    invitationUrlHandler = true,
+  }: NavigationHandlerOptions = {}) {
     const capabilities = yield* Capability.Service;
     const operationService = yield* Capability.get(Capabilities.OperationInvoker);
-    const client = yield* Capability.get(ClientCapabilities.Client);
 
     const handler: AppCapabilities.NavigationHandler = (url: URL) =>
       Effect.gen(function* () {
-        const invitationCode = url.searchParams.get(invitationProp);
+        const invitationCode = invitationUrlHandler ? url.searchParams.get(invitationProp) : null;
         if (!invitationCode) {
           return;
         }
 
         // Ignore invitations that arrive before a local identity exists rather than forcing
         // identity creation here, bypassing the normal onboarding flow.
-        if (!client.halo.identity.get()) {
+        if (Option.isNone(yield* Identity.getSnapshot.pipe(Effect.provide(HaloServicesLayer)))) {
           return;
         }
 
@@ -43,9 +51,21 @@ export default Capability.makeModule(
         removeQueryParam(invitationProp);
         yield* Operation.invoke(SpaceOperation.Join, { invitationCode });
       }).pipe(
+        Effect.catchAll((error) =>
+          Effect.gen(function* () {
+            log.warn('navigation handler failed', { error });
+            yield* Operation.invoke(LayoutOperation.AddToast, {
+              id: `${meta.profile.key}/navigation-failed`,
+              title: ['navigation-failed-toast.title', { ns: meta.profile.key }],
+              description: ['navigation-failed-toast.description', { ns: meta.profile.key }],
+              icon: 'ph--warning--regular',
+            }).pipe(
+              Effect.catchAll((toastError) => Effect.sync(() => log.warn('failed to add toast', { toastError }))),
+            );
+          }),
+        ),
         Effect.provideService(Capability.Service, capabilities),
         Effect.provideService(Operation.Service, operationService),
-        Effect.orDie,
       );
 
     return Capability.contributes(AppCapabilities.NavigationHandler, handler);

package/src/capabilities/navigation-target-resolver.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities, type AppCapabilities as AppCaps, GraphPath } from '@dxos/app-toolkit';
+import { Database, Entity } from '@dxos/echo';
+import { EID } from '@dxos/keys';
+import { getPluginSettingsSectionPath } from '@dxos/plugin-settings';
+import { Position } from '@dxos/util';
+
+import { meta } from '#meta';
+
+import { resolveCollectionObjectPath } from '../collection-path';
+import { resolveTypeSectionPath } from '../type-section-path';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+    const resolver: AppCaps.NavigationTargetResolver = (query) =>
+      Effect.gen(function* () {
+        if (!query?.uri) {
+          return [
+            {
+              path: getPluginSettingsSectionPath(meta.profile.key),
+              label: 'Spaces settings',
+              type: 'settings',
+            },
+          ];
+        }
+
+        const eid = EID.tryParse(query.uri);
+        if (!eid) {
+          return [];
+        }
+
+        const { db } = yield* Database.Service;
+        const ref = db.makeRef(eid);
+        const object = yield* Database.load(ref).pipe(Effect.catchAll(() => Effect.succeed(null)));
+        if (!object) {
+          return [];
+        }
+
+        const typename = Entity.getTypename(object);
+        if (!typename) {
+          return [];
+        }
+
+        const label = Entity.getLabel(object) ?? '';
+
+        // Where the tree actually shows the object: its place in the collection tree, or the sidebar
+        // section its type declares (Chat, Project, …). Both precede the database path, which every
+        // object has but no visible node bears — hence `Position.last`.
+        const collectionPath = yield* resolveCollectionObjectPath({ objectId: object.id });
+        const sectionPath = resolveTypeSectionPath(capabilities, {
+          spaceId: db.spaceId,
+          typename,
+          objectId: object.id,
+        });
+
+        return [
+          ...(collectionPath ? [{ path: collectionPath, label, type: typename }] : []),
+          ...(sectionPath ? [{ path: sectionPath, label, type: typename }] : []),
+          {
+            path: GraphPath.getObjectPath(db.spaceId, typename, object.id),
+            label,
+            type: typename,
+            position: Position.last,
+          },
+        ];
+      });
+
+    return Capability.contributes(AppCapabilities.NavigationTargetResolver, resolver);
+  }),
+);

package/src/capabilities/react-surface.ts

@@ -0,0 +1,274 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { type ComponentProps } from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { Collection, Obj, Type } from '@dxos/echo';
+import { SchemaEx } from '@dxos/effect';
+import { type Space, isSpace } from '@dxos/react-client/echo';
+import { Position } from '@dxos/util';
+
+import {
+  CollectionArticle,
+  CollectionSection,
+  CreateObjectDialog,
+  CreateSpaceDialog,
+  DefaultProperties,
+  ImportSpaceDialog,
+  InlineSyncStatus,
+  JoinDialog,
+  RecordArticle,
+  RelatedArticle,
+  RenamePopover,
+  type RenameSubject,
+  SmallPresenceLive,
+  SpaceHomeArticle,
+  SyncStatus,
+} from '#containers';
+import { meta } from '#meta';
+import {
+  HueAnnotationId,
+  IconAnnotationId,
+  SPACE_HOME_NODE_TYPE,
+  SpaceHomeContent,
+  TypeInputOptionsAnnotationId,
+} from '#types';
+
+import {
+  CREATE_OBJECT_DIALOG,
+  CREATE_SPACE_DIALOG,
+  IMPORT_SPACE_DIALOG,
+  JOIN_DIALOG,
+  RENAME_POPOVER,
+} from '../constants';
+import { HueField, IconField, TypenameField } from './SpaceFormFields';
+import {
+  NavbarPresenceSurface,
+  NavtreePresenceSurface,
+  SelectedObjectsSurface,
+  SpaceHomeDashboardSurface,
+  SpaceHomeRecentSurface,
+  SpaceMembersSurface,
+  SpaceSchemaSurface,
+  SpaceSettingsPropertiesSurface,
+  SpaceSettingsSurface,
+  TypeArticleSurface,
+  ViewEditorSurface,
+} from './SpaceSurfaces';
+import { tryGetViewForObject } from './try-get-view';
+
+type ReactSurfaceOptions = {
+  createInvitationUrl: (invitationCode: string) => string;
+};
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* ({ createInvitationUrl }: ReactSurfaceOptions) {
+    return Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'spaceHome',
+        filter: AppSurface.literal(AppSurface.Article, SPACE_HOME_NODE_TYPE),
+        component: SpaceHomeArticle,
+        props: ({ role, data: { attendableId, properties } }) => ({
+          role,
+          attendableId,
+          space: properties?.space,
+        }),
+      }),
+      Surface.create({
+        id: 'spaceHomeRecent',
+        filter: Surface.makeFilter(SpaceHomeContent),
+        component: SpaceHomeRecentSurface,
+        props: ({ data: { space } }) => ({ space }),
+      }),
+      Surface.create({
+        id: 'spaceHomeDashboard',
+        filter: Surface.makeFilter(SpaceHomeContent),
+        component: SpaceHomeDashboardSurface,
+        props: ({ data: { space } }) => ({ space }),
+      }),
+      Surface.create({
+        id: 'collectionFallback',
+        position: Position.last,
+        filter: AppSurface.object(AppSurface.Article, Collection.Collection),
+        component: CollectionArticle,
+        props: ({ data: { subject, attendableId } }) => ({ subject, attendableId }),
+      }),
+      Surface.create({
+        id: 'recordArticle',
+        position: Position.last,
+        filter: AppSurface.subject(AppSurface.Article, Obj.isObject),
+        component: RecordArticle,
+        props: ({ data: { subject } }) => ({ subject }),
+      }),
+      Surface.create({
+        id: 'typeCollection',
+        filter: AppSurface.subject(AppSurface.Article, Type.isType),
+        component: TypeArticleSurface,
+        props: ({ role, data: { subject, attendableId, properties } }) => ({
+          role,
+          type: subject,
+          attendableId,
+          properties,
+        }),
+      }),
+      Surface.create({
+        id: 'pluginSettings',
+        filter: AppSurface.settings(AppSurface.Article, meta.profile.key),
+        component: SpaceSettingsSurface,
+        props: ({ data: { subject } }) => ({ subject }),
+      }),
+      Surface.create({
+        id: 'companion.objectProperties',
+        filter: AppSurface.allOf(
+          AppSurface.literal(AppSurface.Article, 'settings'),
+          AppSurface.companion(AppSurface.Article),
+        ),
+        component: DefaultProperties,
+        props: ({ role, ref, data: { companionTo } }) => ({ role, subject: companionTo, ref }),
+      }),
+      Surface.create({
+        id: 'companion.related',
+        filter: AppSurface.allOf(
+          AppSurface.literal(AppSurface.Article, 'related'),
+          AppSurface.companion(AppSurface.Article),
+        ),
+        component: RelatedArticle,
+        props: ({ role, data: { companionTo } }) => ({ role, companionTo }),
+      }),
+      Surface.create({
+        id: 'spaceSettingsProperties',
+        filter: AppSurface.literal(AppSurface.Article, `${meta.profile.key}.general`),
+        component: SpaceSettingsPropertiesSurface,
+      }),
+      Surface.create({
+        id: 'spaceSettingsMembers',
+        position: Position.first,
+        filter: AppSurface.literal(AppSurface.Article, `${meta.profile.key}.members`),
+        component: SpaceMembersSurface,
+        props: () => ({ createInvitationUrl }),
+      }),
+      Surface.create({
+        id: 'spaceSettingsSchema',
+        filter: AppSurface.literal(AppSurface.Article, `${meta.profile.key}.schema`),
+        component: SpaceSchemaSurface,
+      }),
+      Surface.create({
+        id: 'selectedObjects',
+        filter: AppSurface.allOf(
+          AppSurface.literal(AppSurface.Article, 'selected-objects'),
+          AppSurface.companion(
+            AppSurface.Article,
+            (value): value is Type.AnyEntity | Obj.Unknown => Type.isType(value) || Obj.isObject(value),
+          ),
+        ),
+        component: SelectedObjectsSurface,
+        props: ({ ref, data: { companionTo } }) => ({ companionTo, ref }),
+      }),
+      Surface.create({
+        id: JOIN_DIALOG,
+        filter: AppSurface.component<ComponentProps<typeof JoinDialog>>(AppSurface.Dialog, JOIN_DIALOG),
+        component: JoinDialog,
+        props: ({ data: { props } }) => ({ ...props }),
+      }),
+      Surface.create({
+        id: CREATE_SPACE_DIALOG,
+        filter: AppSurface.component(AppSurface.Dialog, CREATE_SPACE_DIALOG),
+        component: CreateSpaceDialog,
+      }),
+      Surface.create({
+        id: IMPORT_SPACE_DIALOG,
+        filter: AppSurface.component(AppSurface.Dialog, IMPORT_SPACE_DIALOG),
+        component: ImportSpaceDialog,
+      }),
+      Surface.create({
+        id: CREATE_OBJECT_DIALOG,
+        filter: AppSurface.component<ComponentProps<typeof CreateObjectDialog>>(
+          AppSurface.Dialog,
+          CREATE_OBJECT_DIALOG,
+        ),
+        component: CreateObjectDialog,
+        props: ({ data: { props } }) => ({ ...props }),
+      }),
+      Surface.create({
+        id: 'createInitialSpaceFormHue',
+        filter: AppSurface.formInputBySchema((ast) => !!SchemaEx.findAnnotation<boolean>(ast, HueAnnotationId)),
+        component: HueField,
+      }),
+      Surface.create({
+        id: 'createInitialSpaceFormIcon',
+        filter: AppSurface.formInputBySchema((ast) => !!SchemaEx.findAnnotation<boolean>(ast, IconAnnotationId)),
+        component: IconField,
+      }),
+      Surface.create({
+        id: 'typenameFormInput',
+        filter: AppSurface.formInput(
+          (data) =>
+            data.prop === 'typename' && !!SchemaEx.findAnnotation(data.schema.ast, TypeInputOptionsAnnotationId),
+        ),
+        component: TypenameField,
+      }),
+      Surface.create({
+        id: 'objectProperties',
+        filter: Surface.makeFilter(
+          AppSurface.ObjectProperties,
+          (data) => Obj.isObject(data.subject) && !!tryGetViewForObject(data.subject),
+        ),
+        component: ViewEditorSurface,
+        props: ({ data: { subject } }) => ({ subject }),
+      }),
+      Surface.create({
+        id: RENAME_POPOVER,
+        filter: AppSurface.component<RenameSubject>(AppSurface.Popover, RENAME_POPOVER),
+        component: RenamePopover,
+        props: ({ data: { props } }) => ({ subject: props }),
+      }),
+      Surface.create({
+        id: 'navtreePresence',
+        filter: AppSurface.subject(AppSurface.NavtreeItemEnd, Obj.isObject),
+        component: NavtreePresenceSurface,
+        props: ({ data: { id, open } }) => ({ id, open }),
+      }),
+      // TODO(wittjosiah): Attention glyph for non-echo items should be handled elsewhere.
+      Surface.create({
+        id: 'navtreePresenceFallback',
+        position: Position.last,
+        filter: Surface.makeFilter(AppSurface.NavtreeItemEnd),
+        component: SmallPresenceLive,
+        props: ({ data: { id, open } }) => ({ id, open }),
+      }),
+      // TODO(wittjosiah): Broken?
+      Surface.create({
+        id: 'navtreeSyncStatus',
+        filter: AppSurface.subject(AppSurface.NavtreeItemEnd, isSpace),
+        component: InlineSyncStatus,
+        props: ({ data: { subject, open } }) => ({ space: subject, open }),
+      }),
+      Surface.create({
+        id: 'navbarPresence',
+        position: Position.first,
+        filter: AppSurface.subject(
+          AppSurface.NavbarEnd,
+          (value): value is Space | Obj.Unknown => isSpace(value) || Obj.isObject(value),
+        ),
+        component: NavbarPresenceSurface,
+        props: ({ data: { subject } }) => ({ subject }),
+      }),
+      Surface.create({
+        id: 'collectionSection',
+        filter: AppSurface.object(AppSurface.Section, Collection.Collection),
+        component: CollectionSection,
+        props: ({ data: { subject } }) => ({ subject }),
+      }),
+      Surface.create({
+        id: 'syncStatus',
+        filter: Surface.makeFilter(AppSurface.StatusIndicator),
+        component: SyncStatus,
+      }),
+    ]);
+  }),
+);

package/src/capabilities/spaces-ready.ts

@@ -7,7 +7,7 @@ import * as Fiber from 'effect/Fiber';
 import * as Option from 'effect/Option';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { AppAnnotation, AppCapabilities, AppSpace, LayoutOperation, Paths } from '@dxos/app-toolkit';
+import { AppAnnotation, AppCapabilities, AppSpace, GraphPath, LayoutOperation } from '@dxos/app-toolkit';
 import { SubscriptionList } from '@dxos/async';
 import { Annotation, Collection, Filter, Obj, Type } from '@dxos/echo';
 import { SPACE_ID_LENGTH, parseId } from '@dxos/keys';
@@ -45,6 +45,7 @@ export default Capability.makeModule(
     const stateAtom = yield* Capability.get(SpaceCapabilities.State);
     const ephemeralAtom = yield* Capability.get(SpaceCapabilities.EphemeralState);
     const client = yield* Capability.get(ClientCapabilities.Client);
+    const haloIdentity = yield* Capability.get(ClientCapabilities.IdentityService);
 
     //
     // Personal space initialization — deferred until found.
@@ -66,7 +67,7 @@ export default Capability.makeModule(
         // Check if deck state indicates we should switch to default space.
         const layout = registry.get(layoutAtom);
         if (layout.workspace === 'default') {
-          yield* invoke(LayoutOperation.SwitchWorkspace, { subject: Paths.getSpacePath(personalSpace.id) });
+          yield* invoke(LayoutOperation.SwitchWorkspace, { subject: GraphPath.getSpacePath(personalSpace.id) });
         }
 
         const queryResults = yield* Effect.promise(() =>
@@ -131,6 +132,8 @@ export default Capability.makeModule(
 
           const node = Graph.getNode(graph, id).pipe(Option.getOrNull);
           if (!node && (isEchoRef(id) || id.length === SPACE_ID_LENGTH)) {
+            // Fire any `resolver` extension for the id first; the timeout below is the fallback when
+            // nothing materializes it.
             void Graph.initialize(graph, id);
             const timeout = setTimeout(async () => {
               const node = Graph.getNode(graph, id).pipe(Option.getOrNull);
@@ -211,7 +214,7 @@ export default Capability.makeModule(
 
       const send = () => {
         const spaces = client.spaces.get();
-        const identity = client.halo.identity.get();
+        const identity = Option.getOrUndefined(haloIdentity.getSnapshot());
         if (identity) {
           // Group parts by space for efficient messaging.
           const idsBySpace = reduceGroupBy(active, (id: string) => {
@@ -248,7 +251,7 @@ export default Capability.makeModule(
 
             void space
               .postMessage('viewing', {
-                identityKey: identity.identityKey.toHex(),
+                identityKey: identity.identityKey,
                 attended: current,
                 added,
                 removed,
@@ -287,10 +290,10 @@ export default Capability.makeModule(
             const { added, removed, attended } = message.payload;
 
             const identityKey = PublicKey.safeFrom(message.payload.identityKey);
-            const currentIdentity = client.halo.identity.get();
+            const currentIdentity = Option.getOrUndefined(haloIdentity.getSnapshot());
             if (
               identityKey &&
-              !currentIdentity?.identityKey.equals(identityKey) &&
+              currentIdentity?.identityKey !== identityKey.toHex() &&
               Array.isArray(added) &&
               Array.isArray(removed)
             ) {
@@ -330,18 +333,28 @@ export default Capability.makeModule(
     subscriptions.add(() => viewingSub.unsubscribe());
 
     // Enable edge replication for all spaces.
-    try {
-      yield* Effect.tryPromise(() =>
-        Promise.all(
-          client.spaces
-            .get()
-            .map((space) => space.internal.setEdgeReplicationPreference(EdgeReplicationSetting.ENABLED)),
-        ),
-      );
-      registry.update(stateAtom, (current) => ({ ...current, enabledEdgeReplication: true }));
-    } catch (err) {
-      log.catch(err);
-    }
+    // Per-space failures (e.g. a timeout waiting for the property to propagate) must not
+    // block activation of the whole plugin, so each space is enabled independently.
+    yield* Effect.tryPromise(() =>
+      Promise.allSettled(
+        client.spaces
+          .get()
+          .filter((space) => space.internal.data.edgeReplication !== EdgeReplicationSetting.ENABLED)
+          .map((space) => space.internal.setEdgeReplicationPreference(EdgeReplicationSetting.ENABLED)),
+      ),
+    ).pipe(
+      Effect.tap((results) =>
+        Effect.sync(() => {
+          results.forEach((result) => {
+            if (result.status === 'rejected') {
+              log.catch(result.reason);
+            }
+          });
+        }),
+      ),
+      Effect.catchAll((err) => Effect.sync(() => log.catch(err))),
+    );
+    registry.update(stateAtom, (current) => ({ ...current, enabledEdgeReplication: true }));
 
     return Capability.contributes(Capabilities.Null, null, () =>
       Effect.gen(function* () {

package/src/capabilities/state.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom } from '@effect-atom/atom-react';
+import { Atom } from '@effect-atom/atom';
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
@@ -37,6 +37,8 @@ export default Capability.makeModule(
       navigableCollections: false,
       viewersByObject: {},
       viewersByIdentity: new ComplexMap<PublicKey, Set<string>>(PublicKey.hash),
+      mergePreview: undefined,
+      lastMergeAt: undefined,
     }).pipe(Atom.keepAlive);
 
     const manager = yield* Capability.get(Capabilities.PluginManager);

package/src/capabilities/try-get-view.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Surface components that cannot be expressed as a `props` mapper, because they call hooks or must
+// render nothing until an ambient value (the active space, a backing view) resolves.
+import * as Option from 'effect/Option';
+
+import { Obj, Type, type View } from '@dxos/echo';
+import { ViewAnnotation } from '@dxos/schema';
+
+// Kept out of `SpaceSurfaces.tsx`: react-refresh only fast-refreshes a module whose
+// exports are all components, so values exported beside them force a full page reload on
+// every edit.
+
+/**
+ * Resolves the view backing an object through its type's `ViewAnnotation` path. The
+ * `objectProperties` filter and both consuming surfaces must agree, so they share this.
+ */
+export const tryGetViewForObject = (subject: Obj.Unknown): View.View | undefined => {
+  const type = Obj.getType(subject);
+  const path = type ? Option.getOrElse(ViewAnnotation.get(Type.getSchema(type)), () => [] as readonly string[]) : [];
+  return path.length > 0 ? ViewAnnotation.tryGetTargetAlongPath(subject, path) : undefined;
+};