@dxos/app-framework 0.7.5-main.499c70c → 0.7.5-main.5ae2ba8

package/src/App.tsx

@@ -1,63 +1,169 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-import React from 'react';
+import { effect } from '@preact/signals-core';
+import React, { type PropsWithChildren, type ReactNode } from 'react';
 
 import { invariant } from '@dxos/invariant';
+import { create } from '@dxos/live-object';
 
-import { type HostPluginParams, Plugin, HostPlugin } from './plugins';
-import IntentMeta from './plugins/plugin-intent/meta';
-import SettingsMeta from './plugins/plugin-settings/meta';
-import SurfaceMeta from './plugins/plugin-surface/meta';
+import { Capabilities, Events } from './common';
+import { PluginManager, type PluginManagerOptions, type Plugin } from './core';
+import { topologicalSort } from './helpers';
+import { ErrorBoundary, PluginManagerProvider, useCapabilities } from './react';
+
+const ENABLED_KEY = 'dxos.org/app-framework/enabled';
+
+export type CreateAppOptions = {
+  pluginManager?: PluginManager;
+  pluginLoader?: PluginManagerOptions['pluginLoader'];
+  plugins?: Plugin[];
+  core?: string[];
+  defaults?: string[];
+  placeholder?: ReactNode;
+  fallback?: ErrorBoundary['props']['fallback'];
+  cacheEnabled?: boolean;
+};
 
 /**
  * Expected usage is for this to be the entrypoint of the application.
  * Initializes plugins and renders the root components.
  *
  * @example
- * const meta = [LayoutMeta, MyPluginMeta];
- * const plugins = {
- *  [LayoutMeta.id]: Plugin.lazy(() => import('./plugins/LayoutPlugin/plugin')),
- *  [MyPluginMeta.id]: Plugin.lazy(() => import('./plugins/MyPlugin/plugin')),
- * };
- * const core = [LayoutMeta.id];
- * const default = [MyPluginMeta.id];
+ * const plugins = [LayoutPlugin(), MyPlugin()];
+ * const core = [LayoutPluginId];
+ * const default = [MyPluginId];
  * const fallback = <div>Initializing Plugins...</div>;
- * const App = createApp({ order, plugins, core, default, fallback });
+ * const App = createApp({ plugins, core, default, fallback });
  * createRoot(document.getElementById('root')!).render(
  *   <StrictMode>
  *     <App />
  *   </StrictMode>,
  * );
  *
+ * @param params.pluginLoader A function which loads new plugins.
  * @param params.plugins All plugins available to the application.
- * @param params.meta All plugin metadata.
  * @param params.core Core plugins which will always be enabled.
  * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
- * @param params.fallback Fallback component to render while plugins are initializing.
+ * @param params.placeholder Placeholder component to render during startup.
+ * @param params.fallback Fallback component to render if an error occurs during startup.
+ * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
  */
-export const createApp = ({ meta, plugins, core, ...params }: HostPluginParams) => {
-  const hostPlugin = HostPlugin({
-    plugins: {
-      ...plugins,
-      [IntentMeta.id]: Plugin.lazy(() => import('./plugins/plugin-intent')),
-      [SettingsMeta.id]: Plugin.lazy(() => import('./plugins/plugin-settings')),
-      [SurfaceMeta.id]: Plugin.lazy(() => import('./plugins/plugin-surface')),
-    },
-    meta: [IntentMeta, SettingsMeta, SurfaceMeta, ...meta],
-    core: [IntentMeta.id, SettingsMeta.id, SurfaceMeta.id, ...core],
-    ...params,
+export const createApp = ({
+  pluginManager,
+  pluginLoader: _pluginLoader,
+  plugins = [],
+  core = plugins.map(({ meta }) => meta.id),
+  defaults = [],
+  placeholder = null,
+  fallback = DefaultFallback,
+  cacheEnabled = false,
+}: CreateAppOptions) => {
+  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
+  const pluginLoader =
+    _pluginLoader ??
+    ((id: string) => {
+      const plugin = plugins.find((plugin) => plugin.meta.id === id);
+      invariant(plugin, `Plugin not found: ${id}`);
+      return plugin;
+    });
+
+  const state = create({ ready: false, error: null });
+  const cached: string[] = JSON.parse(localStorage.getItem(ENABLED_KEY) ?? '[]');
+  const enabled = cacheEnabled && cached.length > 0 ? cached : defaults;
+  const manager = pluginManager ?? new PluginManager({ pluginLoader, plugins, core, enabled });
+
+  manager.activation.on(({ event, state: _state, error }) => {
+    // Once the app is ready the first time, don't show the fallback again.
+    if (!state.ready && event === Events.Startup.id) {
+      state.ready = _state === 'activated';
+    }
+
+    if (error && !state.ready && !state.error) {
+      state.error = error;
+    }
+  });
+
+  effect(() => {
+    cacheEnabled && localStorage.setItem(ENABLED_KEY, JSON.stringify(manager.enabled));
+  });
+
+  manager.context.contributeCapability({
+    interface: Capabilities.PluginManager,
+    implementation: manager,
+    module: 'dxos.org/app-framework/plugin-manager',
   });
 
-  invariant(hostPlugin.provides);
-  const { context: Context, root: Root } = hostPlugin.provides;
-  invariant(Context);
-  invariant(Root);
+  setupDevtools(manager);
+
+  // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
+  void manager.activate(Events.SetupReactSurface);
+  void manager.activate(Events.Startup);
 
   return () => (
-    <Context>
-      <Root />
-    </Context>
+    <ErrorBoundary fallback={fallback}>
+      <PluginManagerProvider value={manager}>
+        <App placeholder={placeholder} state={state} />
+      </PluginManagerProvider>
+    </ErrorBoundary>
   );
 };
+
+type AppProps = Required<Pick<CreateAppOptions, 'placeholder'>> & {
+  state: { ready: boolean; error: unknown };
+};
+
+const App = ({ placeholder, state }: AppProps) => {
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
+
+  if (state.error) {
+    // This trigger the error boundary to provide UI feedback for the startup error.
+    throw state.error;
+  }
+
+  // TODO(wittjosiah): Consider using Suspense instead?
+  if (!state.ready) {
+    return <>{placeholder}</>;
+  }
+
+  const ComposedContext = composeContexts(reactContexts);
+  return (
+    <ComposedContext>
+      {reactRoots.map(({ id, root: Component }) => (
+        <Component key={id} />
+      ))}
+    </ComposedContext>
+  );
+};
+
+// Default fallback does not use tailwind or theme.
+const DefaultFallback = ({ error }: { error: Error }) => {
+  return (
+    <div style={{ padding: '1rem' }}>
+      {/* TODO(wittjosiah): Link to docs for replacing default. */}
+      <h1 style={{ fontSize: '1.2rem', fontWeight: 700, margin: '0.5rem 0' }}>{error.message}</h1>
+      <pre>{error.stack}</pre>
+    </div>
+  );
+};
+
+const composeContexts = (contexts: Capabilities.ReactContext[]) => {
+  if (contexts.length === 0) {
+    return ({ children }: PropsWithChildren) => <>{children}</>;
+  }
+
+  return topologicalSort(contexts)
+    .map(({ context }) => context)
+    .reduce((Acc, Next) => ({ children }) => (
+      <Acc>
+        <Next>{children}</Next>
+      </Acc>
+    ));
+};
+
+const setupDevtools = (manager: PluginManager) => {
+  (globalThis as any).composer ??= {};
+  (globalThis as any).composer.manager = manager;
+};

package/src/common/capabilities.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Schema as S } from '@effect/schema';
+import { type FC, type PropsWithChildren } from 'react';
+
+import { type GraphBuilder } from '@dxos/app-graph';
+import { type ArtifactDefinition, type Tool } from '@dxos/artifact';
+import { type Space } from '@dxos/client-protocol';
+import { type RootSettingsStore } from '@dxos/local-storage';
+
+import { type FileInfo } from './file';
+import { type NodeSerializer } from './graph';
+import { type SurfaceDefinition } from './surface';
+import { type Resource } from './translations';
+import { defineCapability, type PluginManager } from '../core';
+import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
+
+export namespace Capabilities {
+  export const PluginManager = defineCapability<PluginManager>('dxos.org/app-framework/capability/plugin-manager');
+
+  export const Null = defineCapability<null>('dxos.org/app-framework/capability/null');
+
+  export type ReactContext = Readonly<{ id: string; dependsOn?: string[]; context: FC<PropsWithChildren> }>;
+  export const ReactContext = defineCapability<ReactContext>('dxos.org/app-framework/capability/react-context');
+
+  export type ReactRoot = Readonly<{ id: string; root: FC<PropsWithChildren> }>;
+  export const ReactRoot = defineCapability<ReactRoot>('dxos.org/app-framework/capability/react-root');
+
+  export type ReactSurface = SurfaceDefinition | readonly SurfaceDefinition[];
+  export const ReactSurface = defineCapability<ReactSurface>('dxos.org/app-framework/common/react-surface');
+
+  export type IntentResolver = AnyIntentResolver | readonly AnyIntentResolver[];
+  export const IntentResolver = defineCapability<IntentResolver>('dxos.org/app-framework/capability/intent-resolver');
+
+  export const IntentDispatcher = defineCapability<IntentContext>(
+    'dxos.org/app-framework/capability/intent-dispatcher',
+  );
+
+  export type Layout = Readonly<{
+    mode: string;
+    dialogOpen: boolean;
+    sidebarOpen: boolean;
+    complementarySidebarOpen: boolean;
+    /**
+     * The id of the active workspace, where a workspace is a set of active items.
+     */
+    workspace: string;
+    /**
+     * Identifiers of items which are currently active in the application.
+     */
+    active: string[];
+    /**
+     * Identifiers of items which were previously active in the application.
+     */
+    inactive: string[];
+    /**
+     * Identifier of the item which should be scrolled into view.
+     */
+    scrollIntoView: string | undefined;
+  }>;
+  export const Layout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
+
+  export const Translations = defineCapability<Readonly<Resource[]>>('dxos.org/app-framework/capability/translations');
+
+  export const AppGraph = defineCapability<Readonly<Pick<GraphBuilder, 'graph' | 'explore'>>>(
+    'dxos.org/app-framework/capability/app-graph',
+  );
+
+  export const AppGraphBuilder = defineCapability<Parameters<GraphBuilder['addExtension']>[0]>(
+    'dxos.org/app-framework/capability/app-graph-builder',
+  );
+
+  export const AppGraphSerializer = defineCapability<NodeSerializer[]>(
+    'dxos.org/app-framework/capability/app-graph-serializer',
+  );
+
+  export const SettingsStore = defineCapability<RootSettingsStore>('dxos.org/app-framework/capability/settings-store');
+
+  // TODO(wittjosiah): The generics caused type inference issues for schemas when contributing settings.
+  // export type Settings = Parameters<RootSettingsStore['createStore']>[0];
+  // export type Settings<T extends SettingsValue = SettingsValue> = SettingsProps<T>;
+  export type Settings = {
+    schema: S.Schema.All;
+    prefix: string;
+    value?: Record<string, any>;
+  };
+  export const Settings = defineCapability<Settings>('dxos.org/app-framework/capability/settings');
+
+  export type Metadata = Readonly<{ id: string; metadata: Record<string, any> }>;
+  export const Metadata = defineCapability<Metadata>('dxos.org/app-framework/capability/metadata');
+
+  export const Tools = defineCapability<Tool[]>('dxos.org/app-framework/capability/tools');
+  export const ArtifactDefinition = defineCapability<ArtifactDefinition>(
+    'dxos.org/app-framework/capability/artifact-definition',
+  );
+
+  export type FileUploader = (file: File, space: Space) => Promise<FileInfo | undefined>;
+  export const FileUploader = defineCapability<FileUploader>('dxos.org/app-framework/capability/file-uploader');
+}

package/src/common/events.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities } from './capabilities';
+import { defineEvent } from '../core';
+
+export namespace Events {
+  /**
+   * Fired when the app is started.
+   */
+  export const Startup = defineEvent('dxos.org/app-framework/event/startup');
+
+  //
+  // Dependent Events
+  //
+
+  /**
+   * Fired to load any newly available surfaces.
+   */
+  export const SetupReactSurface = defineEvent('dxos.org/app-framework/event/setup-react-surface');
+
+  /**
+   * Fired to load any newly available metadata.
+   */
+  export const SetupMetadata = defineEvent('dxos.org/app-framework/event/setup-metadata');
+
+  /**
+   * Fired before the intent dispatcher is activated.
+   */
+  export const SetupIntentResolver = defineEvent('dxos.org/app-framework/event/setup-intent-resolver');
+
+  /**
+   * Fired before the settings store is activated.
+   */
+  export const SetupSettings = defineEvent('dxos.org/app-framework/event/setup-settings');
+
+  /**
+   * Fired before the graph is created.
+   */
+  export const SetupAppGraph = defineEvent('dxos.org/app-framework/event/setup-graph');
+
+  /**
+   * Fired before the translations provider is created.
+   */
+  export const SetupTranslations = defineEvent('dxos.org/app-framework/event/setup-translations');
+
+  /**
+   * Fired to load any newly available artifacts definitions.
+   */
+  export const SetupArtifactDefinition = defineEvent('dxos.org/app-framework/event/setup-artifact-definition');
+
+  //
+  // Triggered Events
+  //
+
+  /**
+   * Fired after the intent dispatcher is ready.
+   */
+  export const DispatcherReady = defineEvent('dxos.org/app-framework/event/dispatcher-ready');
+
+  /**
+   * Fired after the settings store is ready.
+   */
+  export const SettingsReady = defineEvent('dxos.org/app-framework/event/settings-ready');
+
+  /**
+   * Fired when the graph is ready.
+   */
+  export const AppGraphReady = defineEvent('dxos.org/app-framework/event/graph-ready');
+
+  /**
+   * Fired when plugin state is ready.
+   */
+  export const createStateEvent = (specifier: string) => defineEvent('dxos.org/app-framework/event/state', specifier);
+  export const LayoutReady = createStateEvent(Capabilities.Layout.identifier);
+}

package/src/common/file.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Schema as S } from '@effect/schema';
+
+// TODO(burdon): See Accept attribute (uses MIME types).
+// E.g., 'image/*': ['.jpg', '.jpeg', '.png', '.gif'],
+export const defaultFileTypes = {
+  images: ['png', 'jpg', 'jpeg', 'gif'],
+  media: ['mp3', 'mp4', 'mov', 'avi'],
+  text: ['pdf', 'txt', 'md'],
+};
+
+export const FileInfoSchema = S.Struct({
+  name: S.String,
+  type: S.String,
+  url: S.optional(S.String),
+  cid: S.optional(S.String), // TODO(burdon): Meta key? Or other common properties with other file management system? (e.g., WNFS).
+});
+
+export type FileInfo = S.Schema.Type<typeof FileInfoSchema>;

package/src/common/graph.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { Node } from '@dxos/app-graph';
+import { type MaybePromise, type Position } from '@dxos/util';
+
+// TODO(wittjosiah): Factor out.
+export type SerializedNode = {
+  name: string;
+  data: string;
+  type?: string;
+};
+
+// TODO(wittjosiah): Factor out.
+export type NodeSerializer<T = any> = {
+  inputType: string;
+  outputType: string;
+  position?: Position;
+
+  /**
+   * Takes a node and serializes it into a format that can be stored.
+   */
+  serialize: (node: Node<T>) => MaybePromise<SerializedNode>;
+
+  /**
+   * Takes a serialized node and deserializes it into the application.
+   */
+  deserialize: (data: SerializedNode, ancestors: unknown[]) => MaybePromise<T>;
+};

package/src/{plugins/common → common}/index.ts

@@ -2,9 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './capabilities';
+export * from './events';
 export * from './file';
 export * from './graph';
 export * from './layout';
-export * from './metadata';
-export * from './navigation';
+export * from './surface';
 export * from './translations';