@dxos/app-framework 0.8.4-main.b97322e → 0.8.4-main.dedc0f3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-framework",
-  "version": "0.8.4-main.b97322e",
+  "version": "0.8.4-main.dedc0f3",
   "description": "A framework for building applications from composible plugins.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,16 +10,19 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
     },
     "./testing": {
+      "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
       "browser": "./dist/lib/browser/testing/index.mjs",
       "node": "./dist/lib/node-esm/testing/index.mjs"
     },
     "./worker": {
+      "source": "./src/worker.ts",
       "types": "./dist/types/src/worker.d.ts",
       "browser": "./dist/lib/browser/worker.mjs",
       "node": "./dist/lib/node-esm/worker.mjs"
@@ -37,37 +40,38 @@
     }
   },
   "dependencies": {
+    "@effect/ai": "0.25.2",
     "@preact-signals/safe-react": "^0.9.0",
     "@preact/signals-core": "^1.9.0",
-    "@dxos/ai": "0.8.4-main.b97322e",
-    "@dxos/app-graph": "0.8.4-main.b97322e",
-    "@dxos/async": "0.8.4-main.b97322e",
-    "@dxos/blueprints": "0.8.4-main.b97322e",
-    "@dxos/client-protocol": "0.8.4-main.b97322e",
-    "@dxos/debug": "0.8.4-main.b97322e",
-    "@dxos/echo-schema": "0.8.4-main.b97322e",
-    "@dxos/invariant": "0.8.4-main.b97322e",
-    "@dxos/keys": "0.8.4-main.b97322e",
-    "@dxos/functions": "0.8.4-main.b97322e",
-    "@dxos/live-object": "0.8.4-main.b97322e",
-    "@dxos/local-storage": "0.8.4-main.b97322e",
-    "@dxos/log": "0.8.4-main.b97322e",
-    "@dxos/react-hooks": "0.8.4-main.b97322e",
-    "@dxos/schema": "0.8.4-main.b97322e",
-    "@dxos/util": "0.8.4-main.b97322e"
+    "@dxos/ai": "0.8.4-main.dedc0f3",
+    "@dxos/app-graph": "0.8.4-main.dedc0f3",
+    "@dxos/blueprints": "0.8.4-main.dedc0f3",
+    "@dxos/debug": "0.8.4-main.dedc0f3",
+    "@dxos/async": "0.8.4-main.dedc0f3",
+    "@dxos/echo-schema": "0.8.4-main.dedc0f3",
+    "@dxos/client-protocol": "0.8.4-main.dedc0f3",
+    "@dxos/functions": "0.8.4-main.dedc0f3",
+    "@dxos/keys": "0.8.4-main.dedc0f3",
+    "@dxos/invariant": "0.8.4-main.dedc0f3",
+    "@dxos/local-storage": "0.8.4-main.dedc0f3",
+    "@dxos/live-object": "0.8.4-main.dedc0f3",
+    "@dxos/react-hooks": "0.8.4-main.dedc0f3",
+    "@dxos/log": "0.8.4-main.dedc0f3",
+    "@dxos/schema": "0.8.4-main.dedc0f3",
+    "@dxos/util": "0.8.4-main.dedc0f3"
   },
   "devDependencies": {
     "@effect-rx/rx-react": "0.38.0",
-    "@effect/platform": "0.89.0",
+    "@effect/platform": "0.90.2",
     "@types/react": "~18.2.0",
-    "effect": "3.17.0",
+    "effect": "3.17.7",
     "react": "~18.2.0",
     "typedoc": "0.28.1",
-    "@dxos/random": "0.8.4-main.b97322e",
-    "@dxos/echo-signals": "0.8.4-main.b97322e",
-    "@dxos/react-ui": "0.8.4-main.b97322e",
-    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.b97322e",
-    "@dxos/storybook-utils": "0.8.4-main.b97322e"
+    "@dxos/echo-signals": "0.8.4-main.dedc0f3",
+    "@dxos/random": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui": "0.8.4-main.dedc0f3",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.dedc0f3",
+    "@dxos/storybook-utils": "0.8.4-main.dedc0f3"
   },
   "peerDependencies": {
     "@effect-rx/rx-react": "^0.34.1",

package/src/common/capabilities.ts

@@ -2,44 +2,74 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type AiTool, type AiToolkit } from '@effect/ai';
 import { type Registry } from '@effect-rx/rx-react';
-import { type Schema } from 'effect';
+import { type Layer, type Schema } from 'effect';
 import { type FC, type PropsWithChildren } from 'react';
 
-import { type ExecutableTool } from '@dxos/ai';
-import { type GraphBuilder, type BuilderExtensions } from '@dxos/app-graph';
-import { type ArtifactDefinition } from '@dxos/blueprints';
+import { type BuilderExtensions, type GraphBuilder } from '@dxos/app-graph';
+import { type Blueprint } from '@dxos/blueprints';
 import { type Space } from '@dxos/client-protocol';
 import { type FunctionDefinition } from '@dxos/functions';
 import { type RootSettingsStore } from '@dxos/local-storage';
 import { type AnchoredTo } from '@dxos/schema';
 
+import { type PluginManager, defineCapability } from '../core';
+import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
+
 import { type FileInfo } from './file';
 import { type NodeSerializer } from './graph';
 import { type SurfaceDefinition } from './surface';
 import { type Resource } from './translations';
-import { type PluginManager, defineCapability } from '../core';
-import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
 
+// TODO(burdon): Sort.
 export namespace Capabilities {
+  /**
+   * @category Capability
+   */
   export const Null = defineCapability<null>('dxos.org/app-framework/capability/null');
 
+  /**
+   * @category Capability
+   */
   export const PluginManager = defineCapability<PluginManager>('dxos.org/app-framework/capability/plugin-manager');
 
+  /**
+   * @category Capability
+   */
   export const RxRegistry = defineCapability<Registry.Registry>('dxos.org/app-framework/capability/rx-registry');
 
   export type ReactContext = Readonly<{ id: string; dependsOn?: string[]; context: FC<PropsWithChildren> }>;
+
+  /**
+   * @category Capability
+   */
   export const ReactContext = defineCapability<ReactContext>('dxos.org/app-framework/capability/react-context');
 
   export type ReactRoot = Readonly<{ id: string; root: FC<PropsWithChildren> }>;
+
+  /**
+   * @category Capability
+   */
   export const ReactRoot = defineCapability<ReactRoot>('dxos.org/app-framework/capability/react-root');
 
   export type ReactSurface = SurfaceDefinition | readonly SurfaceDefinition[];
+
+  /**
+   * @category Capability
+   */
   export const ReactSurface = defineCapability<ReactSurface>('dxos.org/app-framework/common/react-surface');
 
   export type IntentResolver = AnyIntentResolver | readonly AnyIntentResolver[];
+
+  /**
+   * @category Capability
+   */
   export const IntentResolver = defineCapability<IntentResolver>('dxos.org/app-framework/capability/intent-resolver');
 
+  /**
+   * @category Capability
+   */
   export const IntentDispatcher = defineCapability<IntentContext>(
     'dxos.org/app-framework/capability/intent-dispatcher',
   );
@@ -66,23 +96,41 @@ export namespace Capabilities {
      */
     scrollIntoView: string | undefined;
   }>;
+
+  /**
+   * @category Capability
+   */
   export const Layout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
 
-  // TODO(burdon): Why array?
+  /**
+   * @category Capability
+   */
   export const Translations = defineCapability<Readonly<Resource[]>>('dxos.org/app-framework/capability/translations');
 
+  /**
+   * @category Capability
+   */
   export const AppGraph = defineCapability<Readonly<Pick<GraphBuilder, 'graph' | 'explore'>>>(
     'dxos.org/app-framework/capability/app-graph',
   );
 
+  /**
+   * @category Capability
+   */
   export const AppGraphBuilder = defineCapability<BuilderExtensions>(
     'dxos.org/app-framework/capability/app-graph-builder',
   );
 
+  /**
+   * @category Capability
+   */
   export const AppGraphSerializer = defineCapability<NodeSerializer[]>(
     'dxos.org/app-framework/capability/app-graph-serializer',
   );
 
+  /**
+   * @category Capability
+   */
   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.
@@ -93,26 +141,59 @@ export namespace Capabilities {
     schema: Schema.Schema.All;
     value?: Record<string, any>;
   };
+
+  /**
+   * @category Capability
+   */
   export const Settings = defineCapability<Settings>('dxos.org/app-framework/capability/settings');
 
   export type Metadata = Readonly<{ id: string; metadata: Record<string, any> }>;
+
+  /**
+   * @category Capability
+   */
   export const Metadata = defineCapability<Metadata>('dxos.org/app-framework/capability/metadata');
 
-  export const Tools = defineCapability<ExecutableTool[]>('dxos.org/app-framework/capability/tools');
-  export const ArtifactDefinition = defineCapability<ArtifactDefinition>(
-    'dxos.org/app-framework/capability/artifact-definition',
+  /**
+   * @category Capability
+   */
+  export const Toolkit = defineCapability<AiToolkit.Any>('dxos.org/app-framework/capability/ai-toolkit');
+
+  /**
+   * @category Capability
+   */
+  export const ToolkitHandler = defineCapability<Layer.Layer<AiTool.ToHandler<AiTool.AiTool<any>>, never, never>>(
+    'dxos.org/app-framework/capability/ai-toolkit-handler',
   );
 
+  /**
+   * @category Capability
+   */
+  export const BlueprintDefinition = defineCapability<Blueprint.Blueprint>(
+    'dxos.org/app-framework/capability/blueprint-definition',
+  );
+
+  /**
+   * @category Capability
+   */
   export const Functions = defineCapability<FunctionDefinition<any, any>[]>(
     'dxos.org/app-framework/capability/functions',
   );
 
   export type FileUploader = (file: File, space: Space) => Promise<FileInfo | undefined>;
+
+  /**
+   * @category Capability
+   */
   export const FileUploader = defineCapability<FileUploader>('dxos.org/app-framework/capability/file-uploader');
 
   type AnchorSort = {
     key: string;
     sort: (anchorA: AnchoredTo, anchorB: AnchoredTo) => number;
   };
+
+  /**
+   * @category Capability
+   */
   export const AnchorSort = defineCapability<AnchorSort>('dxos.org/app-framework/capability/anchor-sort');
 }

package/src/common/collaboration.ts

@@ -4,17 +4,14 @@
 
 import { Schema } from 'effect';
 
-import { Expando, Ref } from '@dxos/echo-schema';
+import { DataType } from '@dxos/schema';
 
 export namespace CollaborationActions {
-  export class InsertContent extends Schema.TaggedClass<InsertContent>()('assistant/intent-content', {
+  export class AcceptProposal extends Schema.TaggedClass<AcceptProposal>()('collaboration/accept-proposal', {
     input: Schema.Struct({
-      target: Expando,
-      object: Ref(Expando),
-      at: Schema.optional(Schema.String),
-      label: Schema.String.pipe(Schema.optional),
-    }).annotations({
-      description: 'Enables plugins to inject content blocks or references into a related entity.',
+      subject: Schema.Any,
+      anchor: Schema.String,
+      proposal: DataType.MessageBlock.Proposal,
     }),
     output: Schema.Void,
   }) {}

package/src/common/events.ts

@@ -2,9 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities } from './capabilities';
 import { defineEvent } from '../core';
 
+import { Capabilities } from './capabilities';
+
 export namespace Events {
   /**
    * Fired when the app is started.
@@ -48,6 +49,7 @@ export namespace Events {
   /**
    * Fired to load any newly available artifacts definitions.
    */
+  // TODO(burdon): Rename.
   export const SetupArtifactDefinition = defineEvent('dxos.org/app-framework/event/setup-artifact-definition');
 
   //

package/src/common/index.ts

@@ -6,7 +6,7 @@ export * from './capabilities';
 export * from './collaboration';
 export * from './events';
 export * from './file';
-export type * from './graph';
+export * from './graph';
 export * from './layout';
 export * from './surface';
 export * from './translations';

package/src/common/surface.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type JSX, type ForwardedRef, type PropsWithChildren, type ReactNode } from 'react';
+import { type ForwardedRef, type JSX, type PropsWithChildren, type ReactNode } from 'react';
 
 import { type GuardedType, type MakeOptional, type Position } from '@dxos/util';
 

package/src/components/App.stories.tsx

@@ -0,0 +1,35 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withTheme } from '@dxos/storybook-utils';
+
+import { useApp } from './useApp';
+
+const DefaultStory = () => {
+  const App = useApp({
+    placeholder: () => <div className='fixed inset-0 flex items-center justify-center'>Loading...</div>,
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/App',
+  render: DefaultStory,
+  decorators: [withTheme],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/components/App.tsx

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { Capabilities } from '../common';
+import { topologicalSort } from '../helpers';
+import { useCapabilities } from '../react';
+
+import { type UseAppOptions } from './useApp';
+import { LoadingState, useLoading } from './useLoading';
+
+export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
+  state: { ready: boolean; error: unknown };
+};
+
+export const App = ({ placeholder: Placeholder, state, debounce }: AppProps) => {
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
+  const stage = useLoading(state, debounce);
+
+  if (state.error) {
+    // This triggers the error boundary to provide UI feedback for the startup error.
+    throw state.error;
+  }
+
+  // TODO(wittjosiah): Consider using Suspense instead.
+  if (stage < LoadingState.Done) {
+    if (!Placeholder) {
+      return null;
+    }
+
+    return <Placeholder stage={stage} />;
+  }
+
+  const ComposedContext = composeContexts(reactContexts);
+  return (
+    <ComposedContext>
+      {reactRoots.map(({ id, root: Component }) => (
+        <Component key={id} />
+      ))}
+    </ComposedContext>
+  );
+};
+
+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>
+    ));
+};

package/src/components/DefaultFallback.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+/**
+ * NOTE: Default fallback should not use tailwind or theme.
+ */
+export const DefaultFallback = ({ error }: { error: Error }) => {
+  return (
+    <div
+      style={{
+        margin: '1rem',
+        padding: '1rem',
+        overflow: 'hidden',
+        border: '4px solid teal',
+        borderRadius: '1rem',
+      }}
+    >
+      {/* TODO(wittjosiah): Link to docs for replacing default. */}
+      <h1 style={{ margin: '0.5rem 0', fontSize: '1.2rem' }}>[ERROR]: {error.message}</h1>
+      <pre style={{ overflow: 'auto', fontSize: '1rem', whiteSpace: 'pre-wrap', color: '#888888' }}>{error.stack}</pre>
+    </div>
+  );
+};

package/src/components/index.ts

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

package/src/{App.tsx → components/useApp.tsx}

@@ -4,20 +4,22 @@
 
 import { RegistryContext } from '@effect-rx/rx-react';
 import { effect } from '@preact/signals-core';
-import React, { useCallback, useEffect, useMemo, useState, type FC, type PropsWithChildren } from 'react';
+import React, { type FC, useCallback, useEffect, useMemo } from 'react';
 
 import { invariant } from '@dxos/invariant';
 import { live } from '@dxos/live-object';
-import { useDefaultValue } from '@dxos/react-hooks';
+import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
 
-import { Capabilities, Events } from './common';
-import { PluginManager, type PluginManagerOptions, type Plugin } from './core';
-import { topologicalSort } from './helpers';
-import { ErrorBoundary, PluginManagerProvider, useCapabilities } from './react';
+import { Capabilities, Events } from '../common';
+import { type Plugin, PluginManager, type PluginManagerOptions } from '../core';
+import { ErrorBoundary, PluginManagerProvider } from '../react';
+
+import { App } from './App';
+import { DefaultFallback } from './DefaultFallback';
 
 const ENABLED_KEY = 'dxos.org/app-framework/enabled';
 
-export type CreateAppOptions = {
+export type UseAppOptions = {
   pluginManager?: PluginManager;
   pluginLoader?: PluginManagerOptions['pluginLoader'];
   plugins?: Plugin[];
@@ -27,6 +29,7 @@ export type CreateAppOptions = {
   fallback?: ErrorBoundary['props']['fallback'];
   cacheEnabled?: boolean;
   safeMode?: boolean;
+  debounce?: number;
 };
 
 /**
@@ -38,7 +41,7 @@ export type CreateAppOptions = {
  * const core = [LayoutPluginId];
  * const default = [MyPluginId];
  * const fallback = <div>Initializing Plugins...</div>;
- * const App = createApp({ plugins, core, default, fallback });
+ * const App = useApp({ plugins, core, default, fallback });
  * createRoot(document.getElementById('root')!).render(
  *   <StrictMode>
  *     <App />
@@ -64,7 +67,8 @@ export const useApp = ({
   fallback = DefaultFallback,
   cacheEnabled = false,
   safeMode = false,
-}: CreateAppOptions) => {
+  debounce = 0,
+}: UseAppOptions) => {
   const plugins = useDefaultValue(_plugins, () => []);
   const core = useDefaultValue(_core, () => plugins.map(({ meta }) => meta.id));
   const defaults = useDefaultValue(_defaults, () => []);
@@ -134,16 +138,12 @@ export const useApp = ({
     setupDevtools(manager);
   }, [manager]);
 
-  useEffect(() => {
-    const timeout = setTimeout(async () => {
-      await Promise.all([
-        // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
-        manager.activate(Events.SetupReactSurface),
-        manager.activate(Events.Startup),
-      ]);
-    });
-
-    return () => clearTimeout(timeout);
+  useAsyncEffect(async () => {
+    await Promise.all([
+      // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
+      manager.activate(Events.SetupReactSurface),
+      manager.activate(Events.Startup),
+    ]);
   }, [manager]);
 
   return useCallback(
@@ -151,7 +151,7 @@ export const useApp = ({
       <ErrorBoundary fallback={fallback}>
         <PluginManagerProvider value={manager}>
           <RegistryContext.Provider value={manager.registry}>
-            <App placeholder={placeholder} state={state} />
+            <App placeholder={placeholder} state={state} debounce={debounce} />
           </RegistryContext.Provider>
         </PluginManagerProvider>
       </ErrorBoundary>
@@ -160,116 +160,6 @@ export const useApp = ({
   );
 };
 
-const DELAY_PLACEHOLDER = 2_000;
-
-enum LoadingState {
-  Loading = 0,
-  FadeIn = 1,
-  FadeOut = 2,
-  Done = 3,
-}
-
-/**
- * To avoid "flashing" the placeholder, we wait a period of time before starting the loading animation.
- * If loading completes during this time the placehoder is not shown, otherwise is it displayed for a minimum period of time.
- *
- * States:
- * 0: Loading   - Wait for a period of time before starting the loading animation.
- * 1: Fade-in   - Display a loading animation.
- * 2: Fade-out  - Fade out the loading animation.
- * 3: Done      - Remove the placeholder.
- */
-const useLoading = (state: AppProps['state']) => {
-  const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
-  useEffect(() => {
-    const i = setInterval(() => {
-      setStage((tick) => {
-        switch (tick) {
-          case LoadingState.Loading:
-            if (!state.ready) {
-              return LoadingState.FadeIn;
-            } else {
-              clearInterval(i);
-              return LoadingState.Done;
-            }
-          case LoadingState.FadeIn:
-            if (state.ready) {
-              return LoadingState.FadeOut;
-            }
-            break;
-          case LoadingState.FadeOut:
-            clearInterval(i);
-            return LoadingState.Done;
-        }
-
-        return tick;
-      });
-    }, DELAY_PLACEHOLDER);
-
-    return () => clearInterval(i);
-  }, []);
-
-  return stage;
-};
-
-type AppProps = Pick<CreateAppOptions, 'placeholder'> & {
-  state: { ready: boolean; error: unknown };
-};
-
-const App = ({ placeholder: Placeholder, state }: AppProps) => {
-  const reactContexts = useCapabilities(Capabilities.ReactContext);
-  const reactRoots = useCapabilities(Capabilities.ReactRoot);
-  const stage = useLoading(state);
-
-  if (state.error) {
-    // This triggers the error boundary to provide UI feedback for the startup error.
-    throw state.error;
-  }
-
-  // TODO(wittjosiah): Consider using Suspense instead?
-  if (stage < LoadingState.Done) {
-    if (!Placeholder) {
-      return null;
-    }
-
-    return <Placeholder stage={stage} />;
-  }
-
-  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={{ margin: '0.5rem', padding: '1rem', overflow: 'hidden', border: '1px solid red' }}>
-      {/* TODO(wittjosiah): Link to docs for replacing default. */}
-      <h1 style={{ margin: '0.5rem 0', fontSize: '1.2rem' }}>[ERROR]: {error.message}</h1>
-      <pre style={{ overflow: 'auto', fontSize: '1rem', whiteSpace: 'pre-wrap', color: '#888888' }}>{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;