@dxos/app-framework 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/src/ui/hooks/useApp.tsx

@@ -12,36 +12,76 @@ import React, { type FC, useCallback, useEffect, useMemo, useRef, useState } fro
 import { runAndForwardErrors } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
+import { ErrorBoundary, ErrorFallback, type FallbackProps } from '@dxos/react-error-boundary';
 import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
 import { ContextProtocolProvider } from '@dxos/web-context-react';
 
 import { ActivationEvents, Capabilities } from '../../common';
 import { PluginManagerContext } from '../../context';
 import { type ActivationEvent, type Plugin, PluginManager } from '../../core';
-import { App } from '../components/App';
-import { DefaultFallback } from '../components/DefaultFallback';
-import { ErrorBoundary } from '../components/ErrorBoundary';
-import { PluginManagerProvider } from '../components/PluginManagerProvider';
+import { App, PluginManagerProvider } from '../components';
 
-const ENABLED_KEY = 'dxos.org/app-framework/enabled';
+const ENABLED_KEY = 'org.dxos.app-framework.enabled';
+
+export type StartupProgress = {
+  /** Number of modules that have been activated. */
+  activated: number;
+  /** Total number of modules registered. */
+  total: number;
+  /** Fractional progress (0-1). */
+  progress: number;
+  /**
+   * Raw activation event key (e.g. `org.dxos.app-framework.event.startup`).
+   * Set on event-level transitions, *and* on module-level transitions where
+   * it carries the parent activation event that first triggered the
+   * module's load (plumbed through `_loadCapabilitiesForModules` →
+   * `_loadModule`). Consumers can use this either as the primary id (when
+   * {@link module} is absent) or as an extra "context" field alongside
+   * {@link module}.
+   */
+  event?: string;
+  /**
+   * Raw module id (e.g. `org.dxos.plugin.observability.module.ReactSurface`)
+   * when the in-flight activation is module-level. When present,
+   * {@link event} may also be set, identifying the parent activation that
+   * triggered this module's load.
+   */
+  module?: string;
+  /**
+   * Pre-humanized label for the currently surfaced transition (module
+   * label if {@link module} is set, otherwise the event label), supplied
+   * for consumers that want a sensible default. Hosts that prefer to
+   * render their own label can read the raw {@link event}/{@link module}
+   * fields and ignore this — the framework leaves the policy choice
+   * (which transitions to surface, how to format them, whether to drop
+   * sub-modules entirely) to the host's `Placeholder`.
+   */
+  humanizedName?: string;
+};
+
+export type PlaceholderProps = {
+  stage?: number;
+  progress?: StartupProgress;
+};
 
 export type UseAppOptions = {
   pluginManager?: PluginManager.PluginManager;
   pluginLoader?: PluginManager.ManagerOptions['pluginLoader'];
+  onPluginRemove?: PluginManager.ManagerOptions['onRemove'];
+  pluginRegistryProvider?: PluginManager.ManagerOptions['pluginRegistryProvider'];
   plugins?: Plugin.Plugin[];
-  core?: string[];
   defaults?: string[];
   /**
    * Additional activation events to fire before startup.
    * These are fired alongside SetupReactSurface before the Startup event.
    */
   setupEvents?: ActivationEvent.ActivationEvent[];
-  placeholder?: FC<{ stage: number }>;
-  fallback?: ErrorBoundary['props']['fallback'];
   cacheEnabled?: boolean;
   safeMode?: boolean;
   debounce?: number;
   timeout?: number;
+  fallback?: FC<FallbackProps>;
+  placeholder?: FC<PlaceholderProps>;
 };
 
 /**
@@ -50,10 +90,9 @@ export type UseAppOptions = {
  *
  * @example
  * const plugins = [LayoutPlugin(), MyPlugin()];
- * const core = [LayoutPluginId];
- * const default = [MyPluginId];
- * const fallback = <div>Initializing Plugins...</div>;
- * const App = useApp({ plugins, core, default, fallback });
+ * const defaults = [MyPluginId];
+ * const fallback = () => <div>Initializing Plugins...</div>;
+ * const App = useApp({ plugins, defaults, fallback });
  * createRoot(document.getElementById('root')!).render(
  *   <StrictMode>
  *     <App />
@@ -61,34 +100,32 @@ export type UseAppOptions = {
  * );
  *
  * @param params.pluginLoader A function which loads new plugins.
- * @param params.plugins All plugins available to the application.
- * @param params.core Core plugins which will always be enabled.
+ * @param params.plugins All plugins available to the application. Plugins whose `meta.tags` includes `'system'` are treated as core (force-enabled, not user-toggleable).
  * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
- * @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.
+ * @param params.fallback Fallback component to render if an error occurs during startup.
+ * @param params.placeholder Placeholder component to render during startup.
  */
 export const useApp = ({
   pluginManager,
   pluginLoader: pluginLoaderProp,
+  onPluginRemove,
+  pluginRegistryProvider,
   plugins: pluginsProp,
-  core: coreProp,
   defaults: defaultsProp,
   setupEvents: setupEventsProp,
   placeholder,
-  fallback = DefaultFallback,
+  fallback = ErrorFallback,
   cacheEnabled = false,
   safeMode = false,
   debounce = 0,
   timeout = 30_000,
 }: UseAppOptions) => {
   const plugins = useDefaultValue(pluginsProp, () => []);
-  const core = useDefaultValue(coreProp, () => plugins.map(({ meta }) => meta.id));
   const defaults = useDefaultValue(defaultsProp, () => []);
   const setupEvents = useDefaultValue(setupEventsProp, () => []);
 
-  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
   const pluginLoader = useMemo(
     () =>
       pluginLoaderProp ??
@@ -96,7 +133,7 @@ export const useApp = ({
         Effect.sync(() => {
           const plugin = plugins.find((plugin) => plugin.meta.id === id);
           invariant(plugin, `Plugin not found: ${id}`);
-          return plugin;
+          return { plugin };
         })),
     [pluginLoaderProp, plugins],
   );
@@ -105,16 +142,31 @@ export const useApp = ({
   const [ready, setReady] = useState(false);
   const errorRef = useRef<unknown>(null);
   const [error, setError] = useState<unknown>(null);
+  const [startupProgress, setStartupProgress] = useState<StartupProgress>({
+    activated: 0,
+    total: 0,
+    progress: 0,
+  });
   // TODO(wittjosiah): Migrate to Atom.kvs for isomorphic storage.
   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 ?? PluginManager.make({ pluginLoader, plugins, core, enabled }),
-    [pluginManager, pluginLoader, plugins, core, enabled],
-  );
+  const isExternalManager = !!pluginManager;
+  const manager = useMemo(() => {
+    const mgr =
+      pluginManager ??
+      PluginManager.make({
+        pluginLoader,
+        plugins,
+        enabled,
+        onRemove: onPluginRemove,
+        pluginRegistryProvider,
+      });
+    log('useApp: useMemo created/reused manager', { provided: !!pluginManager });
+    return mgr;
+  }, [pluginManager, pluginLoader, plugins, enabled, onPluginRemove, pluginRegistryProvider]);
 
   useEffect(() => {
     if (!cacheEnabled) {
@@ -130,28 +182,103 @@ export const useApp = ({
   }, [manager]);
 
   useAsyncEffect(async () => {
+    log('useApp: effect mount');
+
     manager.capabilities.contribute({
       interface: Capabilities.PluginManager,
       implementation: manager,
-      module: 'dxos.org/app-framework/plugin-manager',
+      module: 'org.dxos.app-framework.plugin-manager',
     });
 
     manager.capabilities.contribute({
       interface: Capabilities.AtomRegistry,
       implementation: manager.registry,
-      module: 'dxos.org/app-framework/atom-registry',
+      module: 'org.dxos.app-framework.atom-registry',
     });
 
     const fiber = Effect.gen(function* () {
       const queue = yield* PubSub.subscribe(manager.activation);
       const listener = yield* Effect.forkDaemon(
         Queue.take(queue).pipe(
-          Effect.tap(({ event, state, error: error$ }) =>
+          Effect.tap(({ event, state, module, error: error$ }) =>
             Effect.sync(() => {
-              if (event === ActivationEvents.Startup.id && state === 'activated') {
+              // Event-level Startup activated (no `module` field) fires once,
+              // after every module triggered by Startup has finished. Module
+              // activations now also carry their parent event id (so the trace
+              // can attribute a module to its triggering event), which means
+              // each module activated under Startup publishes
+              // `{ event: 'startup', state: 'activated', module: <id> }`. Without
+              // the `!module` guard the listener would mark the app ready on
+              // the *first* such module rather than waiting for the event-level
+              // completion — leaving downstream capabilities (operation-invoker,
+              // app-graph, …) un-registered when the placeholder dismisses.
+              if (event === ActivationEvents.Startup.id && state === 'activated' && !module) {
                 clearTimeout(timeoutId);
                 setReady(true);
                 readyRef.current = true;
+                // Trigger startup profiler dump if available.
+                (globalThis as any).composer?.profiler?.dump();
+                // Notify any host observability layer that startup completed.
+                // A `CustomEvent` keeps this generic — app-framework doesn't
+                // import a provider, and consumers can capture the startup
+                // summary without us picking one.
+                if (typeof window !== 'undefined') {
+                  window.dispatchEvent(new CustomEvent('app-framework:startup-activated'));
+                }
+                return;
+              }
+              // `activating` is the start-of-load signal. Surface the raw
+              // `module` (or `event`) plus a pre-humanized label so the
+              // host placeholder can decide what to render — show
+              // everything, suppress noisy sub-modules, group by plugin,
+              // or apply its own formatting. We intentionally do NOT touch
+              // these fields on `activated`: pairing the two would cause
+              // back-to-back identical updates to the host's effect, which
+              // the boot loader treats as a re-trigger because
+              // `progress.progress` moved. Leaving the label alone on
+              // completion keeps it accurate ("now activating X") until
+              // the next module starts.
+              if (module && state === 'activating' && !readyRef.current) {
+                setStartupProgress((current) => ({
+                  ...current,
+                  // `event` here is the activation event that first
+                  // triggered this module load (plumbed through
+                  // `_loadCapabilitiesForModules` → `_loadModule`).
+                  // Falsy/empty falls back to undefined so consumers can
+                  // tell "no parent context" from "parent context: <X>".
+                  event: event || undefined,
+                  module,
+                  humanizedName: humanizeModuleId(module),
+                }));
+              }
+              // Update the activation count when a module commits. The
+              // ring's fraction comes from this; `event`/`module`/
+              // `humanizedName` were set by the matching `activating`
+              // message above and are left alone so the count can advance
+              // without re-firing the host's status callback.
+              if (module && state === 'activated' && !readyRef.current) {
+                const active = manager.getActive();
+                const total = manager.getModules().length;
+                setStartupProgress((current) => ({
+                  ...current,
+                  activated: active.length,
+                  total,
+                  progress: total > 0 ? active.length / total : 0,
+                }));
+              }
+              // Event-level `activating` (no `module`) — fired at the start
+              // of `_activateModulesForEvent` and recursively for each
+              // before/after event. Surfaces a label during the gap before
+              // the first module-level message lands; subsequent module
+              // updates immediately overwrite this with a more specific
+              // label.
+              if (event && !module && state === 'activating' && !readyRef.current) {
+                setStartupProgress((current) => ({
+                  ...current,
+                  event,
+                  module: undefined,
+                  humanizedName: humanizeEventKey(event),
+                }));
               }
               if (error$ && !readyRef.current) {
                 setError(error$);
@@ -186,20 +313,31 @@ export const useApp = ({
     }, timeout);
 
     return () => {
+      log('useApp: effect cleanup');
       clearTimeout(timeoutId);
       void runAndForwardErrors(Fiber.interrupt(fiber));
-      manager.capabilities.remove(Capabilities.PluginManager, manager);
-      manager.capabilities.remove(Capabilities.AtomRegistry, manager.registry);
+      if (!isExternalManager) {
+        void runAndForwardErrors(manager.shutdown());
+      }
     };
   }, [manager]);
 
+  const progressRef = useRef(startupProgress);
+  progressRef.current = startupProgress;
+
   return useCallback(
     () => (
-      <ErrorBoundary fallback={fallback}>
+      <ErrorBoundary name='app' FallbackComponent={fallback}>
         <PluginManagerProvider value={manager}>
           <ContextProtocolProvider value={manager} context={PluginManagerContext}>
             <RegistryContext.Provider value={manager.registry}>
-              <App placeholder={placeholder} ready={ready} error={error} debounce={debounce} />
+              <App
+                placeholder={placeholder}
+                ready={ready}
+                error={error}
+                debounce={debounce}
+                progress={progressRef.current}
+              />
             </RegistryContext.Provider>
           </ContextProtocolProvider>
         </PluginManagerProvider>
@@ -213,3 +351,68 @@ const setupDevtools = (manager: PluginManager.PluginManager) => {
   (globalThis as any).composer ??= {};
   (globalThis as any).composer.manager = manager;
 };
+
+/**
+ * Extracts a human-readable label from a module ID.
+ *
+ * Module IDs follow `org.dxos.plugin.<plugin-slug>.module.<module-name>`,
+ * where `<plugin-slug>` is kebab-case and `<module-name>` is either an
+ * explicit string (often kebab-case, e.g. `'observability'`, `'namespace'`)
+ * or a capability tag in PascalCase from `Capability.getModuleTag(...)`
+ * (e.g. `'ReactSurface'`, `'AppGraphBuilder'`). The output is
+ * `"Title Case Plugin: kebab-module"` so the visible status names both the
+ * plugin and the aspect being activated, helping disambiguate the multiple
+ * modules a plugin contributes.
+ *
+ * Examples:
+ *   - "org.dxos.plugin.markdown.module.ReactSurface" → "Markdown: react-surface"
+ *   - "org.dxos.plugin.observability.module.AppGraphBuilder" → "Observability: app-graph-builder"
+ *   - "org.dxos.plugin.observability.module.observability" → "Observability"
+ *     (the module name matches the plugin slug — collapsed to avoid
+ *     "Observability: observability" noise.)
+ */
+const humanizeModuleId = (moduleId: string): string => {
+  const match = moduleId.match(/\.plugin\.([^.]+)\.module\.(.+)$/);
+  if (!match) {
+    // Fallback: use the last segment.
+    const parts = moduleId.split('.');
+    return parts[parts.length - 1];
+  }
+  const [, pluginSlug, moduleName] = match;
+  const pluginLabel = pluginSlug
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+  // Normalise the module name to kebab-case so PascalCase capability tags
+  // ("ReactSurface") read consistently with explicit kebab IDs
+  // ("operation-handler"). The two-step substitution handles consecutive
+  // uppercase runs (`URLLoader` → `url-loader`) without splitting them
+  // mid-acronym.
+  const moduleLabel = moduleName
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase();
+  // Capability modules whose name matches the plugin slug (e.g. the
+  // observability plugin's `observability` capability module) would render
+  // as "Observability: observability" — drop the redundant suffix.
+  if (moduleLabel === pluginSlug) {
+    return pluginLabel;
+  }
+  return `${pluginLabel}: ${moduleLabel}`;
+};
+
+/**
+ * Extracts a human-readable label from an activation event key.
+ * E.g., "org.dxos.app-framework.event.setup-react-surface" → "Setup React Surface".
+ */
+const humanizeEventKey = (eventKey: string): string => {
+  // Strip a leading specifier (composite key form: "<id>:<specifier>").
+  const id = eventKey.split(':')[0];
+  // Match the trailing segment after `.event.`.
+  const match = id.match(/\.event\.(.+)$/);
+  const slug = match ? match[1] : (id.split('.').pop() ?? id);
+  return slug
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+};

package/src/ui/hooks/useCapabilities.ts

@@ -9,7 +9,7 @@ import { invariant } from '@dxos/invariant';
 
 import { Capabilities } from '../../common';
 import { type Capability } from '../../core';
-import { usePluginManager } from '../components/PluginManagerProvider';
+import { usePluginManager } from '../components';
 
 /**
  * Hook to request capabilities from the plugin context.
@@ -25,6 +25,7 @@ export const useCapabilities = <T>(interfaceDef: Capability.InterfaceDef<T>) =>
  * @returns The capability.
  * @throws If no capability is found.
  */
+// TODO(burdon): Option not to throw?
 export const useCapability = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
   const capabilities = useCapabilities(interfaceDef);
   invariant(capabilities.length > 0, `No capability found for ${interfaceDef.identifier}`);

package/src/ui/hooks/useLoading.tsx

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 export enum LoadingState {
   Loading = 0,
@@ -23,6 +23,14 @@ export enum LoadingState {
  */
 export const useLoading = (ready: boolean, debounce = 0) => {
   const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
+  // Mirror `ready` into a ref so the interval's `setStage` callback can read
+  // the latest value without depending on the effect re-running. The pure
+  // closure-capture pattern (with `ready` in deps) sticks the FSM at
+  // `FadeIn` whenever HMR doesn't propagate the dep change end-to-end —
+  // a ref sidesteps that entirely and fires the read on every tick.
+  const readyRef = useRef(ready);
+  readyRef.current = ready;
+
   useEffect(() => {
     if (!debounce) {
       return;
@@ -30,18 +38,18 @@ export const useLoading = (ready: boolean, debounce = 0) => {
 
     const i = setInterval(() => {
       setStage((stage) => {
+        const isReady = readyRef.current;
         switch (stage) {
           case LoadingState.Loading: {
-            if (!ready) {
+            if (!isReady) {
               return LoadingState.FadeIn;
-            } else {
-              clearInterval(i);
-              return LoadingState.Done;
             }
+            clearInterval(i);
+            return LoadingState.Done;
           }
 
           case LoadingState.FadeIn: {
-            if (ready) {
+            if (isReady) {
               return LoadingState.FadeOut;
             }
             break;

package/src/ui/hooks/useProcessManagerRuntime.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { type DependencyList, use, useCallback, useMemo } from 'react';
+
+import { Operation, ServiceResolver } from '@dxos/compute';
+import { unwrapExit } from '@dxos/effect';
+import type { SpaceId } from '@dxos/keys';
+
+import { Capabilities } from '../../common';
+import { useCapability } from './useCapabilities';
+
+/**
+ * Resolve the shared {@link Capabilities.ProcessManagerRuntime} from the plugin context.
+ */
+export const useProcessManagerRuntime = (): Capabilities.ProcessManagerRuntime =>
+  useCapability(Capabilities.ProcessManagerRuntime);
+
+/**
+ * Build a callback that runs an effect on the {@link Capabilities.ProcessManagerRuntime}
+ * with space-scoped services resolved via {@link ServiceResolver.provide}.
+ *
+ * The `tags` tuple must list every service the effect requires (beyond the
+ * fixed {@link Capabilities.ProcessManagerRuntimeServices}); these services are
+ * resolved for the given `spaceId` through the runtime's service resolver.
+ *
+ * Nested `Operation.invoke` / `Operation.schedule` calls within the effect
+ * inherit `spaceId` as a default {@link Operation.InvokeOptions} so that
+ * spawned operation processes have a space context (and therefore can resolve
+ * space-scoped services like `Database.Service`) without each call site having
+ * to thread the id through manually.
+ */
+export const useSpaceCallback = <const Tags extends readonly Context.Tag<any, any>[], T>(
+  spaceId: SpaceId | undefined,
+  tags: Tags,
+  fn: () => Effect.Effect<T, any, Context.Tag.Identifier<Tags[number]> | Capabilities.ProcessManagerRuntimeServices>,
+  deps?: DependencyList,
+): (() => Promise<T>) => {
+  const runtime = useProcessManagerRuntime();
+  return useCallback(() => {
+    if (spaceId === undefined) {
+      throw new TypeError('Space not provided to useSpaceCallback');
+    }
+    const layer = Layer.merge(
+      ServiceResolver.provide({ space: spaceId }, ...tags),
+      Operation.withInvocationOptions({ spaceId }),
+    );
+    return runtime.runPromise(fn().pipe(Effect.provide(layer)) as Effect.Effect<T, any, any>);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [runtime, spaceId, ...(deps ?? [])]);
+};
+
+/**
+ * Suspensefully resolve a single space-scoped service via the
+ * {@link Capabilities.ProcessManagerRuntime}'s service resolver.
+ */
+export const useSpaceService = <T extends Context.Tag<any, any>>(
+  tag: T,
+  spaceId: SpaceId | undefined,
+): Context.Tag.Service<T> | undefined => {
+  const runtime = useProcessManagerRuntime();
+  const promise = useMemo(() => {
+    if (spaceId === undefined) {
+      return undefined;
+    }
+    const layer = ServiceResolver.provide({ space: spaceId }, tag);
+    const effect = Effect.flatMap(tag, (service) => Effect.succeed(service)).pipe(Effect.provide(layer));
+    return runtime.runPromiseExit(effect as Effect.Effect<Context.Tag.Service<T>, any, any>);
+  }, [runtime, spaceId, tag]);
+  if (!promise) {
+    return undefined;
+  }
+  return unwrapExit(use(promise));
+};

package/src/ui/hooks/useSurface.ts

@@ -6,8 +6,8 @@ import { useContext } from 'react';
 
 import { raise } from '@dxos/debug';
 
-import { SurfaceContext } from '../components/surface/context';
+import { Surface } from '../components';
 
-export const useSurface = (): SurfaceContext => {
-  return useContext(SurfaceContext) ?? raise(new Error('Missing SurfaceContext'));
+export const useSurface = (): Surface.Context => {
+  return useContext(Surface.Context) ?? raise(new Error('Missing SurfaceContext'));
 };

package/src/ui/index.ts

@@ -4,4 +4,3 @@
 
 export * from './components';
 export * from './hooks';
-export * as Surface from './components/surface';