@dxos/app-framework 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/testing/react.test.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+import { describe, test } from 'vitest';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { Capability, Plugin } from '../core';
+import { Surface } from '../ui';
+import { createTestApp } from './harness';
+import { render, renderSurface } from './react';
+
+const testMeta = { id: 'org.dxos.plugin.test.react-harness', name: 'ReactHarnessTest' };
+
+const TestPlugin = Plugin.define(testMeta).pipe(
+  Plugin.addModule({
+    id: 'surfaces',
+    activatesOn: ActivationEvents.SetupReactSurface,
+    activate: () =>
+      Effect.succeed(
+        Capability.contributes(Capabilities.ReactSurface, [
+          Surface.create<{ message: string }>({
+            id: 'greeting',
+            role: 'greeting',
+            component: ({ data }) => <span data-testid='greeting'>hello {data.message}</span>,
+          }),
+        ]),
+      ),
+  }),
+  Plugin.make,
+);
+
+describe('testing/react', () => {
+  test('render wraps ui in the harness provider tree', async ({ expect }) => {
+    await using harness = await createTestApp({ plugins: [TestPlugin()] });
+    const view = render(harness, <span data-testid='hello'>world</span>);
+    expect(view.getByTestId('hello').textContent).toBe('world');
+  });
+
+  test('renderSurface mounts a surface registered by a plugin', async ({ expect }) => {
+    await using harness = await createTestApp({ plugins: [TestPlugin()] });
+    const view = renderSurface(harness, { role: 'greeting', data: { message: 'plugins' } });
+    const node = await view.findByTestId('greeting');
+    expect(node.textContent).toBe('hello plugins');
+  });
+});

package/src/testing/react.tsx

@@ -0,0 +1,113 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import { render as rtlRender, type RenderOptions, type RenderResult } from '@testing-library/react';
+import React, { type FC, Fragment, type PropsWithChildren, type ReactNode } from 'react';
+
+import { ContextProtocolProvider } from '@dxos/web-context-react';
+
+import { Capabilities } from '../common';
+import { PluginManagerContext } from '../context';
+import { topologicalSort } from '../helpers';
+import { PluginManagerProvider } from '../ui/components/PluginManager/PluginManagerProvider';
+import { SurfaceComponent } from '../ui/components/Surface/SurfaceComponent';
+import { type TestHarness } from './harness';
+
+export type HarnessRenderOptions = Omit<RenderOptions, 'wrapper'> & {
+  /** Additional providers to wrap around the harness tree (applied innermost first). */
+  reactContexts?: FC<PropsWithChildren>[];
+};
+
+/**
+ * Renders `ui` wrapped in the same provider tree as `useApp` plus every contributed
+ * `Capabilities.ReactContext`.
+ */
+export const render = (harness: TestHarness, ui: ReactNode, options?: HarnessRenderOptions): RenderResult => {
+  const { reactContexts = [], ...rest } = options ?? {};
+  const Wrapper = ({ children }: PropsWithChildren) => (
+    <HarnessProviders harness={harness} extra={reactContexts}>
+      {children}
+    </HarnessProviders>
+  );
+  return rtlRender(<>{ui}</>, { ...rest, wrapper: Wrapper });
+};
+
+export type RenderSurfaceProps = {
+  role: string;
+  data?: unknown;
+  limit?: number;
+  fallback?: FC<{ error: Error; data?: any }>;
+  placeholder?: ReactNode;
+};
+
+/**
+ * Renders a `Surface` with the given role/data inside the harness provider tree.
+ */
+export const renderSurface = (
+  harness: TestHarness,
+  props: RenderSurfaceProps,
+  options?: HarnessRenderOptions,
+): RenderResult => {
+  const { role, data, limit, fallback, placeholder } = props;
+  return render(
+    harness,
+    <SurfaceComponent role={role} data={data as any} limit={limit} fallback={fallback} placeholder={placeholder} />,
+    options,
+  );
+};
+
+type HarnessProvidersProps = PropsWithChildren<{
+  harness: TestHarness;
+  extra: FC<PropsWithChildren>[];
+}>;
+
+const HarnessProviders = ({ harness, extra, children }: HarnessProvidersProps) => {
+  const contributed = harness.getAll(Capabilities.ReactContext);
+  const ContributedContext = composeContexts(contributed);
+  const ExtraContext = composeExtra(extra);
+  return (
+    <PluginManagerProvider value={harness.manager}>
+      <ContextProtocolProvider value={harness.manager} context={PluginManagerContext}>
+        <RegistryContext.Provider value={harness.registry}>
+          <ContributedContext>
+            <ExtraContext>{children}</ExtraContext>
+          </ContributedContext>
+        </RegistryContext.Provider>
+      </ContextProtocolProvider>
+    </PluginManagerProvider>
+  );
+};
+
+const composeContexts = (contexts: Capabilities.ReactContext[]): FC<PropsWithChildren> => {
+  if (contexts.length === 0) {
+    return Passthrough;
+  }
+  return topologicalSort(contexts)
+    .map(({ context }) => context)
+    .reduce((Acc, Next) => ({ children }: PropsWithChildren) => (
+      <Acc>
+        <Next>{children}</Next>
+      </Acc>
+    ));
+};
+
+// Composes in innermost-first order: the first context in the array wraps
+// `children` directly; subsequent contexts wrap the accumulator.
+const composeExtra = (contexts: FC<PropsWithChildren>[]): FC<PropsWithChildren> => {
+  if (contexts.length === 0) {
+    return Passthrough;
+  }
+  return contexts.reduce<FC<PropsWithChildren>>(
+    (Acc, Next) =>
+      ({ children }: PropsWithChildren) => (
+        <Next>
+          <Acc>{children}</Acc>
+        </Next>
+      ),
+    Passthrough,
+  );
+};
+
+const Passthrough: FC<PropsWithChildren> = ({ children }) => <Fragment>{children}</Fragment>;

package/src/testing/service.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { invariant } from '@dxos/invariant';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { Plugin, PluginManager } from '../core';
+
+/**
+ * Creates a Plugin.Service layer from a list of plugins.
+ * This is primarily used for testing.
+ */
+export const fromPlugins = (plugins: Plugin.Plugin[]) =>
+  Layer.effect(
+    Plugin.Service,
+    Effect.gen(function* () {
+      // TODO(wittjosiah): Try to dedupe logic between here, createCliApp and useApp.
+
+      const pluginLoader = (id: string) =>
+        Effect.sync(() => {
+          const plugin = plugins.find((plugin) => plugin.meta.id === id);
+          invariant(plugin, `Plugin not found: ${id}`);
+          return plugin;
+        });
+
+      const manager = PluginManager.make({
+        pluginLoader,
+        plugins,
+        core: plugins.map((plugin) => plugin.meta.id),
+      });
+
+      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',
+      });
+
+      yield* manager.activate(ActivationEvents.Startup);
+
+      return manager;
+    }),
+  );

package/src/testing/withPluginManager.stories.tsx

@@ -7,10 +7,9 @@ import React from 'react';
 
 import { withTheme } from '@dxos/react-ui/testing';
 
-import { Capabilities, createSurface } from '../common';
-import { contributes } from '../core';
-import { Surface } from '../react';
-
+import { Capabilities } from '../common';
+import { Capability } from '../core';
+import { Surface } from '../ui';
 import { withPluginManager } from './withPluginManager';
 
 const DefaultStory = () => {
@@ -18,21 +17,21 @@ const DefaultStory = () => {
   return (
     <div>
       <div>Hello</div>
-      <Surface role='main' />
+      <Surface.Surface role='main' />
     </div>
   );
 };
 
 const meta = {
-  title: 'sdk/app-framework/withPluginManager',
+  title: 'sdk/app-framework/testing/withPluginManager',
   render: DefaultStory,
   decorators: [
-    withTheme,
+    withTheme(),
     withPluginManager({
       capabilities: [
-        contributes(
+        Capability.contributes(
           Capabilities.ReactSurface,
-          createSurface({
+          Surface.create({
             id: 'test',
             role: 'main',
             component: ({ role }) => <span>{JSON.stringify({ role })}</span>,

package/src/testing/withPluginManager.tsx

@@ -2,24 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Decorator } from '@storybook/react';
-import React, { useEffect, useMemo } from 'react';
+import { type Decorator, type StoryContext } from '@storybook/react';
+import * as Effect from 'effect/Effect';
+import React, { useEffect, useState } from 'react';
 
 import { raise } from '@dxos/debug';
+import { runAndForwardErrors } from '@dxos/effect';
 import { useAsyncEffect } from '@dxos/react-hooks';
 import { type MaybeProvider, getProviderValue } from '@dxos/util';
 
-import { Capabilities, Events } from '../common';
-import { type UseAppOptions, useApp } from '../components';
-import {
-  type ActivationEvent,
-  type AnyCapability,
-  type PluginContext,
-  PluginManager,
-  contributes,
-  defineModule,
-  definePlugin,
-} from '../core';
+import { ActivationEvents, Capabilities } from '../common';
+import { type ActivationEvent, Capability, type CapabilityManager, Plugin, PluginManager } from '../core';
+import { type UseAppOptions, useApp } from '../ui';
 
 /**
  * @internal
@@ -30,16 +24,16 @@ export const setupPluginManager = ({
   core = plugins.map(({ meta }) => meta.id),
   ...options
 }: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
-  const pluginManager = new PluginManager({
+  const pluginManager = PluginManager.make({
     pluginLoader: () => raise(new Error('Not implemented')),
-    plugins: [StoryPlugin(), ...plugins],
+    plugins: [StoryPlugin, ...plugins],
     core: [StoryPlugin.meta.id, ...core],
     ...options,
   });
 
   if (capabilities) {
-    getProviderValue(capabilities, pluginManager.context).forEach((capability) => {
-      pluginManager.context.contributeCapability({
+    getProviderValue(capabilities, pluginManager.capabilities).forEach((capability) => {
+      pluginManager.capabilities.contribute({
         interface: capability.interface,
         implementation: capability.implementation,
         module: 'story',
@@ -50,57 +44,91 @@ export const setupPluginManager = ({
   return pluginManager;
 };
 
+type ManagedPluginManagerState = {
+  fireEvents?: (ActivationEvent.ActivationEvent | string)[];
+  pluginManager: PluginManager.PluginManager;
+  setupEvents?: ActivationEvent.ActivationEvent[];
+  storyId: string;
+};
+
 export type WithPluginManagerOptions = UseAppOptions & {
   /** @deprecated */
-  capabilities?: MaybeProvider<AnyCapability[], PluginContext>;
+  capabilities?: MaybeProvider<Capability.Any[], CapabilityManager.CapabilityManager>;
   /** @deprecated */
-  fireEvents?: (ActivationEvent | string)[];
+  fireEvents?: (ActivationEvent.ActivationEvent | string)[];
 };
 
+export type WithPluginManagerInitializer<Args = void> =
+  | WithPluginManagerOptions
+  | ((context: StoryContext<Args>) => WithPluginManagerOptions);
+
 /**
  * Wraps a story with a plugin manager.
  * NOTE: This builds up and tears down the plugin manager on every render.
  */
-export const withPluginManager = (options: WithPluginManagerOptions = {}): Decorator => {
+export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args> = {}): Decorator => {
   return (Story, context) => {
-    const pluginManager = useMemo(() => setupPluginManager(options), [options]);
+    const storyId = context.id;
+    const options = typeof init === 'function' ? init(context as any) : init;
+    const [managerState, setManagerState] = useState<ManagedPluginManagerState>();
 
-    // Set-up root capability.
+    // Storybook replaces the full context object often, so key manager ownership by story id.
     useEffect(() => {
-      const capability = contributes(Capabilities.ReactRoot, {
-        id: context.id,
+      const pluginManager = setupPluginManager(options);
+      const capability = Capability.contributes(Capabilities.ReactRoot, {
+        id: storyId,
         root: () => <Story />,
       });
 
-      pluginManager.context.contributeCapability({
+      pluginManager.capabilities.contribute({
         ...capability,
-        module: 'dxos.org/app-framework/withPluginManager',
+        module: 'org.dxos.app-framework.with-plugin-manager',
+      });
+
+      setManagerState({
+        pluginManager,
+        setupEvents: options.setupEvents,
+        fireEvents: options.fireEvents,
+        storyId,
       });
 
       return () => {
-        pluginManager.context.removeCapability(capability.interface, capability.implementation);
+        pluginManager.capabilities.remove(capability.interface, capability.implementation);
+        void runAndForwardErrors(pluginManager.shutdown());
       };
-    }, [pluginManager, context]);
+    }, [storyId, init]);
 
-    // Fire events.
-    useAsyncEffect(async () => {
-      await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
-    }, [pluginManager]);
+    // Avoid mounting useApp with a stale manager from the previous story.
+    if (!managerState || managerState.storyId !== storyId) {
+      return <></>;
+    }
 
-    // Create app.
-    const App = useApp({ pluginManager });
-
-    return <App />;
+    return <WithPluginManagerApp {...managerState} />;
   };
 };
 
+const WithPluginManagerApp = ({ fireEvents, pluginManager, setupEvents, storyId }: ManagedPluginManagerState) => {
+  // Fire deprecated events only after the effect-owned manager for this story exists.
+  useAsyncEffect(async () => {
+    await Promise.all(fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
+  }, [fireEvents, pluginManager, storyId]);
+
+  const App = useApp({ pluginManager, setupEvents });
+  return <App />;
+};
+
 const storyMeta = {
-  id: 'dxos.org/app-framework/story',
+  id: 'org.dxos.app-framework.story',
   name: 'Story',
 };
 
 // No-op plugin to ensure there exists at least one plugin for the startup event.
 // This is necessary because `createApp` expects the startup event to complete before the app is ready.
-const StoryPlugin = definePlugin(storyMeta, () => [
-  defineModule({ id: storyMeta.id, activatesOn: Events.Startup, activate: () => [] }),
-]);
+const StoryPlugin = Plugin.define(storyMeta).pipe(
+  Plugin.addModule({
+    id: 'Story',
+    activatesOn: ActivationEvents.Startup,
+    activate: () => Effect.succeed([]),
+  }),
+  Plugin.make,
+)();

package/src/ui/components/App/App.stories.tsx

@@ -0,0 +1,92 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useEffect } from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { ActivationEvents, Capabilities } from '../../../common';
+import { Capability, Plugin } from '../../../core';
+import { useApp } from '../../hooks';
+
+// Minimal plugin that contributes a ReactRoot.
+const TestPlugin = Plugin.define<{ error?: boolean }>({
+  id: 'org.dxos.plugin.test',
+  name: 'Test Plugin',
+}).pipe(
+  Plugin.addModule(({ error }) => ({
+    id: 'TestMain',
+    activatesOn: ActivationEvents.Startup,
+    activate: () =>
+      Effect.succeed([
+        Capability.contributes(Capabilities.ReactRoot, {
+          id: 'org.dxos.plugin.test.root',
+          root: () => {
+            useEffect(() => {
+              let t: NodeJS.Timeout;
+              if (error) {
+                console.log('Ticking...');
+                t = setTimeout(() => {
+                  console.log('Bang!');
+                  throw new Error('Runtime error');
+                }, 3_000);
+              }
+
+              return () => clearTimeout(t);
+            }, [error]);
+
+            return <h1 className='text-lg'>App Started</h1>;
+          },
+        }),
+      ]),
+  })),
+  Plugin.make,
+);
+
+const core = [TestPlugin.meta.id];
+
+type DefaultStoryProps = { plugins?: Plugin.Plugin[] };
+
+const DefaultStory = ({ plugins }: DefaultStoryProps) => {
+  const App = useApp({
+    plugins,
+    core,
+    placeholder: () => {
+      return (
+        <div role='none' className='text-description'>
+          Loading...
+        </div>
+      );
+    },
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/components/App',
+  render: DefaultStory,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    plugins: [TestPlugin({})],
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    plugins: [TestPlugin({ error: true })],
+  },
+};

package/src/ui/components/App/App.tsx

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren, useEffect } from 'react';
+
+import { Capabilities } from '../../../common';
+import { topologicalSort } from '../../../helpers';
+import { LoadingState, type StartupProgress, type UseAppOptions, useCapabilities, useLoading } from '../../hooks';
+
+export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
+  ready: boolean;
+  error: unknown;
+  progress?: StartupProgress;
+};
+
+const FIRST_INTERACTIVE_MARK = 'app-framework:first-interactive';
+
+export const App = ({ placeholder: Placeholder, ready, error, debounce, progress }: AppProps) => {
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
+  const stage = useLoading(ready, debounce);
+  const placeholderDismissed = stage >= LoadingState.Done;
+
+  // Emit a once-per-app `app-framework:first-interactive` mark the first time
+  // the placeholder is dismissed and the real app shell renders. Closes the
+  // gap between `Startup` activated and the first interactive paint.
+  //
+  // Also dismisses the native-DOM boot loader from
+  // `@dxos/app-framework/vite-plugin` here — the framework owns the
+  // handoff-complete signal, so dismissing in `App` covers both hosts that
+  // wire in a `Placeholder` (which may have its own dismiss path) and hosts
+  // that don't (the loader would otherwise sit forever as a `z-index: 10`
+  // overlay covering the rendered shell).
+  useEffect(() => {
+    if (!placeholderDismissed) {
+      return;
+    }
+    if (performance.getEntriesByName(FIRST_INTERACTIVE_MARK).length === 0) {
+      performance.mark(FIRST_INTERACTIVE_MARK);
+    }
+    (window as { __bootLoader?: { dismiss?: () => void } }).__bootLoader?.dismiss?.();
+  }, [placeholderDismissed]);
+
+  if (error) {
+    // This triggers the error boundary to provide UI feedback for the startup error.
+    throw error;
+  }
+
+  // TODO(wittjosiah): Consider using Suspense instead.
+  if (!placeholderDismissed) {
+    if (!Placeholder) {
+      return null;
+    }
+
+    return <Placeholder stage={stage} progress={progress} />;
+  }
+
+  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/{playground/debug → ui/components/App}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './plugin';
+export * from './App';

package/src/ui/components/Placeholder/Placeholder.stories.tsx

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useState } from 'react';
+import { expect, within } from 'storybook/test';
+
+import { Composer } from '@dxos/brand';
+import { Input, Panel, Toolbar } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Placeholder } from './Placeholder';
+
+/**
+ * The story renders the brand-agnostic `Placeholder` from `@dxos/app-framework/ui`
+ * with the Composer brand icon as its `logo`, so the storybook mirrors what
+ * composer-app actually mounts in production. The render function form lets
+ * the SVG accept the placeholder's animation `className` directly.
+ */
+const meta = {
+  title: 'sdk/app-framework/components/Placeholder',
+  component: Placeholder,
+  render: () => {
+    const [stage, setStage] = useState(0);
+    const [auto, setAuto] = useState(false);
+    useEffect(() => {
+      if (!auto) {
+        return;
+      }
+
+      const interval = setInterval(() => {
+        setStage((prev) => {
+          return prev >= 2 ? 0 : prev + 1;
+        });
+      }, 3_000);
+
+      return () => clearInterval(interval);
+    }, [auto]);
+
+    return (
+      <Panel.Root>
+        <Panel.Toolbar asChild>
+          <Toolbar.Root classNames='gap-2'>
+            <Input.Root>
+              <Input.Checkbox checked={auto} onCheckedChange={(checked) => setAuto(checked === true)} />
+              <Input.Label>Auto</Input.Label>
+            </Input.Root>
+            <Toolbar.Button onClick={() => setStage((prev) => (prev < 2 ? prev + 1 : 0))}>Next</Toolbar.Button>
+            <Toolbar.Text>{stage}</Toolbar.Text>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+        <Panel.Content>
+          <Placeholder stage={stage} logo={(logoProps) => <Composer {...logoProps} />} />
+        </Panel.Content>
+      </Panel.Root>
+    );
+  },
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  tags: ['test'],
+} satisfies Meta<typeof Placeholder>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    stage: 0,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Smoke test: the toolbar's `Next` button is rendered alongside the
+    // placeholder, so the story mounted without throwing.
+    await expect(canvas.getByRole('button', { name: 'Next' })).toBeInTheDocument();
+  },
+};