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

package/src/plugin-operation/invoker-capability.ts

@@ -6,7 +6,7 @@ import * as Effect from 'effect/Effect';
 
 import { OperationInvoker } from '@dxos/operation';
 
-import * as Common from '../common';
+import { ActivationEvents, Capabilities } from '../common';
 import { Capability, Plugin } from '../core';
 
 //
@@ -20,14 +20,14 @@ export default Capability.makeModule(
     const pluginManager = yield* Plugin.Service;
 
     // Get the ManagedRuntime capability (should be available since we activate after ManagedRuntimeReady).
-    const managedRuntimes = yield* Capability.getAll(Common.Capability.ManagedRuntime);
+    const managedRuntimes = yield* Capability.getAll(Capabilities.ManagedRuntime);
     const managedRuntime = managedRuntimes.length > 0 ? managedRuntimes[0] : undefined;
 
     const invoker = OperationInvoker.make(
       () =>
         Effect.gen(function* () {
-          yield* Plugin.activate(Common.ActivationEvent.SetupOperationResolver);
-          return (yield* Capability.getAll(Common.Capability.OperationResolver)).flat();
+          yield* Plugin.activate(ActivationEvents.SetupOperationResolver);
+          return (yield* Capability.getAll(Capabilities.OperationResolver)).flat();
         }).pipe(
           Effect.provideService(Capability.Service, capabilityManager),
           Effect.provideService(Plugin.Service, pluginManager),
@@ -35,6 +35,6 @@ export default Capability.makeModule(
       managedRuntime,
     );
 
-    return Capability.contributes(Common.Capability.OperationInvoker, invoker);
+    return Capability.contributes(Capabilities.OperationInvoker, invoker);
   }),
 );

package/src/plugin-operation/meta.ts

@@ -5,7 +5,7 @@
 import { type Plugin } from '../core';
 
 export const meta: Plugin.Meta = {
-  id: 'dxos.org/plugin/operation',
+  id: 'org.dxos.plugin.operation',
   name: 'Operation Plugin',
   description: 'Provides operation invocation, undo registry, and history tracking.',
 };

package/src/plugin-runtime/RuntimePlugin.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Common from '../common';
+import { ActivationEvents } from '../common';
 import { Capability, Plugin } from '../core';
 
 import { meta } from './meta';
@@ -11,9 +11,9 @@ const ManagedRuntimeCapability = Capability.lazy('ManagedRuntime', () => import(
 
 export const RuntimePlugin = Plugin.define(meta).pipe(
   Plugin.addModule({
-    activatesOn: Common.ActivationEvent.Startup,
-    activatesBefore: [Common.ActivationEvent.SetupLayer],
-    activatesAfter: [Common.ActivationEvent.ManagedRuntimeReady],
+    activatesOn: ActivationEvents.Startup,
+    activatesBefore: [ActivationEvents.SetupLayer],
+    activatesAfter: [ActivationEvents.ManagedRuntimeReady],
     activate: ManagedRuntimeCapability,
   }),
   Plugin.make,

package/src/plugin-runtime/capability.ts

@@ -6,7 +6,7 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as ManagedRuntime from 'effect/ManagedRuntime';
 
-import * as Common from '../common';
+import { ActivationEvents, Capabilities } from '../common';
 import { Capability, Plugin } from '../core';
 
 //
@@ -22,10 +22,10 @@ export default Capability.makeModule(
     const pluginManager = yield* Plugin.Service;
 
     // Trigger setup event so plugins can contribute their layers.
-    yield* Plugin.activate(Common.ActivationEvent.SetupLayer);
+    yield* Plugin.activate(ActivationEvents.SetupLayer);
 
     // Gather all contributed layers.
-    const layers = yield* Capability.getAll(Common.Capability.Layer);
+    const layers = yield* Capability.getAll(Capabilities.Layer);
 
     // Create layers that provide Capability.Service and Plugin.Service.
     const capabilityServiceLayer = Layer.succeed(Capability.Service, capabilityManager);
@@ -46,8 +46,8 @@ export default Capability.makeModule(
           );
 
     // Create the managed runtime from the composed layer.
-    const runtime = ManagedRuntime.make(composedLayer) as Common.Capability.ManagedRuntime;
+    const runtime = ManagedRuntime.make(composedLayer) as Capabilities.ManagedRuntime;
 
-    return Capability.contributes(Common.Capability.ManagedRuntime, runtime);
+    return Capability.contributes(Capabilities.ManagedRuntime, runtime);
   }),
 );

package/src/plugin-runtime/meta.ts

@@ -5,7 +5,7 @@
 import { type Plugin } from '../core';
 
 export const meta: Plugin.Meta = {
-  id: 'dxos.org/plugin/runtime',
+  id: 'org.dxos.plugin.runtime',
   name: 'Runtime Plugin',
   description: 'Provides a managed Effect runtime by composing contributed layers.',
 };

package/src/testing/service.ts

@@ -7,7 +7,7 @@ import * as Layer from 'effect/Layer';
 
 import { invariant } from '@dxos/invariant';
 
-import * as Common from '../common';
+import { ActivationEvents, Capabilities } from '../common';
 import { Plugin, PluginManager } from '../core';
 
 /**
@@ -34,18 +34,18 @@ export const fromPlugins = (plugins: Plugin.Plugin[]) =>
       });
 
       manager.capabilities.contribute({
-        interface: Common.Capability.PluginManager,
+        interface: Capabilities.PluginManager,
         implementation: manager,
-        module: 'dxos.org/app-framework/plugin-manager',
+        module: 'org.dxos.app-framework.plugin-manager',
       });
 
       manager.capabilities.contribute({
-        interface: Common.Capability.AtomRegistry,
+        interface: Capabilities.AtomRegistry,
         implementation: manager.registry,
-        module: 'dxos.org/app-framework/atom-registry',
+        module: 'org.dxos.app-framework.atom-registry',
       });
 
-      yield* manager.activate(Common.ActivationEvent.Startup);
+      yield* manager.activate(ActivationEvents.Startup);
 
       return manager;
     }),

package/src/testing/withPluginManager.stories.tsx

@@ -7,9 +7,9 @@ import React from 'react';
 
 import { withTheme } from '@dxos/react-ui/testing';
 
-import * as Common from '../common';
+import { Capabilities } from '../common';
 import { Capability } from '../core';
-import { Surface } from '../react';
+import { Surface } from '../ui';
 
 import { withPluginManager } from './withPluginManager';
 
@@ -18,7 +18,7 @@ const DefaultStory = () => {
   return (
     <div>
       <div>Hello</div>
-      <Surface role='main' />
+      <Surface.Surface role='main' />
     </div>
   );
 };
@@ -27,12 +27,12 @@ const meta = {
   title: 'sdk/app-framework/withPluginManager',
   render: DefaultStory,
   decorators: [
-    withTheme,
+    withTheme(),
     withPluginManager({
       capabilities: [
         Capability.contributes(
-          Common.Capability.ReactSurface,
-          Common.createSurface({
+          Capabilities.ReactSurface,
+          Surface.create({
             id: 'test',
             role: 'main',
             component: ({ role }) => <span>{JSON.stringify({ role })}</span>,

package/src/testing/withPluginManager.tsx

@@ -4,15 +4,16 @@
 
 import { type Decorator, type StoryContext } from '@storybook/react';
 import * as Effect from 'effect/Effect';
-import React, { useEffect, useMemo } from 'react';
+import React, { useEffect, useState } from 'react';
 
 import { raise } from '@dxos/debug';
+import { runAndForwardErrors } from '@dxos/effect';
 import { useAsyncEffect } from '@dxos/react-hooks';
 import { type MaybeProvider, getProviderValue } from '@dxos/util';
 
-import * as Common from '../common';
+import { ActivationEvents, Capabilities } from '../common';
 import { type ActivationEvent, Capability, type CapabilityManager, Plugin, PluginManager } from '../core';
-import { type UseAppOptions, useApp } from '../react';
+import { type UseAppOptions, useApp } from '../ui';
 
 /**
  * @internal
@@ -43,6 +44,13 @@ export const setupPluginManager = ({
   return pluginManager;
 };
 
+type ManagedPluginManagerState = {
+  fireEvents?: (ActivationEvent.ActivationEvent | string)[];
+  pluginManager: PluginManager.PluginManager;
+  setupEvents?: ActivationEvent.ActivationEvent[];
+  storyId: string;
+};
+
 export type WithPluginManagerOptions = UseAppOptions & {
   /** @deprecated */
   capabilities?: MaybeProvider<Capability.Any[], CapabilityManager.CapabilityManager>;
@@ -60,40 +68,59 @@ export type WithPluginManagerInitializer<Args = void> =
  */
 export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args> = {}): Decorator => {
   return (Story, context) => {
+    const storyId = context.id;
     const options = typeof init === 'function' ? init(context as any) : init;
-    const pluginManager = useMemo(() => setupPluginManager(options), [init]);
+    const [managerState, setManagerState] = useState<ManagedPluginManagerState>();
 
-    // Set-up root capability.
+    // Storybook replaces the full context object often, so key manager ownership by story id.
     useEffect(() => {
-      const capability = Capability.contributes(Common.Capability.ReactRoot, {
-        id: context.id,
+      const pluginManager = setupPluginManager(options);
+
+      const capability = Capability.contributes(Capabilities.ReactRoot, {
+        id: storyId,
         root: () => <Story />,
       });
 
       pluginManager.capabilities.contribute({
         ...capability,
-        module: 'dxos.org/app-framework/withPluginManager',
+        module: 'org.dxos.app-framework.with-plugin-manager',
+      });
+
+      setManagerState({
+        pluginManager,
+        setupEvents: options.setupEvents,
+        fireEvents: options.fireEvents,
+        storyId,
       });
 
       return () => {
         pluginManager.capabilities.remove(capability.interface, capability.implementation);
+        void runAndForwardErrors(pluginManager.shutdown());
       };
-    }, [pluginManager, context]);
+    }, [storyId, init]);
 
-    // Fire events.
-    useAsyncEffect(async () => {
-      await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
-    }, [pluginManager]);
+    // Avoid mounting useApp with a stale manager from the previous story.
+    if (!managerState || managerState.storyId !== storyId) {
+      return <></>;
+    }
 
-    // Create app.
-    const App = useApp({ pluginManager });
-
-    return <App />;
+    return <WithPluginManagerApp {...managerState} />;
   };
 };
 
+const WithPluginManagerApp = ({ fireEvents, pluginManager, setupEvents, storyId }: ManagedPluginManagerState) => {
+  // Fire deprecated events only after the effect-owned manager for this story exists.
+  useAsyncEffect(async () => {
+    await Promise.all(fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
+  }, [fireEvents, pluginManager, storyId]);
+
+  const App = useApp({ pluginManager, setupEvents });
+
+  return <App />;
+};
+
 const storyMeta = {
-  id: 'dxos.org/app-framework/story',
+  id: 'org.dxos.app-framework.story',
   name: 'Story',
 };
 
@@ -102,7 +129,7 @@ const storyMeta = {
 const StoryPlugin = Plugin.define(storyMeta).pipe(
   Plugin.addModule({
     id: 'Story',
-    activatesOn: Common.ActivationEvent.Startup,
+    activatesOn: ActivationEvents.Startup,
     activate: () => Effect.succeed([]),
   }),
   Plugin.make,

package/src/ui/components/App/App.stories.tsx

@@ -0,0 +1,92 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useEffect } from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { ActivationEvents, Capabilities } from '../../../common';
+import { Capability, Plugin } from '../../../core';
+import { useApp } from '../../hooks';
+
+// Minimal plugin that contributes a ReactRoot.
+const TestPlugin = Plugin.define<{ error?: boolean }>({
+  id: 'org.dxos.plugin.test',
+  name: 'Test Plugin',
+}).pipe(
+  Plugin.addModule(({ error }) => ({
+    id: 'TestMain',
+    activatesOn: ActivationEvents.Startup,
+    activate: () =>
+      Effect.succeed([
+        Capability.contributes(Capabilities.ReactRoot, {
+          id: 'org.dxos.plugin.test.root',
+          root: () => {
+            useEffect(() => {
+              let t: NodeJS.Timeout;
+              if (error) {
+                console.log('Ticking...');
+                t = setTimeout(() => {
+                  console.log('Bang!');
+                  throw new Error('Runtime error');
+                }, 3_000);
+              }
+
+              return () => clearTimeout(t);
+            }, [error]);
+
+            return <h1 className='text-lg'>App Started</h1>;
+          },
+        }),
+      ]),
+  })),
+  Plugin.make,
+);
+
+const core = [TestPlugin.meta.id];
+
+type StoryProps = { plugins?: Plugin.Plugin[] };
+
+const DefaultStory = ({ plugins }: StoryProps) => {
+  const App = useApp({
+    plugins,
+    core,
+    placeholder: () => {
+      return (
+        <div role='none' className='text-description'>
+          Loading...
+        </div>
+      );
+    },
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/App',
+  render: DefaultStory,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    plugins: [TestPlugin({})],
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    plugins: [TestPlugin({ error: true })],
+  },
+};

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

@@ -4,12 +4,9 @@
 
 import React, { type PropsWithChildren } from 'react';
 
-import * as Common from '../common';
-import { topologicalSort } from '../helpers';
-
-import { type UseAppOptions } from './useApp';
-import { useCapabilities } from './useCapabilities';
-import { LoadingState, useLoading } from './useLoading';
+import { Capabilities } from '../../../common';
+import { topologicalSort } from '../../../helpers';
+import { LoadingState, type UseAppOptions, useCapabilities, useLoading } from '../../hooks';
 
 export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
   ready: boolean;
@@ -17,8 +14,8 @@ export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
 };
 
 export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppProps) => {
-  const reactContexts = useCapabilities(Common.Capability.ReactContext);
-  const reactRoots = useCapabilities(Common.Capability.ReactRoot);
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
   const stage = useLoading(ready, debounce);
 
   if (error) {
@@ -45,7 +42,7 @@ export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppPro
   );
 };
 
-const composeContexts = (contexts: Common.Capability.ReactContext[]) => {
+const composeContexts = (contexts: Capabilities.ReactContext[]) => {
   if (contexts.length === 0) {
     return ({ children }: PropsWithChildren) => <>{children}</>;
   }

package/src/{playground/layout → ui/components/App}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './plugin';
+export * from './App';

package/src/{react → ui/components/PluginManager}/PluginManagerContext.stories.tsx

@@ -7,14 +7,13 @@ 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 { withLayout, 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';
+import { ActivationEvents, Capabilities } from '../../../common';
+import { PluginManagerContext } from '../../../context';
+import { Capability, Plugin } from '../../../core';
+import { useApp } from '../../hooks';
 
 // Define the Counter capability
 const Counter = Capability.make<{ count: number; increment: () => void }>('example/counter');
@@ -79,7 +78,7 @@ const CounterComponent = () => {
   }, [counter]);
 
   if (!manager) {
-    return <div className='p-4 text-red-500'>Error: Context not found</div>;
+    return <div className='p-4 text-error-text'>Error: Context not found</div>;
   }
 
   return (
@@ -105,7 +104,7 @@ const CounterComponent = () => {
           <CountStatus />
         </div>
 
-        <div className='mt-8 pt-4 border-bs border-neutral-200 dark:border-neutral-700 text-center'>
+        <div className='mt-8 pt-4 border-t 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>
@@ -117,12 +116,12 @@ const CounterComponent = () => {
 
 // Plugin that provides the Counter capability and renders the UI
 const CounterPlugin = Plugin.define({
-  id: 'dxos.org/plugin/counter',
+  id: 'org.dxos.plugin.counter',
   name: 'Counter Plugin',
 }).pipe(
   Plugin.addModule({
     id: 'CounterMain',
-    activatesOn: Common.ActivationEvent.Startup,
+    activatesOn: ActivationEvents.Startup,
     activate: () => {
       const listeners = new Set<() => void>();
       const counter = {
@@ -142,8 +141,8 @@ const CounterPlugin = Plugin.define({
         Capability.contributes(Counter, counter),
 
         // Contribute the UI
-        Capability.contributes(Common.Capability.ReactRoot, {
-          id: 'dxos.org/plugin/counter/root',
+        Capability.contributes(Capabilities.ReactRoot, {
+          id: 'org.dxos.plugin.counter.root',
           root: CounterComponent,
         }),
       ]);
@@ -153,7 +152,7 @@ const CounterPlugin = Plugin.define({
 )();
 
 const plugins = [CounterPlugin];
-const core = ['dxos.org/plugin/counter'];
+const core = ['org.dxos.plugin.counter'];
 const placeholder = () => (
   <div className='flex h-screen items-center justify-center p-4 text-lg text-neutral-500'>
     Initializing Application...
@@ -173,7 +172,7 @@ const DefaultStory = () => {
 const meta = {
   title: 'sdk/app-framework/PluginManagerContext',
   render: DefaultStory,
-  decorators: [withTheme],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
   parameters: {
     layout: 'fullscreen',
   },

package/src/{react → ui/components/PluginManager}/PluginManagerProvider.ts

@@ -6,7 +6,7 @@ import { createContext, useContext } from 'react';
 
 import { raise } from '@dxos/debug';
 
-import { type PluginManager } from '../core';
+import { type PluginManager } from '../../../core';
 
 const PluginManagerContext = createContext<PluginManager.PluginManager | undefined>(undefined);
 

package/src/ui/components/PluginManager/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './PluginManagerProvider';

package/src/{react/Surface.stories.tsx → ui/components/Surface/SurfaceComponent.stories.tsx}

@@ -7,14 +7,15 @@ import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'rea
 
 import { faker } from '@dxos/random';
 import { List, ListItem, Toolbar } from '@dxos/react-ui';
-import { withTheme } from '@dxos/react-ui/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ColorStyles, getHashStyles, mx } from '@dxos/ui-theme';
 
-import * as Common from '../common';
-import { withPluginManager } from '../testing';
+import { Capabilities } from '../../../common';
+import { withPluginManager } from '../../../testing';
+import { usePluginManager } from '../PluginManager';
 
-import { usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
+import { SurfaceComponent, useSurfaces } from './SurfaceComponent';
+import { create } from './types';
 
 type TestComponentProps = {
   id: string;
@@ -24,7 +25,7 @@ type TestComponentProps = {
 const TestComponent = forwardRef<HTMLDivElement, TestComponentProps>(({ styles, id }, forwardedRef) => {
   return (
     <div
-      className={mx('flex justify-center items-center border rounded', styles.surface, styles.border)}
+      className={mx('flex justify-center items-center border rounded-sm', styles.surface, styles.border)}
       ref={forwardedRef}
     >
       <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
@@ -40,10 +41,11 @@ const DefaultStory = () => {
   const handleAdd = useCallback(() => {
     const id = `test-${faker.number.int({ min: 0, max: 1_000 })}`;
     const styles = getHashStyles(id);
+
     manager.capabilities.contribute({
       module: 'test',
-      interface: Common.Capability.ReactSurface,
-      implementation: Common.createSurface({
+      interface: Capabilities.ReactSurface,
+      implementation: create({
         id,
         role: 'item',
         filter: (data): data is any => (data as any)?.id === id,
@@ -61,8 +63,8 @@ const DefaultStory = () => {
   const handleError = useCallback(() => {
     manager.capabilities.contribute({
       module: 'error',
-      interface: Common.Capability.ReactSurface,
-      implementation: Common.createSurface({
+      interface: Capabilities.ReactSurface,
+      implementation: create({
         id: 'error',
         role: 'item',
         filter: (data): data is any => (data as any)?.id === 'error',
@@ -86,7 +88,7 @@ const DefaultStory = () => {
           }
 
           return (
-            <div className='flex justify-center items-center border border-roseFill rounded'>
+            <div className='flex justify-center items-center border border-rose-fill rounded-sm'>
               <span className='font-mono'>Ticking... {count}</span>
             </div>
           );
@@ -103,15 +105,15 @@ const DefaultStory = () => {
   }, [ref]);
 
   return (
-    <div className='flex flex-col bs-full overflow-hidden'>
+    <div className='flex flex-col h-full overflow-hidden'>
       <Toolbar.Root>
         <Toolbar.Button onClick={handleAdd}>Add</Toolbar.Button>
         <Toolbar.Button onClick={handleSelect}>Pick</Toolbar.Button>
         <Toolbar.Button onClick={handleError}>Error</Toolbar.Button>
       </Toolbar.Root>
-      <div className='grid grid-cols-2 bs-full gap-4 overflow-hidden'>
-        <Surface role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
-        <div className='overflow-y-auto bs-full'>
+      <div className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
+        <SurfaceComponent role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
+        <div className='overflow-y-auto h-full'>
           <List>
             {surfaces.map((surface) => (
               <ListItem.Root key={surface.id} id={surface.id}>
@@ -128,7 +130,7 @@ const DefaultStory = () => {
 const meta = {
   title: 'sdk/app-framework/Surface',
   render: DefaultStory,
-  decorators: [withTheme, withPluginManager({ capabilities: [] })],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withPluginManager({ capabilities: [] })],
   parameters: {
     layout: 'fullscreen',
   },