@dxos/app-framework 0.8.4-main.ae835ea → 0.8.4-main.bc674ce

package/src/plugin-settings/app-graph-builder.ts

@@ -2,159 +2,139 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Rx } from '@effect-rx/rx-react';
-import * as Function from 'effect/Function';
-import * as Option from 'effect/Option';
+import * as Effect from 'effect/Effect';
 
-import { ROOT_ID, createExtension } from '@dxos/app-graph';
-import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
+import { GraphBuilder, NodeMatcher } from '@dxos/app-graph';
+import { Operation } from '@dxos/operation';
 import { isNonNullable } from '@dxos/util';
 
-import { Capabilities } from '../common';
-import { type PluginContext, type PluginMeta, contributes } from '../core';
-import { createIntent } from '../plugin-intent';
+import * as Common from '../common';
+import { Capability, type Plugin } from '../core';
 
-import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
+import { SETTINGS_ID, SETTINGS_KEY, SettingsOperation } from './actions';
 import { meta } from './meta';
 
-export default (context: PluginContext) =>
-  contributes(Capabilities.AppGraphBuilder, [
-    createExtension({
-      id: `${meta.id}/action`,
-      actions: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: meta.id,
-                data: async () => {
-                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-                  await dispatch(createIntent(SettingsAction.Open));
-                },
-                properties: {
-                  label: ['open settings label', { ns: meta.id }],
-                  icon: 'ph--gear--regular',
-                  disposition: 'menu',
-                  keyBinding: {
-                    macos: 'meta+,',
-                    windows: 'alt+,',
-                  },
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    // Get context for lazy capability access in callbacks.
+    const capabilities = yield* Capability.Service;
+    const managerAtom = capabilities.atom(Common.Capability.PluginManager);
+    const settingsAtom = capabilities.atom(Common.Capability.Settings);
+
+    const extensions = yield* Effect.all([
+      GraphBuilder.createExtension({
+        id: `${meta.id}/action`,
+        match: NodeMatcher.whenRoot,
+        actions: () =>
+          Effect.succeed([
+            {
+              id: meta.id,
+              data: () => Operation.invoke(SettingsOperation.Open, {}),
+              properties: {
+                label: ['open settings label', { ns: meta.id }],
+                icon: 'ph--gear--regular',
+                disposition: 'menu',
+                keyBinding: {
+                  macos: 'meta+,',
+                  windows: 'alt+,',
                 },
               },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${meta.id}/core`,
-      connector: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: SETTINGS_ID,
-                type: meta.id,
+            },
+          ]),
+      }),
+      GraphBuilder.createExtension({
+        id: `${meta.id}/core`,
+        match: NodeMatcher.whenRoot,
+        connector: () =>
+          Effect.succeed([
+            {
+              id: SETTINGS_ID,
+              type: meta.id,
+              properties: {
+                label: ['app settings label', { ns: meta.id }],
+                icon: 'ph--gear--regular',
+                disposition: 'pin-end',
+                position: 'hoist',
+                testId: 'treeView.appSettings',
+              },
+            },
+          ]),
+      }),
+      GraphBuilder.createExtension({
+        id: `${meta.id}/core-plugins`,
+        match: NodeMatcher.whenId(SETTINGS_ID),
+        connector: (node, get) => {
+          const [manager] = get(managerAtom);
+          const allSettings = get(settingsAtom);
+          return Effect.succeed([
+            ...manager
+              .getPlugins()
+              .filter((plugin: Plugin.Plugin) => manager.getCore().includes(plugin.meta.id))
+              .map((plugin: Plugin.Plugin): [Plugin.Meta, Common.Capability.Settings] | null => {
+                const settings = allSettings.find((s) => s.prefix === plugin.meta.id);
+                if (!settings) {
+                  return null;
+                }
+
+                return [plugin.meta, settings];
+              })
+              .filter(isNonNullable)
+              .map(([meta, settings]: [Plugin.Meta, Common.Capability.Settings]) => ({
+                id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
+                type: 'category',
+                data: settings,
                 properties: {
-                  label: ['app settings label', { ns: meta.id }],
-                  icon: 'ph--gear--regular',
-                  disposition: 'pin-end',
-                  position: 'hoist',
-                  testId: 'treeView.appSettings',
+                  label: meta.name ?? meta.id,
+                  icon: meta.icon ?? 'ph--circle--regular',
                 },
-              },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${meta.id}/core-plugins`,
-      connector: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id !== SETTINGS_ID ? Option.none() : Option.some(node))),
-            Option.map(() => {
-              const manager = get(context.capability(Capabilities.PluginManager));
-              const [settingsStore] = get(context.capabilities(Capabilities.SettingsStore));
-              return [
-                ...manager.plugins
-                  .filter((plugin) => manager.core.includes(plugin.meta.id))
-                  .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
-                    const settings = settingsStore?.getStore(plugin.meta.id);
-                    if (!settings) {
-                      return null;
-                    }
+              })),
 
-                    return [plugin.meta, settings];
-                  })
-                  .filter(isNonNullable)
-                  .map(([meta, settings]) => ({
-                    id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
-                    type: 'category',
-                    data: settings,
-                    properties: {
-                      label: meta.name ?? meta.id,
-                      icon: meta.icon ?? 'ph--circle--regular',
-                    },
-                  })),
+            {
+              id: `${SETTINGS_KEY}:custom-plugins`,
+              type: 'category',
+              properties: {
+                label: ['custom plugins label', { ns: meta.id }],
+                icon: 'ph--squares-four--regular',
+                role: 'branch',
+                disposition: 'collection',
+              },
+            },
+          ]);
+        },
+      }),
+      GraphBuilder.createExtension({
+        id: `${meta.id}/custom-plugins`,
+        match: NodeMatcher.whenId(`${SETTINGS_KEY}:custom-plugins`),
+        connector: (node, get) => {
+          const [manager] = get(managerAtom);
+          const allSettings = get(settingsAtom);
+          return Effect.succeed(
+            manager
+              .getPlugins()
+              .filter((plugin: Plugin.Plugin) => !manager.getCore().includes(plugin.meta.id))
+              .map((plugin: Plugin.Plugin): [Plugin.Meta, Common.Capability.Settings] | null => {
+                const settings = allSettings.find((s) => s.prefix === plugin.meta.id);
+                if (!settings) {
+                  return null;
+                }
 
-                {
-                  id: `${SETTINGS_KEY}:custom-plugins`,
-                  type: 'category',
-                  properties: {
-                    label: ['custom plugins label', { ns: meta.id }],
-                    icon: 'ph--squares-four--regular',
-                    role: 'branch',
-                    disposition: 'collection',
-                  },
+                return [plugin.meta, settings];
+              })
+              .filter(isNonNullable)
+              .map(([meta, settings]: [Plugin.Meta, Common.Capability.Settings]) => ({
+                id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
+                type: 'category',
+                data: settings,
+                properties: {
+                  label: meta.name ?? meta.id,
+                  icon: meta.icon ?? 'ph--circle--regular',
                 },
-              ];
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${meta.id}/custom-plugins`,
-      connector: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) =>
-              node.id !== `${SETTINGS_KEY}:custom-plugins` ? Option.none() : Option.some(node),
-            ),
-            Option.map(() => {
-              const manager = get(context.capability(Capabilities.PluginManager));
-              const [settingsStore] = get(context.capabilities(Capabilities.SettingsStore));
-              return manager.plugins
-                .filter((plugin) => !manager.core.includes(plugin.meta.id))
-                .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
-                  const settings = settingsStore?.getStore(plugin.meta.id);
-                  if (!settings) {
-                    return null;
-                  }
+              })),
+          );
+        },
+      }),
+    ]);
 
-                  return [plugin.meta, settings];
-                })
-                .filter(isNonNullable)
-                .map(([meta, settings]) => ({
-                  id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
-                  type: 'category',
-                  data: settings,
-                  properties: {
-                    label: meta.name ?? meta.id,
-                    icon: meta.icon ?? 'ph--circle--regular',
-                  },
-                }));
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-  ]);
+    return Capability.contributes(Common.Capability.AppGraphBuilder, extensions);
+  }),
+);

package/src/plugin-settings/meta.ts

@@ -2,9 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
 
-export const meta: PluginMeta = {
+export const meta: Plugin.Meta = {
   id: 'dxos.org/plugin/settings',
   name: 'Settings',
 };

package/src/plugin-settings/operation-resolver.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { OperationResolver } from '@dxos/operation';
+
+import * as Common from '../common';
+import { Capability } from '../core';
+
+import { SETTINGS_ID, SETTINGS_KEY, SettingsOperation } from './actions';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Common.Capability.OperationResolver, [
+      //
+      // Open Settings
+      //
+      OperationResolver.make({
+        operation: SettingsOperation.Open,
+        handler: (input) =>
+          Effect.gen(function* () {
+            const { invoke } = yield* Capability.get(Common.Capability.OperationInvoker);
+            yield* invoke(Common.LayoutOperation.SwitchWorkspace, { subject: SETTINGS_ID });
+            if (input.plugin) {
+              // Fire and forget the open operation.
+              yield* Effect.fork(
+                invoke(Common.LayoutOperation.Open, {
+                  subject: [`${SETTINGS_KEY}:${input.plugin.replaceAll('/', ':')}`],
+                }),
+              );
+            }
+          }),
+      }),
+
+      //
+      // Open Plugin Registry
+      //
+      OperationResolver.make({
+        operation: SettingsOperation.OpenPluginRegistry,
+        handler: () =>
+          Effect.gen(function* () {
+            const { invoke } = yield* Capability.get(Common.Capability.OperationInvoker);
+            yield* invoke(Common.LayoutOperation.SwitchWorkspace, { subject: SETTINGS_ID });
+            yield* Effect.fork(
+              invoke(Common.LayoutOperation.Open, {
+                subject: [`${SETTINGS_KEY}:plugins`],
+              }),
+            );
+          }),
+      }),
+    ]);
+  }),
+);

package/src/plugin-settings/translations.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Resource } from '@dxos/react-ui';
+import { type Resource } from '../common';
 
 import { meta } from './meta';
 

package/src/react/App.stories.tsx

@@ -0,0 +1,63 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+
+import * as Common from '../common';
+import { Capability, Plugin } from '../core';
+
+import { useApp } from './useApp';
+
+// Minimal plugin that contributes a ReactRoot.
+const TestPlugin = Plugin.define({
+  id: 'dxos.org/plugin/test',
+  name: 'Test Plugin',
+}).pipe(
+  Plugin.addModule({
+    id: 'TestMain',
+    activatesOn: Common.ActivationEvent.Startup,
+    activate: () =>
+      Effect.succeed([
+        Capability.contributes(Common.Capability.ReactRoot, {
+          id: 'dxos.org/plugin/test/root',
+          root: () => (
+            <div className='fixed inset-0 flex items-center justify-center text-2xl'>App Started Successfully!</div>
+          ),
+        }),
+      ]),
+  }),
+  Plugin.make,
+);
+
+const plugins = [TestPlugin()];
+const core = [TestPlugin.meta.id];
+
+const DefaultStory = () => {
+  const App = useApp({
+    plugins,
+    core,
+    placeholder: () => <div className='fixed inset-0 flex items-center justify-center'>Loading...</div>,
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/App',
+  render: DefaultStory,
+  decorators: [withTheme],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/{components → react}/App.tsx

@@ -4,25 +4,26 @@
 
 import React, { type PropsWithChildren } from 'react';
 
-import { Capabilities } from '../common';
+import * as Common from '../common';
 import { topologicalSort } from '../helpers';
-import { useCapabilities } from '../react';
 
 import { type UseAppOptions } from './useApp';
+import { useCapabilities } from './useCapabilities';
 import { LoadingState, useLoading } from './useLoading';
 
 export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
-  state: { ready: boolean; error: unknown };
+  ready: boolean;
+  error: unknown;
 };
 
-export const App = ({ placeholder: Placeholder, state, debounce }: AppProps) => {
-  const reactContexts = useCapabilities(Capabilities.ReactContext);
-  const reactRoots = useCapabilities(Capabilities.ReactRoot);
-  const stage = useLoading(state, debounce);
+export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppProps) => {
+  const reactContexts = useCapabilities(Common.Capability.ReactContext);
+  const reactRoots = useCapabilities(Common.Capability.ReactRoot);
+  const stage = useLoading(ready, debounce);
 
-  if (state.error) {
+  if (error) {
     // This triggers the error boundary to provide UI feedback for the startup error.
-    throw state.error;
+    throw error;
   }
 
   // TODO(wittjosiah): Consider using Suspense instead.
@@ -44,7 +45,7 @@ export const App = ({ placeholder: Placeholder, state, debounce }: AppProps) =>
   );
 };
 
-const composeContexts = (contexts: Capabilities.ReactContext[]) => {
+const composeContexts = (contexts: Common.Capability.ReactContext[]) => {
   if (contexts.length === 0) {
     return ({ children }: PropsWithChildren) => <>{children}</>;
   }

package/src/{components → react}/DefaultFallback.tsx

@@ -19,7 +19,7 @@ export const DefaultFallback = ({ error }: { error: Error }) => {
       }}
     >
       {/* TODO(wittjosiah): Link to docs for replacing default. */}
-      <h1 style={{ margin: '0.5rem 0', fontSize: '1.2rem' }}>[ERROR]: {error.message}</h1>
+      <h1 style={{ margin: '0.5rem 0', fontSize: '1.2rem' }}>ERROR: {error.message}</h1>
       <pre style={{ overflow: 'auto', fontSize: '1rem', whiteSpace: 'pre-wrap', color: '#888888' }}>{error.stack}</pre>
     </div>
   );

package/src/react/PluginManagerContext.stories.tsx

@@ -0,0 +1,184 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, useAtomValue } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useEffect, useMemo, useState } from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+import { useWebComponentContext } from '@dxos/web-context-react';
+
+import * as Common from '../common';
+import { PluginManagerContext } from '../context';
+import { Capability, Plugin } from '../core';
+
+import { useApp } from './useApp';
+
+// Define the Counter capability
+const Counter = Capability.make<{ count: number; increment: () => void }>('example/counter');
+
+const CountStatus = () => {
+  const manager = useWebComponentContext(PluginManagerContext);
+  const capabilitiesAtom = useMemo(
+    () => manager?.capabilities.atom(Counter) ?? Atom.make<{ count: number; increment: () => void }[]>([]),
+    [manager],
+  );
+  const capabilities = useAtomValue(capabilitiesAtom);
+  const counter = (capabilities as any)[0];
+  const [count, setCount] = useState(counter?.count ?? 0);
+
+  useEffect(() => {
+    if (!counter) {
+      return;
+    }
+    setCount(counter.count);
+    if ('subscribe' in counter && typeof counter.subscribe === 'function') {
+      return counter.subscribe(() => setCount(counter.count));
+    }
+  }, [counter]);
+
+  if (!manager) return null;
+
+  const isEven = count % 2 === 0;
+
+  return (
+    <div
+      className={`mt-4 px-4 py-2 rounded-full text-sm font-medium transition-colors ${
+        isEven
+          ? 'bg-emerald-100 text-emerald-800 dark:bg-emerald-900/30 dark:text-emerald-400'
+          : 'bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-400'
+      }`}
+    >
+      Status: {isEven ? 'Even' : 'Odd'}
+    </div>
+  );
+};
+
+// A component that consumes the PluginManager via web context
+const CounterComponent = () => {
+  // Use the web-context hook to get the PluginManager
+  const manager = useWebComponentContext(PluginManagerContext);
+  const capabilitiesAtom = useMemo(
+    () => manager?.capabilities.atom(Counter) ?? Atom.make<{ count: number; increment: () => void }[]>([]),
+    [manager],
+  );
+  const capabilities = useAtomValue(capabilitiesAtom);
+  const counter = (capabilities as any)[0];
+  const [count, setCount] = useState(counter?.count ?? 0);
+
+  useEffect(() => {
+    if (!counter) {
+      return;
+    }
+    setCount(counter.count);
+    if ('subscribe' in counter && typeof counter.subscribe === 'function') {
+      return counter.subscribe(() => setCount(counter.count));
+    }
+  }, [counter]);
+
+  if (!manager) {
+    return <div className='p-4 text-red-500'>Error: Context not found</div>;
+  }
+
+  return (
+    <div className='flex flex-col items-center justify-center h-screen bg-neutral-100 dark:bg-neutral-900 text-neutral-900 dark:text-white'>
+      <div className='p-8 bg-white dark:bg-neutral-800 rounded-lg shadow-xl border border-neutral-200 dark:border-neutral-700 max-w-md w-full'>
+        <h2 className='text-2xl font-bold mb-6 text-center text-primary-600 dark:text-primary-400'>
+          Web Context Counter
+        </h2>
+
+        <div className='flex flex-col items-center gap-6'>
+          <div className='text-6xl font-mono font-bold tabular-nums tracking-tighter'>{count}</div>
+
+          <button
+            className='px-6 py-3 bg-primary-600 hover:bg-primary-700 text-white font-semibold rounded-full transition-colors shadow-md active:transform active:scale-95'
+            onClick={() => {
+              const counter = manager.capabilities.get(Counter);
+              counter.increment();
+            }}
+          >
+            Increment
+          </button>
+
+          <CountStatus />
+        </div>
+
+        <div className='mt-8 pt-4 border-bs border-neutral-200 dark:border-neutral-700 text-center'>
+          <p className='text-sm text-neutral-500 dark:text-neutral-400'>
+            This component accesses the <code>PluginManager</code> via <code>useWebComponentContext</code>.
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+// Plugin that provides the Counter capability and renders the UI
+const CounterPlugin = Plugin.define({
+  id: 'dxos.org/plugin/counter',
+  name: 'Counter Plugin',
+}).pipe(
+  Plugin.addModule({
+    id: 'CounterMain',
+    activatesOn: Common.ActivationEvent.Startup,
+    activate: () => {
+      const listeners = new Set<() => void>();
+      const counter = {
+        count: 0,
+        increment: () => {
+          counter.count++;
+          listeners.forEach((listener) => listener());
+        },
+        subscribe: (listener: () => void) => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+      };
+
+      return Effect.succeed([
+        // Contribute the state/logic
+        Capability.contributes(Counter, counter),
+
+        // Contribute the UI
+        Capability.contributes(Common.Capability.ReactRoot, {
+          id: 'dxos.org/plugin/counter/root',
+          root: CounterComponent,
+        }),
+      ]);
+    },
+  }),
+  Plugin.make,
+)();
+
+const plugins = [CounterPlugin];
+const core = ['dxos.org/plugin/counter'];
+const placeholder = () => (
+  <div className='flex h-screen items-center justify-center p-4 text-lg text-neutral-500'>
+    Initializing Application...
+  </div>
+);
+
+const DefaultStory = () => {
+  const App = useApp({
+    plugins,
+    core,
+    placeholder,
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/PluginManagerContext',
+  render: DefaultStory,
+  decorators: [withTheme],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+
+export const Default: StoryObj<typeof meta> = {};

package/src/react/PluginManagerProvider.ts

@@ -8,12 +8,12 @@ import { raise } from '@dxos/debug';
 
 import { type PluginManager } from '../core';
 
-const PluginManagerContext = createContext<PluginManager | undefined>(undefined);
+const PluginManagerContext = createContext<PluginManager.PluginManager | undefined>(undefined);
 
 /**
  * Get the plugin manager.
  */
-export const usePluginManager = (): PluginManager =>
+export const usePluginManager = (): PluginManager.PluginManager =>
   useContext(PluginManagerContext) ?? raise(new Error('Missing PluginManagerContext'));
 
 /**