@dxos/app-framework 0.8.4-main.937b3ca → 0.8.4-main.9be5663bfe

package/src/plugin-operation/testing.ts

@@ -9,49 +9,39 @@ import * as Ref from 'effect/Ref';
 import * as Schema from 'effect/Schema';
 import * as Stream from 'effect/Stream';
 
-import { Operation, type OperationInvoker, OperationResolver } from '@dxos/operation';
+import { Operation, type OperationInvoker } from '@dxos/operation';
 
 //
 // Test Operations
 //
 
 export const Compute = Operation.make({
-  schema: {
-    input: Schema.Struct({ value: Schema.Number }),
-    output: Schema.Struct({ value: Schema.Number }),
-  },
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
   meta: { key: 'test.compute' },
 });
 
 export const HalveCompute = Operation.make({
-  schema: {
-    input: Schema.Struct({ value: Schema.Number }),
-    output: Schema.Struct({ value: Schema.Number }),
-  },
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
   meta: { key: 'test.halve-compute' },
 });
 
 export const ToString = Operation.make({
-  schema: {
-    input: Schema.Struct({ value: Schema.Number }),
-    output: Schema.Struct({ string: Schema.String }),
-  },
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ string: Schema.String }),
   meta: { key: 'test.to-string' },
 });
 
 export const Add = Operation.make({
-  schema: {
-    input: Schema.Tuple(Schema.Number, Schema.Number),
-    output: Schema.Number,
-  },
+  input: Schema.Tuple(Schema.Number, Schema.Number),
+  output: Schema.Number,
   meta: { key: 'test.add' },
 });
 
 export const SideEffect = Operation.make({
-  schema: {
-    input: Schema.Void,
-    output: Schema.Void,
-  },
+  input: Schema.Void,
+  output: Schema.Void,
   meta: { key: 'test.side-effect' },
 });
 
@@ -59,34 +49,24 @@ export const SideEffect = Operation.make({
 // Test Handlers
 //
 
-export const computeHandler = OperationResolver.make({
-  operation: Compute,
-  handler: (data) =>
-    Effect.gen(function* () {
-      yield* Effect.sleep(data.value * 10);
-      return { value: data.value * 2 };
-    }),
-});
+export const computeHandler = Operation.withHandler(Compute, (data) =>
+  Effect.gen(function* () {
+    yield* Effect.sleep(data.value * 10);
+    return { value: data.value * 2 };
+  }),
+);
 
-export const halveComputeHandler = OperationResolver.make({
-  operation: HalveCompute,
-  handler: (data) => Effect.succeed({ value: data.value / 2 }),
-});
+export const halveComputeHandler = Operation.withHandler(HalveCompute, (data) =>
+  Effect.succeed({ value: data.value / 2 }),
+);
 
-export const toStringHandler = OperationResolver.make({
-  operation: ToString,
-  handler: (data) => Effect.succeed({ string: data.value.toString() }),
-});
+export const toStringHandler = Operation.withHandler(ToString, (data) =>
+  Effect.succeed({ string: data.value.toString() }),
+);
 
-export const addHandler = OperationResolver.make({
-  operation: Add,
-  handler: (data) => Effect.succeed(data[0] + data[1]),
-});
+export const addHandler = Operation.withHandler(Add, (data) => Effect.succeed(data[0] + data[1]));
 
-export const sideEffectHandler = OperationResolver.make({
-  operation: SideEffect,
-  handler: () => Effect.succeed(undefined),
-});
+export const sideEffectHandler = Operation.withHandler(SideEffect, () => Effect.succeed(undefined));
 
 //
 // Test Utilities

package/src/plugin-runtime/RuntimePlugin.ts

@@ -2,18 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Common from '../common';
+import { ActivationEvents } from '../common';
 import { Capability, Plugin } from '../core';
-
 import { meta } from './meta';
 
 const ManagedRuntimeCapability = Capability.lazy('ManagedRuntime', () => import('./capability'));
 
 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,10 +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';
 
 const DefaultStory = () => {
@@ -18,7 +17,7 @@ const DefaultStory = () => {
   return (
     <div>
       <div>Hello</div>
-      <Surface role='main' />
+      <Surface.Surface role='main' />
     </div>
   );
 };
@@ -27,12 +26,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,57 @@ 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 +127,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 DefaultStoryProps = { plugins?: Plugin.Plugin[] };
+
+const DefaultStory = ({ plugins }: DefaultStoryProps) => {
+  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,21 +4,19 @@
 
 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 StartupProgress, type UseAppOptions, useCapabilities, useLoading } from '../../hooks';
 
 export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
   ready: boolean;
   error: unknown;
+  progress?: StartupProgress;
 };
 
-export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppProps) => {
-  const reactContexts = useCapabilities(Common.Capability.ReactContext);
-  const reactRoots = useCapabilities(Common.Capability.ReactRoot);
+export const App = ({ placeholder: Placeholder, ready, error, debounce, progress }: AppProps) => {
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
   const stage = useLoading(ready, debounce);
 
   if (error) {
@@ -32,7 +30,7 @@ export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppPro
       return null;
     }
 
-    return <Placeholder stage={stage} />;
+    return <Placeholder stage={stage} progress={progress} />;
   }
 
   const ComposedContext = composeContexts(reactContexts);
@@ -45,7 +43,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';