@dxos/app-framework 0.8.4-main.406dc2a → 0.8.4-main.422d1c7879

package/src/ui/hooks/useApp.tsx

@@ -0,0 +1,289 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
+import React, { type FC, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+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, PluginManagerProvider } from '../components';
+
+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;
+  /** Human-readable label for the currently activating module. */
+  status?: string;
+};
+
+export type PlaceholderProps = {
+  stage?: number;
+  progress?: StartupProgress;
+};
+
+export type UseAppOptions = {
+  pluginManager?: PluginManager.PluginManager;
+  pluginLoader?: PluginManager.ManagerOptions['pluginLoader'];
+  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[];
+  cacheEnabled?: boolean;
+  safeMode?: boolean;
+  debounce?: number;
+  timeout?: number;
+  fallback?: FC<FallbackProps>;
+  placeholder?: FC<PlaceholderProps>;
+};
+
+/**
+ * Expected usage is for this to be the entrypoint of the application.
+ * Initializes plugins and renders the root components.
+ *
+ * @example
+ * const plugins = [LayoutPlugin(), MyPlugin()];
+ * const core = [LayoutPluginId];
+ * const default = [MyPluginId];
+ * const fallback = <div>Initializing Plugins...</div>;
+ * const App = useApp({ 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.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.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,
+  plugins: pluginsProp,
+  core: coreProp,
+  defaults: defaultsProp,
+  setupEvents: setupEventsProp,
+  placeholder,
+  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, () => []);
+
+  const pluginLoader = useMemo(
+    () =>
+      pluginLoaderProp ??
+      ((id: string) =>
+        Effect.sync(() => {
+          const plugin = plugins.find((plugin) => plugin.meta.id === id);
+          invariant(plugin, `Plugin not found: ${id}`);
+          return plugin;
+        })),
+    [pluginLoaderProp, plugins],
+  );
+
+  const readyRef = useRef(false);
+  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 isExternalManager = !!pluginManager;
+  const manager = useMemo(() => {
+    const mgr = pluginManager ?? PluginManager.make({ pluginLoader, plugins, core, enabled });
+    log('useApp: useMemo created/reused manager', { provided: !!pluginManager });
+    return mgr;
+  }, [pluginManager, pluginLoader, plugins, core, enabled]);
+
+  useEffect(() => {
+    if (!cacheEnabled) {
+      return;
+    }
+    return manager.registry.subscribe(manager.enabled, (value) => {
+      localStorage.setItem(ENABLED_KEY, JSON.stringify(value));
+    });
+  }, [cacheEnabled, manager]);
+
+  useEffect(() => {
+    setupDevtools(manager);
+  }, [manager]);
+
+  useAsyncEffect(async () => {
+    log('useApp: effect mount');
+
+    manager.capabilities.contribute({
+      interface: Capabilities.PluginManager,
+      implementation: manager,
+      module: 'org.dxos.app-framework.plugin-manager',
+    });
+
+    manager.capabilities.contribute({
+      interface: Capabilities.AtomRegistry,
+      implementation: manager.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, module, error: error$ }) =>
+            Effect.sync(() => {
+              if (event === ActivationEvents.Startup.id && state === 'activated') {
+                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;
+              }
+              // Update progress on every module-level `activated` message.
+              // Driven by the activation event itself rather than a poll, so
+              // the placeholder UI updates as soon as a module commits.
+              if (module && state === 'activated' && !readyRef.current) {
+                const active = manager.getActive();
+                const total = manager.getModules().length;
+                setStartupProgress({
+                  activated: active.length,
+                  total,
+                  progress: total > 0 ? active.length / total : 0,
+                  status: humanizeModuleId(module),
+                });
+              }
+              if (error$ && !readyRef.current) {
+                setError(error$);
+                errorRef.current = error$;
+              }
+            }),
+          ),
+          Effect.forever,
+        ),
+      );
+
+      yield* Effect.all([
+        ...setupEvents.map((event) => manager.activate(event)),
+        manager.activate(ActivationEvents.SetupReactSurface),
+        manager.activate(ActivationEvents.Startup),
+      ]);
+
+      return yield* Fiber.join(listener);
+    }).pipe(Effect.scoped, Effect.runFork);
+
+    // Set up a timeout for startup.
+    const timeoutId = setTimeout(() => {
+      if (!readyRef.current && !errorRef.current) {
+        log.warn('startup timeout diagnostic', {
+          eventsFired: manager.getEventsFired(),
+          activeModules: manager.getActive(),
+          pendingReset: manager.getPendingReset(),
+        });
+        void runAndForwardErrors(Fiber.interrupt(fiber));
+        setError(new Error(`Startup timed out after ${timeout}ms`));
+      }
+    }, timeout);
+
+    return () => {
+      log('useApp: effect cleanup');
+      clearTimeout(timeoutId);
+      void runAndForwardErrors(Fiber.interrupt(fiber));
+      if (!isExternalManager) {
+        void runAndForwardErrors(manager.shutdown());
+      }
+    };
+  }, [manager]);
+
+  return useCallback(
+    () => (
+      <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}
+                progress={startupProgress}
+              />
+            </RegistryContext.Provider>
+          </ContextProtocolProvider>
+        </PluginManagerProvider>
+      </ErrorBoundary>
+    ),
+    [fallback, manager, placeholder, ready, error],
+  );
+};
+
+const setupDevtools = (manager: PluginManager.PluginManager) => {
+  (globalThis as any).composer ??= {};
+  (globalThis as any).composer.manager = manager;
+};
+
+/**
+ * Extracts a human-readable label from a module ID.
+ * E.g., "org.dxos.plugin.markdown.module.ReactSurface" → "Markdown".
+ */
+const humanizeModuleId = (moduleId: string): string => {
+  // Extract plugin name from pattern: org.dxos.plugin.<name>.module.<capability>
+  const pluginMatch = moduleId.match(/\.plugin\.([^.]+)\./);
+  if (pluginMatch) {
+    const name = pluginMatch[1];
+    // Convert kebab-case to title case.
+    return name
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  // Fallback: use the last segment.
+  const parts = moduleId.split('.');
+  return parts[parts.length - 1];
+};

package/src/ui/hooks/useCapabilities.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import { useCallback } from 'react';
+
+import { invariant } from '@dxos/invariant';
+
+import { Capabilities } from '../../common';
+import { type Capability } from '../../core';
+import { usePluginManager } from '../components';
+
+/**
+ * Hook to request capabilities from the plugin context.
+ * @returns An array of capabilities.
+ */
+export const useCapabilities = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
+  const manager = usePluginManager();
+  return useAtomValue(manager.capabilities.atom(interfaceDef));
+};
+
+/**
+ * Hook to request a capability from the plugin context.
+ * @returns The capability.
+ * @throws If no capability is found.
+ */
+export const useCapability = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
+  const capabilities = useCapabilities(interfaceDef);
+  invariant(capabilities.length > 0, `No capability found for ${interfaceDef.identifier}`);
+  return capabilities[0];
+};
+
+/**
+ * Hook to get the current value of an atom capability.
+ * Automatically subscribes to changes.
+ * @example const settings = useAtomCapability(ThreadCapabilities.Settings);
+ */
+export const useAtomCapability = <T>(atomCapability: Capability.InterfaceDef<Atom.Atom<T>>): T => {
+  const atom = useCapability(atomCapability);
+  return useAtomValue(atom);
+};
+
+/**
+ * Hook to get value and updater for an atom capability.
+ * Returns [currentValue, updateFn] similar to useState.
+ * @example const [settings, updateSettings] = useAtomCapabilityState(ThreadCapabilities.Settings);
+ */
+export const useAtomCapabilityState = <T>(
+  atomCapability: Capability.InterfaceDef<Atom.Writable<T>>,
+): [T, (fn: (current: T) => T) => void] => {
+  const registry = useCapability(Capabilities.AtomRegistry);
+  const atom = useCapability(atomCapability);
+  const value = useAtomValue(atom);
+  const update = useCallback(
+    (fn: (current: T) => T) => {
+      registry.set(atom, fn(registry.get(atom)));
+    },
+    [registry, atom],
+  );
+  return [value, update];
+};
+
+/**
+ * Hook to get the operation invoker capability.
+ */
+export const useOperationInvoker = (): Capabilities.OperationInvoker => useCapability(Capabilities.OperationInvoker);

package/src/{components → ui/hooks}/useLoading.tsx

@@ -4,8 +4,6 @@
 
 import { useEffect, useState } from 'react';
 
-import { type AppProps } from './App';
-
 export enum LoadingState {
   Loading = 0,
   FadeIn = 1,
@@ -23,7 +21,7 @@ export enum LoadingState {
  * 2: Fade-out  - Fade out the loading animation.
  * 3: Done      - Remove the placeholder.
  */
-export const useLoading = (state: AppProps['state'], debounce = 0) => {
+export const useLoading = (ready: boolean, debounce = 0) => {
   const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
   useEffect(() => {
     if (!debounce) {
@@ -34,7 +32,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
       setStage((stage) => {
         switch (stage) {
           case LoadingState.Loading: {
-            if (!state.ready) {
+            if (!ready) {
               return LoadingState.FadeIn;
             } else {
               clearInterval(i);
@@ -43,7 +41,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
           }
 
           case LoadingState.FadeIn: {
-            if (state.ready) {
+            if (ready) {
               return LoadingState.FadeOut;
             }
             break;
@@ -63,7 +61,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
   }, [debounce]);
 
   if (!debounce) {
-    return state.ready ? LoadingState.Done : LoadingState.Loading;
+    return ready ? LoadingState.Done : LoadingState.Loading;
   }
 
   return stage;

package/src/ui/hooks/useSettingsState.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, RegistryContext, useAtomValue } from '@effect-atom/atom-react';
+import { useCallback, useContext } from 'react';
+
+/**
+ * Hook to read and update a settings atom.
+ * Returns the current value and an update function.
+ */
+export const useSettingsState = <T>(
+  atom: Atom.Writable<T>,
+): { settings: T; updateSettings: (fn: (current: T) => T) => void } => {
+  const registry = useContext(RegistryContext);
+  const settings = useAtomValue(atom);
+
+  const updateSettings = useCallback(
+    (fn: (current: T) => T) => {
+      registry.set(atom, fn(registry.get(atom)));
+    },
+    [registry, atom],
+  );
+
+  return { settings, updateSettings };
+};

package/src/ui/hooks/useSurface.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { Surface } from '../components';
+
+export const useSurface = (): Surface.Context => {
+  return useContext(Surface.Context) ?? raise(new Error('Missing SurfaceContext'));
+};

package/src/ui/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './components';
+export * from './hooks';

package/src/vite-plugin/boot-loader/BootLoader.stories.tsx

@@ -0,0 +1,162 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useState } from 'react';
+
+import css from './boot-loader.css?raw';
+
+/**
+ * React rendering of the native-DOM boot loader so the visual can be poked at
+ * in storybook without having to rebuild a host app. The DOM structure and
+ * style classes are identical to what {@link bootLoaderPlugin} injects via
+ * `transformIndexHtml`; the CSS itself is imported as a raw string from the
+ * same source the plugin uses, so a styling change in `boot-loader.css`
+ * shows up here automatically.
+ *
+ * Coupled-but-not-shared: the actual production loader runs as inline HTML
+ * before any module loads, so it can't be a React component there. This
+ * mirror lets us iterate on the look + animations + status-text behaviour
+ * with hot-reload.
+ */
+type BootLoaderProps = {
+  status?: string;
+  /**
+   * Inline SVG markup. Use `fill="currentColor"` on the paths so the mark
+   * inherits the loader's text colour.
+   */
+  markSvg?: string;
+  /**
+   * Optional progress fraction in [0, 1]. When set, switches the bar from
+   * the default indeterminate slide animation to a determinate fill.
+   */
+  progress?: number;
+};
+
+const BootLoader = ({ status = 'Loading…', markSvg, progress }: BootLoaderProps) => {
+  const determinate = typeof progress === 'number' && progress >= 0;
+  const clamped = determinate ? Math.max(0, Math.min(1, progress!)) : 0;
+  return (
+    <>
+      <style>{css}</style>
+      <div id='boot-loader' role='status' aria-live='polite' aria-label='Initializing'>
+        {markSvg ? <div id='boot-loader-mark' dangerouslySetInnerHTML={{ __html: markSvg }} /> : null}
+        <div
+          id='boot-loader-bar'
+          {...(determinate
+            ? {
+                'data-determinate': '',
+                style: { ['--boot-loader-bar-progress' as string]: String(clamped * 100) },
+              }
+            : {})}
+        />
+        <div id='boot-loader-status'>{status}</div>
+      </div>
+    </>
+  );
+};
+
+// Stand-in mark — keeps storybook self-contained (the production app pipes in
+// `packages/ui/brand/assets/icons/composer-icon-monochrome.svg` from
+// vite.config.ts via the plugin's `markSvg` option).
+const PLACEHOLDER_MARK = `
+  <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="12" cy="12" r="10" fill="none" stroke="currentColor" stroke-width="1.5" />
+    <path d="M8 12h8 M12 8v8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+  </svg>
+`;
+
+const PHASES = ['Loading…', 'Loading framework…', 'Reading configuration…', 'Starting services…', 'Loading plugins…'];
+
+/**
+ * Approximate plugin count used by the `Determinate` story. Hardcoded here
+ * to keep the storybook self-contained — the production count comes from
+ * `composer-app/src/plugin-defs.tsx`'s dynamic-import list. Adjust if the
+ * story should mirror an updated count.
+ */
+const STORY_PLUGIN_COUNT = 59;
+
+/** Tick interval for the determinate-progress simulation, in ms. */
+const STORY_TICK_MS = 100;
+
+const CyclingStory = () => {
+  const [index, setIndex] = useState(0);
+  useEffect(() => {
+    const handle = setInterval(() => {
+      setIndex((current) => (current + 1) % PHASES.length);
+    }, 1_500);
+    return () => clearInterval(handle);
+  }, []);
+  return <BootLoader status={PHASES[index]} markSvg={PLACEHOLDER_MARK} />;
+};
+
+const DeterminateStory = () => {
+  // Walks progress 0 → 1 by ticking once every `STORY_TICK_MS`, mirroring
+  // composer's per-plugin counter in `getPlugins`.
+  const [progress, setProgress] = useState(0);
+  useEffect(() => {
+    let loaded = 0;
+    const handle = setInterval(() => {
+      loaded += 1;
+      setProgress(loaded / STORY_PLUGIN_COUNT);
+      if (loaded >= STORY_PLUGIN_COUNT) {
+        clearInterval(handle);
+      }
+    }, STORY_TICK_MS);
+    return () => clearInterval(handle);
+  }, []);
+  const loaded = Math.round(progress * STORY_PLUGIN_COUNT);
+  const status = progress >= 1 ? 'Starting Composer…' : `Loading plugins (${loaded}/${STORY_PLUGIN_COUNT})…`;
+  return <BootLoader status={status} markSvg={PLACEHOLDER_MARK} progress={progress} />;
+};
+
+const meta: Meta<typeof BootLoader> = {
+  title: 'sdk/app-framework/vite-plugin/BootLoader',
+  component: BootLoader,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  argTypes: {
+    status: { control: 'text' },
+    markSvg: { control: 'text' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof BootLoader>;
+
+/** Static loader exactly as it ships in `composer-app` (without the brand SVG). */
+export const Default: Story = {
+  args: {
+    status: 'Loading…',
+  },
+};
+
+/** Same loader plus an inline brand mark — verify currentColor inheritance. */
+export const WithMark: Story = {
+  args: {
+    status: 'Loading…',
+    markSvg: PLACEHOLDER_MARK,
+  },
+};
+
+/**
+ * Cycles through the strings the host typically passes to
+ * `window.__bootLoader.status(...)`. Useful for verifying that the progress
+ * bar's vertical position is stable across status changes — `#boot-loader-status`
+ * has a fixed height so the line-box can't reflow the flex column.
+ */
+export const Cycling: Story = {
+  render: () => <CyclingStory />,
+};
+
+/**
+ * Determinate progress bar driven by `__bootLoader.progress(fraction)`.
+ * Mirrors composer-app's behaviour during the `getPlugins` phase — the bar
+ * fills 0 → 100% as plugin chunks resolve.
+ */
+export const Determinate: Story = {
+  render: () => <DeterminateStory />,
+};