@dxos/app-framework 0.8.3-staging.0fa589b → 0.8.4-main.1da679c

package/src/playground/generator/Toolbar.tsx

@@ -6,12 +6,13 @@ import React, { useCallback } from 'react';
 
 import { Button } from '@dxos/react-ui';
 
-import { createGeneratorIntent, createPluginId, Number } from './generator';
 import { Capabilities } from '../../common';
 import { contributes } from '../../core';
 import { createIntent } from '../../plugin-intent';
 import { useCapabilities, useIntentDispatcher, usePluginManager } from '../../react';
 
+import { Number, createGeneratorIntent, createPluginId } from './generator';
+
 export const Toolbar = () => {
   const manager = usePluginManager();
   const { dispatchPromise: dispatch } = useIntentDispatcher();

package/src/playground/generator/generator.ts

@@ -5,8 +5,8 @@
 import { Schema } from 'effect';
 
 import { Capabilities, Events } from '../../common';
-import { contributes, defineEvent, defineCapability, defineModule, definePlugin } from '../../core';
-import { createResolver, type IntentSchema } from '../../plugin-intent';
+import { contributes, defineCapability, defineEvent, defineModule, definePlugin } from '../../core';
+import { type IntentSchema, createResolver } from '../../plugin-intent';
 
 export const Number = defineCapability<number>('dxos.org/test/generator/number');
 

package/src/playground/layout/plugin.ts

@@ -3,7 +3,7 @@
 //
 
 import { Events } from '../../common';
-import { definePlugin, lazy, defineModule } from '../../core';
+import { defineModule, definePlugin, lazy } from '../../core';
 
 const Layout = lazy(() => import('./Layout'));
 

package/src/playground/logger/Toolbar.tsx

@@ -6,12 +6,13 @@ import React, { useCallback } from 'react';
 
 import { Button } from '@dxos/react-ui';
 
-import { Log } from './schema';
 import { Capabilities, createSurface } from '../../common';
 import { contributes } from '../../core';
 import { createIntent } from '../../plugin-intent';
 import { useIntentDispatcher } from '../../react';
 
+import { Log } from './schema';
+
 export const Logger = () => {
   const { dispatchPromise } = useIntentDispatcher();
   const handleClick = useCallback(() => dispatchPromise(createIntent(Log, { message: 'Hello, world!' })), []);

package/src/playground/logger/plugin.ts

@@ -4,11 +4,12 @@
 
 import { log } from '@dxos/log';
 
-import { Log } from './schema';
 import { Capabilities, Events } from '../../common';
-import { contributes, defineModule, lazy, definePlugin } from '../../core';
+import { contributes, defineModule, definePlugin, lazy } from '../../core';
 import { createResolver } from '../../plugin-intent';
 
+import { Log } from './schema';
+
 const Toolbar = lazy(() => import('./Toolbar'));
 
 export const LoggerPlugin = () =>

package/src/playground/playground.stories.tsx

@@ -4,16 +4,18 @@
 
 import '@dxos-theme';
 
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { withLayout, withTheme } from '@dxos/storybook-utils';
 
+import { useApp } from '../components';
+import { IntentPlugin } from '../plugin-intent';
+
 import { DebugPlugin } from './debug';
-import { createNumberPlugin, GeneratorPlugin } from './generator';
+import { GeneratorPlugin, createNumberPlugin } from './generator';
 import { LayoutPlugin } from './layout';
 import { LoggerPlugin } from './logger';
-import { useApp } from '../App';
-import { IntentPlugin } from '../plugin-intent';
 
 const plugins = [IntentPlugin(), LayoutPlugin(), DebugPlugin(), LoggerPlugin(), GeneratorPlugin()];
 
@@ -21,22 +23,25 @@ const Placeholder = () => {
   return <div>Loading...</div>;
 };
 
-const Story = () => {
+const DefaultStory = () => {
   const App = useApp({
     pluginLoader: (id) => createNumberPlugin(id),
     plugins,
     core: plugins.map((plugin) => plugin.meta.id),
-    // Having a non-empty placeholder makes it clear if it's taking a while to load.
     placeholder: Placeholder,
   });
 
   return <App />;
 };
 
-export const Playground = {};
-
-export default {
+const meta = {
   title: 'sdk/app-framework/playground',
-  render: Story,
+  render: DefaultStory,
   decorators: [withTheme, withLayout()],
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {};

package/src/plugin-intent/IntentPlugin.ts

@@ -2,10 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import { INTENT_PLUGIN } from './actions';
 import { Events } from '../common';
 import { defineModule, definePlugin, lazy } from '../core';
 
+import { INTENT_PLUGIN } from './actions';
+
 export const IntentPlugin = () =>
   definePlugin({ id: INTENT_PLUGIN, name: 'Intent' }, [
     defineModule({

package/src/plugin-intent/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './actions';
+export * from './errors';
 export * from './intent';
 export * from './intent-dispatcher';
 export * from './IntentPlugin';

package/src/plugin-intent/intent-dispatcher.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema, Effect, Fiber, pipe } from 'effect';
+import { Effect, Fiber, Schema, pipe } from 'effect';
 import { describe, expect, test } from 'vitest';
 
 import { chain, createIntent } from './intent';

package/src/plugin-intent/intent-dispatcher.ts

@@ -2,17 +2,19 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Effect, Option, pipe, Ref } from 'effect';
+import { Effect, Option, Ref, pipe } from 'effect';
 import { type Simplify } from 'effect/Types';
 
 import { live } from '@dxos/live-object';
 import { log } from '@dxos/log';
-import { byPosition, type MaybePromise, type Position, type GuardedType } from '@dxos/util';
+import { type GuardedType, type MaybePromise, type Position, byPosition } from '@dxos/util';
+
+import { Capabilities, Events } from '../common';
+import { type PluginContext, contributes } from '../core';
 
 import { IntentAction } from './actions';
 import { CycleDetectedError, NoResolversError } from './errors';
 import {
-  createIntent,
   type AnyIntent,
   type AnyIntentChain,
   type Intent,
@@ -22,9 +24,8 @@ import {
   type IntentResultData,
   type IntentSchema,
   type Label,
+  createIntent,
 } from './intent';
-import { Events, Capabilities } from '../common';
-import { contributes, type PluginContext } from '../core';
 
 const EXECUTION_LIMIT = 100;
 const HISTORY_LIMIT = 100;
@@ -196,7 +197,8 @@ export const createDispatcher = (
         .filter((resolver) => !resolver.filter || resolver.filter(intent.data))
         .toSorted(byPosition);
       if (candidates.length === 0) {
-        yield* Effect.fail(new NoResolversError(intent.id));
+        log.info('no resolvers found', { intent: intent.id });
+        return yield* Effect.fail(new NoResolversError(intent.id));
       }
 
       const effect = candidates[0].resolve(intent.data, intent.undo ?? false);
@@ -207,7 +209,7 @@ export const createDispatcher = (
   const dispatch: IntentDispatcher = (intentChain, depth = 0) => {
     return Effect.gen(function* () {
       if (depth > executionLimit) {
-        yield* Effect.fail(new CycleDetectedError());
+        return yield* Effect.fail(new CycleDetectedError());
       }
 
       const resultsRef = yield* Ref.make<AnyIntentResult[]>([]);
@@ -230,7 +232,7 @@ export const createDispatcher = (
           //     error: result.error.message,
           //   }),
           // );
-          yield* Effect.fail(result.error);
+          return yield* Effect.fail(result.error);
         }
       }
 

package/src/plugin-settings/SettingsPlugin.ts

@@ -2,11 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
-import { SETTINGS_PLUGIN } from './actions';
-import translations from './translations';
 import { Capabilities, Events } from '../common';
 import { contributes, defineModule, definePlugin, lazy } from '../core';
 
+import { SETTINGS_PLUGIN } from './actions';
+import { translations } from './translations';
+
 // TODO(wittjosiah): Add options to exclude some modules.
 export const SettingsPlugin = () =>
   definePlugin({ id: SETTINGS_PLUGIN, name: 'Settings' }, [

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

@@ -5,15 +5,16 @@
 import { Rx } from '@effect-rx/rx-react';
 import { Option, pipe } from 'effect';
 
-import { createExtension, ROOT_ID } from '@dxos/app-graph';
+import { ROOT_ID, createExtension } from '@dxos/app-graph';
 import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
 import { isNonNullable } from '@dxos/util';
 
-import { SETTINGS_ID, SETTINGS_KEY, SETTINGS_PLUGIN, SettingsAction } from './actions';
 import { Capabilities } from '../common';
-import { contributes, type PluginMeta, type PluginContext } from '../core';
+import { type PluginContext, type PluginMeta, contributes } from '../core';
 import { createIntent } from '../plugin-intent';
 
+import { SETTINGS_ID, SETTINGS_KEY, SETTINGS_PLUGIN, SettingsAction } from './actions';
+
 export default (context: PluginContext) =>
   contributes(Capabilities.AppGraphBuilder, [
     createExtension({

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

@@ -4,10 +4,11 @@
 
 import { pipe } from 'effect';
 
-import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
 import { Capabilities, LayoutAction } from '../common';
 import { contributes } from '../core';
-import { createResolver, createIntent, chain } from '../plugin-intent';
+import { chain, createIntent, createResolver } from '../plugin-intent';
+
+import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
 
 export default () =>
   contributes(

package/src/plugin-settings/store.ts

@@ -5,7 +5,7 @@
 import { RootSettingsStore } from '@dxos/local-storage';
 
 import { Capabilities } from '../common';
-import { contributes, type PluginContext } from '../core';
+import { type PluginContext, contributes } from '../core';
 
 export default (context: PluginContext) => {
   // TODO(wittjosiah): Replace with rx?

package/src/plugin-settings/translations.ts

@@ -2,9 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type Resource } from '@dxos/react-ui';
+
 import { SETTINGS_PLUGIN } from './actions';
 
-export default [
+export const translations = [
   {
     'en-US': {
       [SETTINGS_PLUGIN]: {
@@ -14,4 +16,4 @@ export default [
       },
     },
   },
-];
+] as const satisfies Resource[];

package/src/react/ErrorBoundary.tsx

@@ -2,38 +2,40 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { Component, type FC, type PropsWithChildren } from 'react';
+import React, { Component, type FC, type JSX, type PropsWithChildren, type ReactNode } from 'react';
 
-type Props = PropsWithChildren<{ data?: any; fallback: FC<{ data?: any; error: Error; reset: () => void }> }>;
-type State = { error: Error | undefined };
+type State = {
+  error: Error | undefined;
+};
+
+export type ErrorBoundaryProps = PropsWithChildren<{
+  data?: any;
+  fallback?: FC<{ data?: any; error: Error }>;
+}>;
 
 /**
  * Surface error boundary.
- *
  * For basic usage prefer providing a fallback component to `Surface`.
  *
- * For more information on error boundaries, see:
- * https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
+ * Ref: https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
  */
-export class ErrorBoundary extends Component<Props, State> {
-  constructor(props: Props) {
-    super(props);
-    this.state = { error: undefined };
-  }
-
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
   static getDerivedStateFromError(error: Error): { error: Error } {
     return { error };
   }
 
-  override componentDidUpdate(prevProps: Props): void {
+  override state = { error: undefined };
+
+  override componentDidUpdate(prevProps: ErrorBoundaryProps): void {
     if (prevProps.data !== this.props.data) {
       this.resetError();
     }
   }
 
-  override render(): string | number | boolean | React.JSX.Element | Iterable<React.ReactNode> | null | undefined {
+  override render(): string | number | boolean | JSX.Element | Iterable<ReactNode> | null | undefined {
     if (this.state.error) {
-      return <this.props.fallback data={this.props.data} error={this.state.error} reset={this.resetError} />;
+      const Fallback = this.props.fallback ?? DefaultFallback;
+      return <Fallback data={this.props.data} error={this.state.error} />;
     }
 
     return this.props.children;
@@ -43,3 +45,10 @@ export class ErrorBoundary extends Component<Props, State> {
     this.setState({ error: undefined });
   }
 }
+
+const DefaultFallback: NonNullable<ErrorBoundaryProps['fallback']> = ({ data, error }) => (
+  <div className='flex flex-col gap-2 overflow-hidden border border-red-500 rounded-sm'>
+    <pre className='whitespace-pre-wrap font-sm text-xs p-2'>ERROR: {error.message}</pre>
+    <pre className='whitespace-pre-wrap font-sm text-xs p-2 text-subdued'>{JSON.stringify(data, null, 2)}</pre>
+  </div>
+);

package/src/react/IntentContext.tsx

@@ -2,15 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Context, createContext, useContext, type Provider, useEffect } from 'react';
+import { type Context, type Provider, createContext, useContext, useEffect } from 'react';
 
 import { raise } from '@dxos/debug';
 import { pick } from '@dxos/util';
 
-import { usePluginManager } from './PluginManagerProvider';
 import { Capabilities } from '../common';
 import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
 
+import { usePluginManager } from './PluginManagerProvider';
+
 const IntentContext: Context<IntentContext | undefined> = createContext<IntentContext | undefined>(undefined);
 
 export const useIntentDispatcher = (): Pick<IntentContext, 'dispatch' | 'dispatchPromise'> => {

package/src/react/Surface.stories.tsx

@@ -4,18 +4,20 @@
 
 import '@dxos-theme';
 
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useCallback, useState } from 'react';
 
 import { faker } from '@dxos/random';
 import { Button, List, ListItem } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/storybook-utils';
 
-import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
 import { Capabilities, createSurface } from '../common';
 import { type PluginManager } from '../core';
 import { setupPluginManager } from '../testing';
 
+import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
+import { Surface, useSurfaces } from './Surface';
+
 const randomColor = (): string => {
   const hue = faker.number.int({ min: 0, max: 360 });
   const saturation = faker.number.int({ min: 50, max: 90 });
@@ -23,7 +25,7 @@ const randomColor = (): string => {
   return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
 };
 
-const Story = () => {
+const Component = () => {
   const manager = usePluginManager();
   const surfaces = useSurfaces();
   const [picked, setPicked] = useState('test');
@@ -77,20 +79,26 @@ const Story = () => {
   );
 };
 
-export default {
+const DefaultStory = (props: { manager: PluginManager }) => {
+  return (
+    <PluginManagerProvider value={props.manager}>
+      <Component />
+    </PluginManagerProvider>
+  );
+};
+
+const meta = {
   title: 'sdk/app-framework/Surface',
-  render: ({ manager }: { manager: PluginManager }) => {
-    return (
-      <PluginManagerProvider value={manager}>
-        <Story />
-      </PluginManagerProvider>
-    );
-  },
+  render: DefaultStory,
   // NOTE: Intentionally not using withPluginManager to try to reduce surface area of the story.
   decorators: [withTheme, withLayout()],
   args: {
     manager: setupPluginManager(),
   },
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
 
-export const Default = {};
+export const Default: Story = {};

package/src/react/Surface.tsx

@@ -2,16 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { memo, forwardRef, Suspense, useMemo, Fragment } from 'react';
+import React, { Fragment, Suspense, forwardRef, memo, useMemo } from 'react';
 
 import { useDefaultValue } from '@dxos/react-hooks';
 import { byPosition } from '@dxos/util';
 
-import { ErrorBoundary } from './ErrorBoundary';
-import { useCapabilities } from './useCapabilities';
 import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
 import { type PluginContext } from '../core';
 
+import { ErrorBoundary } from './ErrorBoundary';
+import { useCapabilities } from './useCapabilities';
+
 const DEFAULT_PLACEHOLDER = <Fragment />;
 
 /**

package/src/react/common.ts

@@ -2,9 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useCapability } from './useCapabilities';
 import { Capabilities } from '../common';
 
+import { useCapability } from './useCapabilities';
+
 export const useIntentDispatcher = () => useCapability(Capabilities.IntentDispatcher);
 
 export const useAppGraph = () => useCapability(Capabilities.AppGraph);

package/src/react/useCapabilities.ts

@@ -6,9 +6,10 @@ import { useRxValue } from '@effect-rx/rx-react';
 
 import { invariant } from '@dxos/invariant';
 
-import { usePluginManager } from './PluginManagerProvider';
 import { type InterfaceDef } from '../core';
 
+import { usePluginManager } from './PluginManagerProvider';
+
 /**
  * Hook to request capabilities from the plugin context.
  * @returns An array of capabilities.

package/src/testing/withPluginManager.stories.tsx

@@ -2,15 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { withTheme, type Meta } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/storybook-utils';
 
-import { withPluginManager } from './withPluginManager';
 import { Capabilities, createSurface } from '../common';
 import { contributes } from '../core';
 import { Surface } from '../react';
 
+import { withPluginManager } from './withPluginManager';
+
 const DefaultStory = () => {
   console.log('Render');
   return (
@@ -21,7 +23,7 @@ const DefaultStory = () => {
   );
 };
 
-const meta: Meta = {
+const meta = {
   title: 'sdk/app-framework/withPluginManager',
   render: DefaultStory,
   decorators: [
@@ -39,8 +41,10 @@ const meta: Meta = {
       ],
     }),
   ],
-};
+} satisfies Meta<typeof DefaultStory>;
 
 export default meta;
 
-export const Default = {};
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/testing/withPluginManager.tsx

@@ -6,22 +6,24 @@ import { type Decorator } from '@storybook/react';
 import React, { useEffect, useMemo } from 'react';
 
 import { raise } from '@dxos/debug';
+import { useAsyncEffect } from '@dxos/react-hooks';
 
-import { useApp, type CreateAppOptions } from '../App';
 import { Capabilities, Events } from '../common';
+import { type UseAppOptions, useApp } from '../components';
 import {
-  contributes,
-  defineModule,
-  definePlugin,
   type ActivationEvent,
   type AnyCapability,
-  PluginManager,
   type PluginContext,
+  PluginManager,
+  contributes,
+  defineModule,
+  definePlugin,
 } from '../core';
 
 // TODO(burdon): Factor out (use consistently in plugin framework?)
 export type Provider<C, R> = (context: C) => R;
 export type ProviderOrValue<C, R> = Provider<C, R> | R;
+
 export const getValue = <C, R>(providerOrValue: ProviderOrValue<C, R>, context: C): R => {
   return typeof providerOrValue === 'function' ? (providerOrValue as Provider<C, R>)(context) : providerOrValue;
 };
@@ -34,7 +36,7 @@ export const setupPluginManager = ({
   plugins = [],
   core = plugins.map(({ meta }) => meta.id),
   ...options
-}: CreateAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
+}: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
   const pluginManager = new PluginManager({
     pluginLoader: () => raise(new Error('Not implemented')),
     plugins: [storyPlugin(), ...plugins],
@@ -55,8 +57,10 @@ export const setupPluginManager = ({
   return pluginManager;
 };
 
-export type WithPluginManagerOptions = CreateAppOptions & {
+export type WithPluginManagerOptions = UseAppOptions & {
+  /** @deprecated */
   capabilities?: ProviderOrValue<PluginContext, AnyCapability[]>;
+  /** @deprecated */
   fireEvents?: (ActivationEvent | string)[];
 };
 
@@ -86,12 +90,8 @@ export const withPluginManager = (options: WithPluginManagerOptions = {}): Decor
     }, [pluginManager, context]);
 
     // Fire events.
-    useEffect(() => {
-      const timeout = setTimeout(async () => {
-        await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
-      });
-
-      return () => clearTimeout(timeout);
+    useAsyncEffect(async () => {
+      await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
     }, [pluginManager]);
 
     // Create app.

package/tsconfig.json

@@ -39,7 +39,7 @@
       "path": "../../core/ai"
     },
     {
-      "path": "../../core/artifact"
+      "path": "../../core/blueprints"
     },
     {
       "path": "../../core/echo/echo-schema"
@@ -50,6 +50,9 @@
     {
       "path": "../../core/echo/live-object"
     },
+    {
+      "path": "../../core/functions"
+    },
     {
       "path": "../../ui/primitives/react-hooks"
     },
@@ -68,12 +71,5 @@
     {
       "path": "../schema"
     }
-  ],
-  "ts-node": {
-    "compilerOptions": {
-      "module": "CommonJS"
-    },
-    "files": true,
-    "transpileOnly": true
-  }
+  ]
 }

package/vitest.config.ts

@@ -4,6 +4,9 @@
 
 import { defineConfig, mergeConfig } from 'vitest/config';
 
-import { baseConfig } from '../../../vitest.shared';
+import { baseConfig } from '../../../vitest.base.config';
 
-export default mergeConfig(baseConfig({ cwd: __dirname }), defineConfig({}));
+export default mergeConfig(
+  baseConfig({ cwd: __dirname }),
+  defineConfig({}),
+);