@dxos/app-framework 0.7.4 → 0.7.5-feature-compute.4d9d99a

package/dist/types/src/plugin-settings/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../../src/plugin-settings/actions.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAEtC,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAC1D,eAAO,MAAM,eAAe,oCAA8B,CAAC;AAE3D,yBAAiB,cAAc,CAAC;;;;;;;;;IAC9B,MAAM,OAAO,IAAK,SAAQ,SAKxB;KAAG;;CACN"}

package/dist/types/src/plugin-settings/index.d.ts

@@ -0,0 +1,3 @@
+export * from './actions';
+export * from './SettingsPlugin';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/plugin-settings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/plugin-settings/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC"}

package/dist/types/src/react/ErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../../../../src/react/ErrorBoundary.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAE1E,KAAK,KAAK,GAAG,iBAAiB,CAAC;IAAE,IAAI,CAAC,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,EAAE,CAAC;QAAE,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAC9G,KAAK,KAAK,GAAG;IAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1C;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC;gBAC5C,KAAK,EAAE,KAAK;IAKxB,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK;;;IAInC,kBAAkB,CAAC,SAAS,EAAE,KAAK,GAAG,IAAI;IAM1C,MAAM;IAQf,OAAO,CAAC,UAAU;CAGnB"}

package/dist/types/src/react/PluginManagerProvider.d.ts

@@ -0,0 +1,10 @@
+import { type PluginManager } from '../core';
+/**
+ * Get the plugin manager.
+ */
+export declare const usePluginManager: () => PluginManager;
+/**
+ * Context provider for a plugin manager.
+ */
+export declare const PluginManagerProvider: import("react").Provider<PluginManager | undefined>;
+//# sourceMappingURL=PluginManagerProvider.d.ts.map

package/dist/types/src/react/PluginManagerProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManagerProvider.d.ts","sourceRoot":"","sources":["../../../../src/react/PluginManagerProvider.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7C;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAO,aACkD,CAAC;AAEvF;;GAEG;AACH,eAAO,MAAM,qBAAqB,qDAAgC,CAAC"}

package/dist/types/src/react/Surface.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { type SurfaceProps } from '../common';
+import { type PluginsContext } from '../core';
+/**
+ * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
+ */
+export declare const isSurfaceAvailable: (context: PluginsContext, { role, data }: Pick<SurfaceProps, "role" | "data">) => boolean;
+/**
+ * A surface is a named region of the screen that can be populated by plugins.
+ */
+export declare const Surface: React.MemoExoticComponent<React.ForwardRefExoticComponent<Omit<SurfaceProps, "ref"> & React.RefAttributes<HTMLElement>>>;
+//# sourceMappingURL=Surface.d.ts.map

package/dist/types/src/react/Surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Surface.d.ts","sourceRoot":"","sources":["../../../../src/react/Surface.tsx"],"names":[],"mappings":"AAIA,OAAO,KAA8C,MAAM,OAAO,CAAC;AAOnE,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAgB9C;;GAEG;AACH,eAAO,MAAM,kBAAkB,YAAa,cAAc,kBAAkB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,YAI9G,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,0HA+BnB,CAAC"}

package/dist/types/src/react/index.d.ts

@@ -0,0 +1,5 @@
+export * from './ErrorBoundary';
+export * from './PluginManagerProvider';
+export * from './Surface';
+export * from './useCapabilities';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/react/index.ts"],"names":[],"mappings":"AAIA,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC"}

package/dist/types/src/react/useCapabilities.d.ts

@@ -0,0 +1,13 @@
+import { type InterfaceDef } from '../core';
+/**
+ * Hook to request capabilities from the plugin context.
+ * @returns An array of capabilities.
+ */
+export declare const useCapabilities: <T, U extends T = T>(interfaceDef: InterfaceDef<T>, filter?: (capability: T, moduleId: string) => capability is U) => U[];
+/**
+ * Hook to request a capability from the plugin context.
+ * @returns The capability.
+ * @throws If no capability is found.
+ */
+export declare const useCapability: <T, U extends T = T>(interfaceDef: InterfaceDef<T>, filter?: (capability: T, moduleId: string) => capability is U) => U;
+//# sourceMappingURL=useCapabilities.d.ts.map

package/dist/types/src/react/useCapabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCapabilities.d.ts","sourceRoot":"","sources":["../../../../src/react/useCapabilities.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,SAAS,CAAC,oBAC9B,YAAY,CAAC,CAAC,CAAC,WACpB,CAAC,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,UAAU,IAAI,CAAC,QAS9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,CAAC,SAAS,CAAC,oBAC5B,YAAY,CAAC,CAAC,CAAC,WACpB,CAAC,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,UAAU,IAAI,CAAC,MAK9D,CAAC"}

package/dist/types/src/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './withPluginManager';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAIA,cAAc,qBAAqB,CAAC"}

package/dist/types/src/testing/withPluginManager.d.ts

@@ -0,0 +1,10 @@
+import { type Decorator } from '@storybook/react';
+import { type CreateAppOptions } from '../App';
+import { type AnyCapability } from '../core';
+/**
+ * Wraps a story with a plugin manager.
+ */
+export declare const withPluginManager: ({ capabilities, plugins, core, ...options }?: CreateAppOptions & {
+    capabilities?: AnyCapability[];
+}) => Decorator;
+//# sourceMappingURL=withPluginManager.d.ts.map

package/dist/types/src/testing/withPluginManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withPluginManager.d.ts","sourceRoot":"","sources":["../../../../src/testing/withPluginManager.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAKlD,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE1D,OAAO,EAAE,KAAK,aAAa,EAA0D,MAAM,SAAS,CAAC;AAErG;;GAEG;AACH,eAAO,MAAM,iBAAiB,iDAK3B,gBAAgB,GAAG;IAAE,YAAY,CAAC,EAAE,aAAa,EAAE,CAAA;CAAE,KAAQ,SAqC/D,CAAC"}

package/dist/types/src/testing/withPluginManager.stories.d.ts

@@ -0,0 +1,5 @@
+import { type Meta } from '@dxos/storybook-utils';
+declare const meta: Meta;
+export default meta;
+export declare const Default: {};
+//# sourceMappingURL=withPluginManager.stories.d.ts.map

package/dist/types/src/testing/withPluginManager.stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withPluginManager.stories.d.ts","sourceRoot":"","sources":["../../../../src/testing/withPluginManager.stories.tsx"],"names":[],"mappings":"AAOA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAiB7D,QAAA,MAAM,IAAI,EAAE,IAkBX,CAAC;AAEF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,IAAK,CAAC"}

package/dist/types/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.7.2"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-framework",
-  "version": "0.7.4",
+  "version": "0.7.5-feature-compute.4d9d99a",
   "description": "A framework for building applications from composible plugins.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -12,32 +12,48 @@
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/src/testing/index.d.ts",
+      "browser": "./dist/lib/browser/testing/index.mjs",
+      "node": "./dist/lib/node-esm/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
-    "*": {}
+    "*": {
+      "./testing": [
+        "dist/types/src/testing/index.d.ts"
+      ]
+    }
   },
   "dependencies": {
     "@effect/schema": "^0.75.5",
     "@phosphor-icons/react": "^2.1.5",
     "@preact/signals-core": "^1.6.0",
+    "effect": "^3.12.3",
     "zod": "^3.22.4",
-    "@dxos/app-graph": "0.7.4",
-    "@dxos/client-protocol": "0.7.4",
-    "@dxos/async": "0.7.4",
-    "@dxos/context": "0.7.4",
-    "@dxos/debug": "0.7.4",
-    "@dxos/echo-schema": "0.7.4",
-    "@dxos/invariant": "0.7.4",
-    "@dxos/live-object": "0.7.4",
-    "@dxos/local-storage": "0.7.4",
-    "@dxos/log": "0.7.4",
-    "@dxos/util": "0.7.4"
+    "@dxos/async": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/app-graph": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/client-protocol": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/debug": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/echo-schema": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/context": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/invariant": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/local-storage": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/live-object": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/log": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/react-hooks": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/storybook-utils": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/util": "0.7.5-feature-compute.4d9d99a"
   },
   "devDependencies": {
     "@types/react": "~18.2.0",
-    "react": "~18.2.0"
+    "react": "~18.2.0",
+    "@dxos/echo-signals": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/react-ui": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/react-ui-syntax-highlighter": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/storybook-utils": "0.7.5-feature-compute.4d9d99a"
   },
   "peerDependencies": {
     "@phosphor-icons/react": "^2.1.5",

package/project.json

@@ -11,7 +11,8 @@
     "compile": {
       "options": {
         "entryPoints": [
-          "{projectRoot}/src/index.ts"
+          "{projectRoot}/src/index.ts",
+          "{projectRoot}/src/testing/index.ts"
         ]
       }
     },

package/src/App.tsx

@@ -1,63 +1,167 @@
 //
-// 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 } 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 }) => {
+    if (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);
+
+  void manager.activate(Events.Startup);
 
   return () => (
-    <Context>
-      <Root />
-    </Context>
+    <ErrorBoundary fallback={fallback}>
+      <App placeholder={placeholder} manager={manager} state={state} />
+    </ErrorBoundary>
   );
 };
+
+type AppProps = Required<Pick<CreateAppOptions, 'placeholder'>> & {
+  manager: PluginManager;
+  state: { ready: boolean; error: unknown };
+};
+
+const App = ({ placeholder, manager, state }: AppProps) => {
+  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 reactContexts = manager.context.requestCapabilities(Capabilities.ReactContext);
+  const reactRoots = manager.context.requestCapabilities(Capabilities.ReactRoot);
+
+  const ComposedContext = composeContexts(reactContexts);
+  return (
+    <PluginManagerProvider value={manager}>
+      <ComposedContext>
+        {reactRoots.map(({ id, root: Component }) => (
+          <Component key={id} />
+        ))}
+      </ComposedContext>
+    </PluginManagerProvider>
+  );
+};
+
+// 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,82 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type FC, type PropsWithChildren } from 'react';
+
+import { type GraphBuilder } from '@dxos/app-graph';
+import { type Space } from '@dxos/client-protocol';
+import { type S } from '@dxos/echo-schema';
+import { type RootSettingsStore } from '@dxos/local-storage';
+import { type DeepReadonly } from '@dxos/util';
+
+import { type FileInfo } from './file';
+import { type NodeSerializer } from './graph';
+import { type Layout } from './layout';
+import { type LayoutParts } from './navigation';
+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 const Layout = defineCapability<Readonly<Layout>>('dxos.org/app-framework/capability/layout');
+  export const MutableLayout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
+
+  export type MutableLocation = { active: LayoutParts; closed: string[] };
+  export type Location = DeepReadonly<MutableLocation>;
+  export const Location = defineCapability<Location>('dxos.org/app-framework/capability/location');
+  export const MutableLocation = defineCapability<MutableLocation>('dxos.org/app-framework/capability/location');
+
+  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 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,63 @@
+//
+// 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 before the intent dispatcher is activated.
+   */
+  export const SetupIntents = defineEvent('dxos.org/app-framework/event/setup-intents');
+
+  /**
+   * 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');
+
+  //
+  // 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);
+  export const LocationReady = createStateEvent(Capabilities.Location.identifier);
+}

package/src/common/file.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { S } from '@dxos/echo-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 } 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;
+  disposition?: 'hoist' | 'fallback';
+
+  /**
+   * 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,11 @@
 // 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';