@dxos/plugin-space 0.8.4-main.4a85c3132b → 0.8.4-main.51f1e5ca51

package/src/capabilities/app-graph-builder/extensions/types.ts

@@ -0,0 +1,430 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities, AppNode, AppNodeMatcher, LayoutOperation, Segments } from '@dxos/app-toolkit';
+import { type Space, SpaceState, isSpace } from '@dxos/client/echo';
+import { Operation } from '@dxos/compute';
+import { Collection, Filter, Obj, Query, Type } from '@dxos/echo';
+import { AtomObj, AtomQuery } from '@dxos/echo-atom';
+import { EntityKind, SystemTypeAnnotation, getTypeAnnotation } from '@dxos/echo/internal';
+import { ClientCapabilities } from '@dxos/plugin-client/types';
+import { CreateAtom, GraphBuilder, Node } from '@dxos/plugin-graph';
+import { ViewAnnotation } from '@dxos/schema';
+import { createFilename, isNonNullable } from '@dxos/util';
+
+import { meta } from '#meta';
+import { SpaceOperation } from '#operations';
+
+import {
+  ADD_VIEW_TO_SCHEMA_LABEL,
+  BLOCK_REORDER_ABOVE,
+  type MetadataResolver,
+  SNAPSHOT_BY_SCHEMA_LABEL,
+  STATIC_SCHEMA_TYPE,
+  TYPES_SECTION_TYPE,
+  TYPE_COLLECTION_TYPE,
+  buildViewIndex,
+  createObjectNode,
+  downloadBlob,
+  getDynamicLabel,
+} from './shared';
+
+//
+// Extension Factory
+//
+
+/** Creates type-related extensions: types section, schema nodes, schema children, and schema actions. */
+export const createTypeExtensions = Effect.fnUntraced(function* () {
+  const capabilities = yield* Capability.Service;
+
+  const resolve = (_get: any) => (typename: string) =>
+    capabilities.getAll(AppCapabilities.Metadata).find(({ id }) => id === typename)?.metadata ?? {};
+
+  return yield* Effect.all([
+    // Types section virtual node under each space.
+    GraphBuilder.createExtension({
+      id: 'types-section',
+      match: AppNodeMatcher.whenSpace,
+      connector: (space, get) => {
+        const spaceState = get(CreateAtom.fromObservable(space.state));
+        if (spaceState !== SpaceState.SPACE_READY) {
+          return Effect.succeed([]);
+        }
+
+        return Effect.succeed([
+          AppNode.makeSection({
+            id: Segments.types,
+            type: TYPES_SECTION_TYPE,
+            label: ['types-section.label', { ns: meta.id }],
+            icon: 'ph--shapes--regular',
+            space,
+            position: 'fallback',
+            testId: 'spacePlugin.typesSection',
+          }),
+        ]);
+      },
+    }),
+
+    // Schema nodes under the Types virtual node.
+    GraphBuilder.createExtension({
+      id: 'types',
+      match: (node) => {
+        const space = isSpace(node.properties.space) ? node.properties.space : undefined;
+        return node.type === TYPES_SECTION_TYPE && space ? Option.some(space) : Option.none();
+      },
+      connector: (space, get) => {
+        const allSchemas = get(
+          AtomQuery.fromQuery(space.db.schemaRegistry.query({ location: ['database', 'runtime'] })),
+        );
+
+        const userSchemas = allSchemas.filter((schema) => {
+          if (getTypeAnnotation(schema)?.kind === EntityKind.Relation) {
+            return false;
+          }
+          if (SystemTypeAnnotation.get(schema).pipe(Option.getOrElse(() => false))) {
+            return false;
+          }
+          if (Type.getTypename(schema) === Collection.Collection.typename) {
+            return false;
+          }
+          return true;
+        });
+
+        const viewIndex = buildViewIndex(get, space, allSchemas);
+
+        const visibleSchemas = userSchemas.filter((schema) => {
+          if (Type.isMutable(schema)) {
+            return true;
+          }
+          const typename = Type.getTypename(schema);
+          const objects = get(AtomQuery.make(space.db, Filter.typename(typename)));
+          if (ViewAnnotation.has(schema)) {
+            return objects.some((obj) => !viewIndex.isView(obj));
+          }
+          return objects.length > 0 || viewIndex.typenamesWithViews.has(typename);
+        });
+
+        return Effect.succeed(
+          visibleSchemas.map((schema) => createSchemaNode({ schema, space, resolve: resolve(get), get })),
+        );
+      },
+    }),
+
+    // {All} virtual node + view objects under each schema node.
+    GraphBuilder.createExtension({
+      id: 'schema-children',
+      match: (node) => {
+        const space = isSpace(node.properties.space) ? node.properties.space : undefined;
+        return space && (Obj.instanceOf(Type.PersistentType, node.data) || Schema.isSchema(node.data))
+          ? Option.some({ space, schema: node.data })
+          : Option.none();
+      },
+      connector: ({ space, schema }, get) => {
+        const client = get(capabilities.atom(ClientCapabilities.Client)).at(0);
+        const schemas = client
+          ? get(AtomQuery.fromQuery(client.graph.schemaRegistry.query({ location: ['runtime'] })))
+          : [];
+
+        const typename = Schema.isSchema(schema) ? Type.getTypename(schema as Type.AnyObj) : schema.typename;
+
+        // {All} virtual node.
+        const allNode = Node.make({
+          id: 'all',
+          type: TYPE_COLLECTION_TYPE,
+          data: { space, typename },
+          properties: {
+            label: ['type-collection-all.label', { ns: meta.id }],
+            icon: 'ph--list--regular',
+            iconHue: 'neutral',
+            role: 'branch',
+            testId: `spacePlugin.typeCollectionAll.${typename}`,
+            selectable: false,
+            draggable: false,
+            droppable: false,
+            childrenDroppable: false,
+            blockInstruction: BLOCK_REORDER_ABOVE,
+          },
+        });
+
+        // View objects for this schema.
+        const viewIndex = buildViewIndex(get, space, schemas);
+        const viewNodes = viewIndex
+          .getViewsForTypename(typename)
+          .map((object: Obj.Unknown) =>
+            createObjectNode({
+              db: space.db,
+              object,
+              resolve: resolve(get),
+              droppable: false,
+            }),
+          )
+          .filter(isNonNullable);
+
+        return Effect.succeed([allNode, ...viewNodes]);
+      },
+    }),
+
+    // Objects of the schema type under the {All} node.
+    GraphBuilder.createExtension({
+      id: 'type-collection-objects',
+      match: (node) => {
+        if (node.type !== TYPE_COLLECTION_TYPE || !node.data?.space || !node.data?.typename) {
+          return Option.none();
+        }
+        return Option.some({ space: node.data.space as Space, typename: node.data.typename as string });
+      },
+      connector: ({ space, typename }, get) => {
+        const client = get(capabilities.atom(ClientCapabilities.Client)).at(0);
+        const schemas = client
+          ? get(AtomQuery.fromQuery(client.graph.schemaRegistry.query({ location: ['runtime'] })))
+          : [];
+        const viewIndex = buildViewIndex(get, space, schemas);
+        const objects = get(AtomQuery.make(space.db, Filter.typename(typename))).filter(
+          (object: Obj.Unknown) => !viewIndex.isView(object),
+        );
+
+        return Effect.succeed(
+          objects
+            .map((object: Obj.Unknown) => {
+              get(AtomObj.make(object));
+              return createObjectNode({
+                db: space.db,
+                object,
+                resolve: resolve(get),
+                droppable: false,
+              });
+            })
+            .filter(isNonNullable)
+            .toSorted((nodeA, nodeB) => {
+              const labelA = typeof nodeA.properties.label === 'string' ? nodeA.properties.label : '';
+              const labelB = typeof nodeB.properties.label === 'string' ? nodeB.properties.label : '';
+              return labelA.localeCompare(labelB);
+            }),
+        );
+      },
+    }),
+
+    // Actions for schema nodes.
+    GraphBuilder.createExtension({
+      id: 'schema-actions',
+      match: (node) => {
+        const space = isSpace(node.properties.space) ? node.properties.space : undefined;
+        return space && Schema.isSchema(node.data) ? Option.some({ space, schema: node.data }) : Option.none();
+      },
+      actions: ({ space, schema }, get) => {
+        const client = get(capabilities.atom(ClientCapabilities.Client)).at(0);
+        const schemas = client
+          ? get(AtomQuery.fromQuery(client.graph.schemaRegistry.query({ location: ['runtime'] })))
+          : [];
+
+        const targetTypename = Type.getTypename(schema as Type.AnyObj);
+        const viewIndex = buildViewIndex(get, space, schemas);
+        const deletable =
+          Type.isMutable(schema as Type.AnyObj) && viewIndex.getViewsForTypename(targetTypename).length === 0;
+
+        return Effect.succeed(
+          createSchemaActions({
+            schema: schema as Type.AnyObj,
+            space,
+            deletable,
+            resolve: resolve(get),
+          }),
+        );
+      },
+    }),
+  ]);
+});
+
+//
+// Helpers
+//
+
+/** Returns schemas keyed uniquely by typename, preferring later entries. */
+const uniqueSchemasByTypename = <TSchema extends Type.AnyEntity>(schemas: TSchema[]): TSchema[] => {
+  const uniqueSchemas = new Map<string, TSchema>();
+  for (const schema of schemas) {
+    uniqueSchemas.set(Type.getTypename(schema), schema);
+  }
+
+  return [...uniqueSchemas.values()];
+};
+
+/** Builds a graph node for a schema in the Types subtree. */
+const createSchemaNode = ({
+  schema,
+  space,
+  resolve,
+  get,
+}: {
+  schema: Type.AnyEntity;
+  space: Space;
+  resolve: MetadataResolver;
+  get: Atom.Context;
+}): Node.NodeArg<Type.AnyEntity> => {
+  const typename = Type.getTypename(schema);
+  const metadata = resolve(typename);
+  const { label, nodeId } = Match.value(schema).pipe(
+    Match.when(Type.isMutable, (mutableSchema) => {
+      const persistentSchema = mutableSchema.persistentSchema;
+      const snapshot = get(AtomObj.make(persistentSchema));
+      return {
+        label: snapshot.name || ['object-name.placeholder', { ns: Type.PersistentType.typename }],
+        nodeId: typename,
+      };
+    }),
+    Match.orElse(() => ({
+      label: getDynamicLabel('typename.label', typename, { count: 2, defaultValue: typename }),
+      nodeId: typename,
+    })),
+  );
+  const icon = Type.isMutable(schema) ? 'ph--cube--regular' : (metadata.icon ?? 'ph--placeholder--regular');
+  const iconHue = Type.isMutable(schema) ? 'neutral' : metadata.iconHue;
+  return Node.make({
+    id: nodeId,
+    type: STATIC_SCHEMA_TYPE,
+    data: schema,
+    properties: {
+      label,
+      icon,
+      iconHue,
+      role: 'branch',
+      testId: `spacePlugin.schemaNode.${typename}`,
+      selectable: false,
+      draggable: false,
+      droppable: false,
+      childrenDroppable: false,
+      space,
+    },
+  });
+};
+
+/** Builds schema actions (add view, rename, delete, snapshot). */
+const createSchemaActions = ({
+  schema,
+  space,
+  deletable,
+  resolve,
+}: {
+  schema: Type.AnyObj;
+  space: Space;
+  deletable: boolean;
+  resolve: MetadataResolver;
+}) => {
+  const typename = Type.getTypename(schema);
+  const metadata = resolve(typename);
+  const createObjectFn = metadata.createObject;
+  const inputSchema = metadata.inputSchema;
+
+  const actions: Node.NodeArg<Node.ActionData<Operation.Service>>[] = [
+    ...(createObjectFn
+      ? [
+          Node.makeAction({
+            id: SpaceOperation.OpenCreateObject.meta.key,
+            data: Effect.fnUntraced(function* () {
+              if (inputSchema) {
+                yield* Operation.invoke(SpaceOperation.OpenCreateObject, {
+                  target: space.db,
+                  typename,
+                });
+              } else {
+                const result = yield* createObjectFn({}, { db: space.db, target: space.db }) as Effect.Effect<
+                  { subject: readonly string[] },
+                  Error,
+                  never
+                >;
+                if (result.subject.length > 0) {
+                  yield* Operation.invoke(LayoutOperation.Open, {
+                    subject: [...result.subject],
+                    navigation: 'immediate',
+                  });
+                }
+              }
+            }),
+            properties: {
+              label: getDynamicLabel('add object label', typename),
+              icon: 'ph--plus--regular',
+              disposition: 'list-item-primary',
+              testId: 'spacePlugin.createObject',
+            },
+          }),
+        ]
+      : []),
+    Node.makeAction({
+      id: `${SpaceOperation.AddObject.meta.key}-view`,
+      data: () =>
+        Operation.invoke(SpaceOperation.OpenCreateObject, {
+          target: space.db,
+          views: true,
+          initialFormValues: { typename: Type.getTypename(schema) },
+        }),
+      properties: {
+        label: ADD_VIEW_TO_SCHEMA_LABEL,
+        icon: 'ph--circles-three-plus--regular',
+        disposition: 'list-item',
+        testId: 'spacePlugin.addViewToSchema',
+      },
+    }),
+    Node.makeAction({
+      id: SpaceOperation.RenameObject.meta.key,
+      data: (params?: Node.InvokeProps) =>
+        Type.isMutable(schema)
+          ? Operation.invoke(SpaceOperation.RenameObject, {
+              object: (schema as Type.RuntimeType).persistentSchema as any,
+              caller: `${params?.caller}:${params?.parent?.id}`,
+            })
+          : Effect.fail(new Error('Cannot rename immutable schema')),
+      properties: {
+        label: getDynamicLabel('rename object label', Type.getTypename(Type.PersistentType)),
+        icon: 'ph--pencil-simple-line--regular',
+        disabled: !Type.isMutable(schema),
+        disposition: 'list-item',
+        testId: 'spacePlugin.renameObject',
+      },
+    }),
+    Node.makeAction({
+      id: SpaceOperation.RemoveObjects.meta.key,
+      data: () =>
+        Type.isMutable(schema)
+          ? Operation.invoke(SpaceOperation.RemoveObjects, {
+              objects: [(schema as Type.RuntimeType).persistentSchema as Obj.Unknown],
+            })
+          : Effect.succeed(undefined),
+      properties: {
+        label: getDynamicLabel('delete object label', Type.getTypename(Type.PersistentType)),
+        icon: 'ph--trash--regular',
+        disposition: 'list-item',
+        disabled: !deletable,
+        testId: 'spacePlugin.deleteObject',
+      },
+    }),
+    Node.makeAction({
+      id: SpaceOperation.Snapshot.meta.key,
+      data: Effect.fnUntraced(function* () {
+        const result = yield* Operation.invoke(SpaceOperation.Snapshot, {
+          db: space.db,
+          query: Query.select(Filter.type(schema)).ast,
+        });
+        if (result.snapshot) {
+          yield* Effect.tryPromise(() =>
+            downloadBlob(result.snapshot, createFilename({ parts: [space.id, Type.getTypename(schema)], ext: 'json' })),
+          );
+        }
+      }),
+      properties: {
+        label: SNAPSHOT_BY_SCHEMA_LABEL,
+        icon: 'ph--camera--regular',
+        disposition: 'list-item',
+      },
+    }),
+  ];
+
+  return actions;
+};

package/src/capabilities/app-graph-builder/index.ts

@@ -1,5 +1,5 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
 import { Capability } from '@dxos/app-framework';

package/src/capabilities/{app-graph-serializer/app-graph-serializer.ts → app-graph-serializer.ts}

@@ -10,10 +10,12 @@ import { isSpace } from '@dxos/client/echo';
 import { Obj } from '@dxos/echo';
 import { Collection } from '@dxos/echo';
 
-import { meta } from '../../meta';
-import { translations } from '../../translations';
-import { SPACE_TYPE, SpaceOperation } from '../../types';
-import { SPACES } from '../../util';
+import { meta } from '#meta';
+import { SpaceOperation } from '#operations';
+import { translations } from '#translations';
+import { SPACE_TYPE } from '#types';
+
+import { SPACES } from '../util';
 
 const COLLECTION_TYPE = Collection.Collection.typename;
 
@@ -30,8 +32,8 @@ export default Capability.makeModule(
         inputType: SPACES,
         outputType: DIRECTORY_TYPE,
         serialize: (node) => ({
-          name: translations[0]['en-US'][meta.id]['spaces label'] ?? 'Spaces',
-          data: translations[0]['en-US'][meta.id]['spaces label'] ?? 'Spaces',
+          name: translations[0]['en-US'][meta.id]['spaces.label'] ?? 'Spaces',
+          data: translations[0]['en-US'][meta.id]['spaces.label'] ?? 'Spaces',
           type: DIRECTORY_TYPE,
         }),
         deserialize: () => {
@@ -42,8 +44,8 @@ export default Capability.makeModule(
         inputType: SPACE_TYPE,
         outputType: DIRECTORY_TYPE,
         serialize: (node) => ({
-          name: node.data.properties.name ?? translations[0]['en-US'][meta.id]['unnamed space label'],
-          data: node.data.properties.name ?? translations[0]['en-US'][meta.id]['unnamed space label'],
+          name: node.data.properties.name ?? translations[0]['en-US'][meta.id]['unnamed-space.label'],
+          data: node.data.properties.name ?? translations[0]['en-US'][meta.id]['unnamed-space.label'],
           type: DIRECTORY_TYPE,
         }),
         deserialize: async (data) => {
@@ -56,8 +58,8 @@ export default Capability.makeModule(
         inputType: COLLECTION_TYPE,
         outputType: DIRECTORY_TYPE,
         serialize: (node) => ({
-          name: node.data.name ?? translations[0]['en-US'][meta.id]['object name placeholder'],
-          data: node.data.name ?? translations[0]['en-US'][meta.id]['object name placeholder'],
+          name: node.data.name ?? translations[0]['en-US'][meta.id]['object-name.placeholder'],
+          data: node.data.name ?? translations[0]['en-US'][meta.id]['object-name.placeholder'],
           type: DIRECTORY_TYPE,
         }),
         deserialize: async (data, ancestors) => {

package/src/capabilities/identity-created.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { PERSONAL_SPACE_TAG } from '@dxos/app-toolkit';
+import { Obj, Ref } from '@dxos/echo';
+import { Collection } from '@dxos/echo';
+import { Migrations } from '@dxos/migrations';
+import { ClientCapabilities } from '@dxos/plugin-client/types';
+import { EdgeReplicationSetting } from '@dxos/protocols/proto/dxos/echo/metadata';
+import { MembershipPolicy } from '@dxos/protocols/proto/dxos/halo/credentials';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const client = yield* Capability.get(ClientCapabilities.Client);
+
+    const personalSpace = yield* Effect.tryPromise(() =>
+      client.spaces.create({}, { tags: [PERSONAL_SPACE_TAG], membershipPolicy: MembershipPolicy.LOCKED }),
+    );
+    yield* Effect.tryPromise(() => personalSpace.waitUntilReady());
+
+    // Create root collection structure.
+    yield* Effect.tryPromise(() => personalSpace.internal.setEdgeReplicationPreference(EdgeReplicationSetting.ENABLED));
+    Obj.update(personalSpace.properties, (properties) => {
+      properties[Collection.Collection.typename] = Ref.make(Collection.make());
+      if (Migrations.versionProperty) {
+        properties[Migrations.versionProperty] = Migrations.targetVersion;
+      }
+    });
+  }),
+);

package/src/capabilities/index.ts

@@ -2,13 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
+
 export * from './app-graph-builder';
-export * from './app-graph-serializer';
-export * from './identity-created';
-export * from './operation-resolver';
-export * from './react-root';
-export * from './react-surface';
-export * from './repair';
-export * from './settings';
-export * from './spaces-ready';
-export * from './state';
+
+export const AppGraphSerializer = Capability.lazy('AppGraphSerializer', () => import('./app-graph-serializer'));
+export const IdentityCreated = Capability.lazy('IdentityCreated', () => import('./identity-created'));
+export const Migrations = Capability.lazy('SpaceMigrations', () => import('./migrations'));
+export { NavigationHandler } from './navigation-handler';
+export type { NavigationHandlerOptions } from './navigation-handler';
+export const NavigationResolver = Capability.lazy('NavigationResolver', () => import('./navigation-resolver'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactRoot = Capability.lazy('ReactRoot', () => import('./react-root'));
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const Repair = Capability.lazy('Repair', () => import('./repair'));
+export const SpaceSettings = Capability.lazy('SpaceSettings', () => import('./settings'));
+export const SpacesReady = Capability.lazy('SpacesReady', () => import('./spaces-ready'));
+export const SpaceState = Capability.lazy('SpaceState', () => import('./state'));
+export const UndoMappings = Capability.lazy('UndoMappings', () => import('./undo-mappings'));

package/src/capabilities/migrations.ts

@@ -0,0 +1,59 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { LegacySpaceProperties, SpaceProperties } from '@dxos/client-protocol';
+import { defineObjectMigration } from '@dxos/client/echo';
+import { ClientCapabilities } from '@dxos/plugin-client/types';
+import { AccessToken, AnchoredTo, HasConnection, HasRelationship, HasSubject } from '@dxos/types';
+
+const identityTransform = async (from: any) => ({ ...from });
+const noopCallback = async () => {};
+
+const migrations = [
+  defineObjectMigration({
+    from: LegacySpaceProperties,
+    to: SpaceProperties,
+    transform: identityTransform,
+    onMigration: noopCallback,
+  }),
+  defineObjectMigration({
+    from: AccessToken.LegacyAccessToken,
+    to: AccessToken.AccessToken,
+    transform: identityTransform,
+    onMigration: noopCallback,
+  }),
+  defineObjectMigration({
+    from: AnchoredTo.LegacyAnchoredTo,
+    to: AnchoredTo.AnchoredTo,
+    transform: identityTransform,
+    onMigration: noopCallback,
+  }),
+  defineObjectMigration({
+    from: HasConnection.LegacyHasConnection,
+    to: HasConnection.HasConnection,
+    transform: identityTransform,
+    onMigration: noopCallback,
+  }),
+  defineObjectMigration({
+    from: HasRelationship.LegacyHasRelationship,
+    to: HasRelationship.HasRelationship,
+    transform: identityTransform,
+    onMigration: noopCallback,
+  }),
+  defineObjectMigration({
+    from: HasSubject.LegacyHasSubject,
+    to: HasSubject.HasSubject,
+    transform: identityTransform,
+    onMigration: noopCallback,
+  }),
+];
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(ClientCapabilities.Migration, migrations);
+  }),
+);

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

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export type { NavigationHandlerOptions } from './navigation-handler';
+
+export const NavigationHandler = Capability.lazy('NavigationHandler', () => import('./navigation-handler'));

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

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { log } from '@dxos/log';
+
+import { SpaceOperation } from '../../operations';
+
+export type NavigationHandlerOptions = {
+  invitationProp?: string;
+};
+
+/**
+ * NavigationHandler for space invitation URL params.
+ * Handles ?spaceInvitationCode=X → join space via invitation.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* ({ invitationProp = 'spaceInvitationCode' }: NavigationHandlerOptions = {}) {
+    const capabilities = yield* Capability.Service;
+    const operationService = yield* Capability.get(Capabilities.OperationInvoker);
+
+    const handler: AppCapabilities.NavigationHandler = (url: URL) =>
+      Effect.gen(function* () {
+        const invitationCode = url.searchParams.get(invitationProp);
+        if (invitationCode) {
+          log('space invitation received via navigation');
+          removeQueryParam(invitationProp);
+          yield* Operation.invoke(SpaceOperation.Join, { invitationCode });
+        }
+      }).pipe(
+        Effect.provideService(Capability.Service, capabilities),
+        Effect.provideService(Operation.Service, operationService),
+        Effect.orDie,
+      );
+
+    return Capability.contributes(AppCapabilities.NavigationHandler, handler);
+  }),
+);
+
+/** Remove a query param from the current browser URL. */
+const removeQueryParam = (key: string) => {
+  const current = new URL(window.location.href);
+  current.searchParams.delete(key);
+  history.replaceState(null, '', current.pathname + current.search);
+};