@dxos/app-framework 0.8.2-main.f11618f → 0.8.2-staging.42af850

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

@@ -1 +1 @@
-{"version":3,"file":"useIntentResolver.d.ts","sourceRoot":"","sources":["../../../../src/react/useIntentResolver.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,eAAO,MAAM,iBAAiB,WAAY,MAAM,YAAY,iBAAiB,SAW5E,CAAC"}
+{"version":3,"file":"useIntentResolver.d.ts","sourceRoot":"","sources":["../../../../src/react/useIntentResolver.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,EAAE,UAAU,iBAAiB,SAW5E,CAAC"}

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

@@ -1,12 +1,16 @@
 import { type Decorator } from '@storybook/react';
 import { type CreateAppOptions } from '../App';
-import { type ActivationEvent, type AnyCapability } from '../core';
+import { type ActivationEvent, type AnyCapability, type PluginContext } from '../core';
+export type Provider<C, R> = (context: C) => R;
+export type ProviderOrValue<C, R> = Provider<C, R> | R;
+export declare const getValue: <C, R>(providerOrValue: ProviderOrValue<C, R>, context: C) => R;
 export type WithPluginManagerOptions = CreateAppOptions & {
-    capabilities?: AnyCapability[];
+    capabilities?: ProviderOrValue<PluginContext, AnyCapability[]>;
     fireEvents?: (ActivationEvent | string)[];
 };
 /**
  * Wraps a story with a plugin manager.
+ * NOTE: This builds up and tears down the plugin manager on every render.
  */
 export declare const withPluginManager: (options?: WithPluginManagerOptions) => Decorator;
 //# sourceMappingURL=withPluginManager.d.ts.map

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

@@ -1 +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,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAKnB,MAAM,SAAS,CAAC;AA+BjB,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,GAAG;IACxD,YAAY,CAAC,EAAE,aAAa,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,CAAC,eAAe,GAAG,MAAM,CAAC,EAAE,CAAC;CAC3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,aAAa,wBAAwB,KAAQ,SAyB1E,CAAC"}
+{"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,EAAU,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEvD,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,aAAa,EAElB,KAAK,aAAa,EACnB,MAAM,SAAS,CAAC;AAGjB,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;AAC/C,MAAM,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;AACvD,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,iBAAiB,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,KAAG,CAEnF,CAAC;AA+BF,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,GAAG;IACxD,YAAY,CAAC,EAAE,eAAe,CAAC,aAAa,EAAE,aAAa,EAAE,CAAC,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,eAAe,GAAG,MAAM,CAAC,EAAE,CAAC;CAC3C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAS,wBAA6B,KAAG,SAmC1E,CAAC"}

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

@@ -1 +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"}
+{"version":3,"file":"withPluginManager.stories.d.ts","sourceRoot":"","sources":["../../../../src/testing/withPluginManager.stories.tsx"],"names":[],"mappings":"AAMA,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

@@ -1 +1 @@
-{"version":"5.7.3"}
+{"version":"5.8.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-framework",
-  "version": "0.8.2-main.f11618f",
+  "version": "0.8.2-staging.42af850",
   "description": "A framework for building applications from composible plugins.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -37,34 +37,41 @@
     }
   },
   "dependencies": {
-    "@preact/signals-core": "^1.6.0",
-    "@dxos/app-graph": "0.8.2-main.f11618f",
-    "@dxos/artifact": "0.8.2-main.f11618f",
-    "@dxos/async": "0.8.2-main.f11618f",
-    "@dxos/client-protocol": "0.8.2-main.f11618f",
-    "@dxos/echo-schema": "0.8.2-main.f11618f",
-    "@dxos/invariant": "0.8.2-main.f11618f",
-    "@dxos/local-storage": "0.8.2-main.f11618f",
-    "@dxos/live-object": "0.8.2-main.f11618f",
-    "@dxos/log": "0.8.2-main.f11618f",
-    "@dxos/debug": "0.8.2-main.f11618f",
-    "@dxos/react-hooks": "0.8.2-main.f11618f",
-    "@dxos/util": "0.8.2-main.f11618f"
+    "@preact/signals-core": "^1.9.0",
+    "@dxos/ai": "0.8.2-staging.42af850",
+    "@dxos/app-graph": "0.8.2-staging.42af850",
+    "@dxos/client-protocol": "0.8.2-staging.42af850",
+    "@dxos/artifact": "0.8.2-staging.42af850",
+    "@dxos/async": "0.8.2-staging.42af850",
+    "@dxos/invariant": "0.8.2-staging.42af850",
+    "@dxos/echo-schema": "0.8.2-staging.42af850",
+    "@dxos/debug": "0.8.2-staging.42af850",
+    "@dxos/keys": "0.8.2-staging.42af850",
+    "@dxos/local-storage": "0.8.2-staging.42af850",
+    "@dxos/live-object": "0.8.2-staging.42af850",
+    "@dxos/log": "0.8.2-staging.42af850",
+    "@dxos/react-hooks": "0.8.2-staging.42af850",
+    "@dxos/schema": "0.8.2-staging.42af850",
+    "@dxos/util": "0.8.2-staging.42af850"
   },
   "devDependencies": {
+    "@effect-rx/rx-react": "^0.34.1",
+    "@effect/platform": "0.80.12",
     "@phosphor-icons/react": "^2.1.5",
     "@types/react": "~18.2.0",
-    "effect": "3.13.3",
+    "effect": "3.14.21",
     "react": "~18.2.0",
     "typedoc": "0.28.1",
-    "@dxos/echo-signals": "0.8.2-main.f11618f",
-    "@dxos/random": "0.8.2-main.f11618f",
-    "@dxos/react-ui": "0.8.2-main.f11618f",
-    "@dxos/react-ui-syntax-highlighter": "0.8.2-main.f11618f",
-    "@dxos/storybook-utils": "0.8.2-main.f11618f"
+    "@dxos/echo-signals": "0.8.2-staging.42af850",
+    "@dxos/random": "0.8.2-staging.42af850",
+    "@dxos/react-ui-syntax-highlighter": "0.8.2-staging.42af850",
+    "@dxos/react-ui": "0.8.2-staging.42af850",
+    "@dxos/storybook-utils": "0.8.2-staging.42af850"
   },
   "peerDependencies": {
-    "effect": "3.13.3",
+    "@effect-rx/rx-react": "^0.34.1",
+    "@effect/platform": "0.80.12",
+    "effect": "^3.13.3",
     "react": "~18.2.0"
   },
   "publishConfig": {

package/src/App.tsx

@@ -2,11 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
+import { RegistryContext } from '@effect-rx/rx-react';
 import { effect } from '@preact/signals-core';
-import React, { useEffect, useState, type FC, type PropsWithChildren } from 'react';
+import React, { useCallback, useEffect, useMemo, useState, type FC, type PropsWithChildren } from 'react';
 
 import { invariant } from '@dxos/invariant';
 import { live } from '@dxos/live-object';
+import { useDefaultValue } from '@dxos/react-hooks';
 
 import { Capabilities, Events } from './common';
 import { PluginManager, type PluginManagerOptions, type Plugin } from './core';
@@ -24,6 +26,7 @@ export type CreateAppOptions = {
   placeholder?: FC<{ stage: number }>;
   fallback?: ErrorBoundary['props']['fallback'];
   cacheEnabled?: boolean;
+  safeMode?: boolean;
 };
 
 /**
@@ -49,64 +52,111 @@ export type CreateAppOptions = {
  * @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.
+ * @param params.safeMode Whether to enable safe mode, which disables optional plugins.
  */
-export const createApp = ({
+export const useApp = ({
   pluginManager,
   pluginLoader: _pluginLoader,
-  plugins = [],
-  core = plugins.map(({ meta }) => meta.id),
-  defaults = [],
+  plugins: _plugins,
+  core: _core,
+  defaults: _defaults,
   placeholder,
   fallback = DefaultFallback,
   cacheEnabled = false,
+  safeMode = false,
 }: CreateAppOptions) => {
+  const plugins = useDefaultValue(_plugins, () => []);
+  const core = useDefaultValue(_core, () => plugins.map(({ meta }) => meta.id));
+  const defaults = useDefaultValue(_defaults, () => []);
+
   // 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 pluginLoader = useMemo(
+    () =>
+      _pluginLoader ??
+      ((id: string) => {
+        const plugin = plugins.find((plugin) => plugin.meta.id === id);
+        invariant(plugin, `Plugin not found: ${id}`);
+        return plugin;
+      }),
+    [_pluginLoader, plugins],
+  );
+
+  const state = useMemo(() => live({ ready: false, error: null }), []);
+  const cached: string[] = useMemo(() => JSON.parse(localStorage.getItem(ENABLED_KEY) ?? '[]'), []);
+  const enabled = useMemo(
+    () => (safeMode ? [] : cacheEnabled && cached.length > 0 ? cached : defaults),
+    [safeMode, cacheEnabled, cached, defaults],
+  );
+  const manager = useMemo(
+    () => pluginManager ?? new PluginManager({ pluginLoader, plugins, core, enabled }),
+    [pluginManager, pluginLoader, plugins, core, enabled],
+  );
+
+  useEffect(() => {
+    return 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;
+      }
     });
+  }, [manager, state]);
 
-  const state = live({ 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 });
+  useEffect(() => {
+    effect(() => {
+      cacheEnabled && localStorage.setItem(ENABLED_KEY, JSON.stringify(manager.enabled));
+    });
+  }, [cacheEnabled, manager]);
 
-  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';
-    }
+  useEffect(() => {
+    manager.context.contributeCapability({
+      interface: Capabilities.PluginManager,
+      implementation: manager,
+      module: 'dxos.org/app-framework/plugin-manager',
+    });
 
-    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',
-  });
-
-  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 () => (
-    <ErrorBoundary fallback={fallback}>
-      <PluginManagerProvider value={manager}>
-        <App placeholder={placeholder} state={state} />
-      </PluginManagerProvider>
-    </ErrorBoundary>
+    manager.context.contributeCapability({
+      interface: Capabilities.RxRegistry,
+      implementation: manager.registry,
+      module: 'dxos.org/app-framework/rx-registry',
+    });
+
+    return () => {
+      manager.context.removeCapability(Capabilities.PluginManager, manager);
+      manager.context.removeCapability(Capabilities.RxRegistry, manager.registry);
+    };
+  }, [manager]);
+
+  useEffect(() => {
+    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);
+  }, [manager]);
+
+  return useCallback(
+    () => (
+      <ErrorBoundary fallback={fallback}>
+        <PluginManagerProvider value={manager}>
+          <RegistryContext.Provider value={manager.registry}>
+            <App placeholder={placeholder} state={state} />
+          </RegistryContext.Provider>
+        </PluginManagerProvider>
+      </ErrorBoundary>
+    ),
+    [fallback, manager, placeholder, state],
   );
 };
 

package/src/common/capabilities.ts

@@ -2,19 +2,22 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema as S } from 'effect';
+import { type Registry } from '@effect-rx/rx-react';
+import { type Schema } from 'effect';
 import { type FC, type PropsWithChildren } from 'react';
 
-import { type GraphBuilder } from '@dxos/app-graph';
-import { type ArtifactDefinition, type Tool } from '@dxos/artifact';
+import { type ExecutableTool } from '@dxos/ai';
+import { type GraphBuilder, type BuilderExtensions } from '@dxos/app-graph';
+import { type ArtifactDefinition } from '@dxos/artifact';
 import { type Space } from '@dxos/client-protocol';
 import { type RootSettingsStore } from '@dxos/local-storage';
+import { type AnchoredTo } from '@dxos/schema';
 
 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 PluginManager, defineCapability } from '../core';
 import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
 
 export namespace Capabilities {
@@ -22,6 +25,8 @@ export namespace Capabilities {
 
   export const Null = defineCapability<null>('dxos.org/app-framework/capability/null');
 
+  export const RxRegistry = defineCapability<Registry.Registry>('dxos.org/app-framework/capability/rx-registry');
+
   export type ReactContext = Readonly<{ id: string; dependsOn?: string[]; context: FC<PropsWithChildren> }>;
   export const ReactContext = defineCapability<ReactContext>('dxos.org/app-framework/capability/react-context');
 
@@ -68,7 +73,7 @@ export namespace Capabilities {
     'dxos.org/app-framework/capability/app-graph',
   );
 
-  export const AppGraphBuilder = defineCapability<Parameters<GraphBuilder['addExtension']>[0]>(
+  export const AppGraphBuilder = defineCapability<BuilderExtensions>(
     'dxos.org/app-framework/capability/app-graph-builder',
   );
 
@@ -82,7 +87,7 @@ export namespace Capabilities {
   // export type Settings = Parameters<RootSettingsStore['createStore']>[0];
   // export type Settings<T extends SettingsValue = SettingsValue> = SettingsProps<T>;
   export type Settings = {
-    schema: S.Schema.All;
+    schema: Schema.Schema.All;
     prefix: string;
     value?: Record<string, any>;
   };
@@ -91,11 +96,17 @@ export namespace Capabilities {
   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 Tools = defineCapability<ExecutableTool[]>('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');
+
+  type AnchorSort = {
+    key: string;
+    sort: (anchorA: AnchoredTo, anchorB: AnchoredTo) => number;
+  };
+  export const AnchorSort = defineCapability<AnchorSort>('dxos.org/app-framework/capability/anchor-sort');
 }

package/src/common/collaboration.ts

@@ -2,20 +2,20 @@
 // Copyright 2025 DXOS.org
 //
 
-import { SchemaAST as AST, Schema as S } from 'effect';
+import { Schema } from 'effect';
 
-import { Expando, Ref, SpaceIdSchema } from '@dxos/echo-schema';
+import { Expando, Ref } from '@dxos/echo-schema';
 
 export namespace CollaborationActions {
-  export class InsertContent extends S.TaggedClass<InsertContent>()('assistant/intent-content', {
-    input: S.Struct({
-      spaceId: SpaceIdSchema,
-      target: Ref(Expando),
+  export class InsertContent extends Schema.TaggedClass<InsertContent>()('assistant/intent-content', {
+    input: Schema.Struct({
+      target: Expando,
       object: Ref(Expando),
-      label: S.String.pipe(S.optional),
+      at: Schema.optional(Schema.String),
+      label: Schema.String.pipe(Schema.optional),
     }).annotations({
-      [AST.DescriptionAnnotationId]: 'Enables plugins to inject content blocks or references into a related entity.',
+      description: 'Enables plugins to inject content blocks or references into a related entity.',
     }),
-    output: S.Void,
+    output: Schema.Void,
   }) {}
 }

package/src/common/file.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema as S } from 'effect';
+import { Schema } from 'effect';
 
 // TODO(burdon): See Accept attribute (uses MIME types).
 // E.g., 'image/*': ['.jpg', '.jpeg', '.png', '.gif'],
@@ -12,11 +12,11 @@ export const defaultFileTypes = {
   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 const FileInfoSchema = Schema.Struct({
+  name: Schema.String,
+  type: Schema.String,
+  url: Schema.optional(Schema.String),
+  cid: Schema.optional(Schema.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>;
+export type FileInfo = Schema.Schema.Type<typeof FileInfoSchema>;