@dxos/app-framework 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

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

@@ -24,13 +24,13 @@ export const fromPlugins = (plugins: Plugin.Plugin[]) =>
         Effect.sync(() => {
           const plugin = plugins.find((plugin) => plugin.meta.id === id);
           invariant(plugin, `Plugin not found: ${id}`);
-          return plugin;
+          return { plugin };
         });
 
       const manager = PluginManager.make({
         pluginLoader,
         plugins,
-        core: plugins.map((plugin) => plugin.meta.id),
+        enabled: plugins.map((plugin) => plugin.meta.id),
       });
 
       manager.capabilities.contribute({

package/src/testing/withPluginManager.stories.tsx

@@ -10,7 +10,6 @@ import { withTheme } from '@dxos/react-ui/testing';
 import { Capabilities } from '../common';
 import { Capability } from '../core';
 import { Surface } from '../ui';
-
 import { withPluginManager } from './withPluginManager';
 
 const DefaultStory = () => {
@@ -24,7 +23,7 @@ const DefaultStory = () => {
 };
 
 const meta = {
-  title: 'sdk/app-framework/withPluginManager',
+  title: 'sdk/app-framework/testing/withPluginManager',
   render: DefaultStory,
   decorators: [
     withTheme(),

package/src/testing/withPluginManager.tsx

@@ -4,9 +4,11 @@
 
 import { type Decorator, type StoryContext } from '@storybook/react';
 import * as Effect from 'effect/Effect';
-import React, { useEffect, useMemo } from 'react';
+import React, { useEffect, useState } from 'react';
 
 import { raise } from '@dxos/debug';
+import { runAndForwardErrors } from '@dxos/effect';
+import { DXN } from '@dxos/keys';
 import { useAsyncEffect } from '@dxos/react-hooks';
 import { type MaybeProvider, getProviderValue } from '@dxos/util';
 
@@ -20,13 +22,15 @@ import { type UseAppOptions, useApp } from '../ui';
 export const setupPluginManager = ({
   capabilities,
   plugins = [],
-  core = plugins.map(({ meta }) => meta.id),
   ...options
 }: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
+  // Auto-enable every non-system plugin so stories don't have to spell out
+  // enablement. System-tagged plugins are force-enabled by the manager.
+  const enabled = plugins.filter(({ meta }) => !meta.tags?.includes('system')).map(({ meta }) => meta.id);
   const pluginManager = PluginManager.make({
     pluginLoader: () => raise(new Error('Not implemented')),
     plugins: [StoryPlugin, ...plugins],
-    core: [StoryPlugin.meta.id, ...core],
+    enabled,
     ...options,
   });
 
@@ -43,6 +47,13 @@ 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<Capability.Any[], CapabilityManager.CapabilityManager>;
@@ -60,16 +71,15 @@ export type WithPluginManagerInitializer<Args = void> =
  */
 export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args> = {}): Decorator => {
   return (Story, context) => {
+    const storyId = context.id;
     const options = typeof init === 'function' ? init(context as any) : init;
-    const { pluginManager, setupEvents } = useMemo(
-      () => ({ pluginManager: setupPluginManager(options), setupEvents: options.setupEvents }),
-      [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 pluginManager = setupPluginManager(options);
       const capability = Capability.contributes(Capabilities.ReactRoot, {
-        id: context.id,
+        id: storyId,
         root: () => <Story />,
       });
 
@@ -78,28 +88,44 @@ export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args
         module: 'org.dxos.app-framework.with-plugin-manager',
       });
 
+      setManagerState({
+        pluginManager,
+        setupEvents: options.setupEvents,
+        fireEvents: options.fireEvents,
+        storyId,
+      });
+
       return () => {
         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, setupEvents });
-
-    return <App />;
+    return <WithPluginManagerApp {...managerState} />;
   };
 };
 
-const storyMeta = {
-  id: 'org.dxos.app-framework.story',
-  name: 'Story',
+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 = Plugin.makeMeta({
+  key: DXN.make('org.dxos.appFramework.story'),
+  name: 'Story',
+  tags: ['system'],
+});
+
 // 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 = Plugin.define(storyMeta).pipe(

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

@@ -6,6 +6,7 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
 import React, { useEffect } from 'react';
 
+import { DXN } from '@dxos/keys';
 import { withTheme } from '@dxos/react-ui/testing';
 
 import { ActivationEvents, Capabilities } from '../../../common';
@@ -13,10 +14,13 @@ 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(
+const TestPlugin = Plugin.define<{ error?: boolean }>(
+  Plugin.makeMeta({
+    key: DXN.make('org.dxos.plugin.test'),
+    name: 'Test Plugin',
+    tags: ['system'],
+  }),
+).pipe(
   Plugin.addModule(({ error }) => ({
     id: 'TestMain',
     activatesOn: ActivationEvents.Startup,
@@ -46,28 +50,16 @@ const TestPlugin = Plugin.define<{ error?: boolean }>({
   Plugin.make,
 );
 
-const core = [TestPlugin.meta.id];
+type DefaultStoryProps = { plugins?: Plugin.Plugin[] };
 
-type StoryProps = { plugins?: Plugin.Plugin[] };
-
-const DefaultStory = ({ plugins }: StoryProps) => {
-  const App = useApp({
-    plugins,
-    core,
-    placeholder: () => {
-      return (
-        <div role='none' className='text-description'>
-          Loading...
-        </div>
-      );
-    },
-  });
+const DefaultStory = ({ plugins }: DefaultStoryProps) => {
+  const App = useApp({ plugins });
 
   return <App />;
 };
 
 const meta = {
-  title: 'sdk/app-framework/App',
+  title: 'sdk/app-framework/components/App',
   render: DefaultStory,
   decorators: [withTheme()],
   parameters: {

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

@@ -2,34 +2,121 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type PropsWithChildren } from 'react';
+import React, { type PropsWithChildren, useEffect, useLayoutEffect } from 'react';
 
 import { Capabilities } from '../../../common';
 import { topologicalSort } from '../../../helpers';
-import { LoadingState, type UseAppOptions, useCapabilities, useLoading } from '../../hooks';
+import { LoadingState, type StartupProgress, type UseAppOptions, useCapabilities, useLoading } from '../../hooks';
 
-export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
+declare global {
+  interface Window {
+    /**
+     * Driver injected by `@dxos/app-framework/vite-plugin`'s `bootLoaderPlugin`
+     * (a Solid app inlined into `index.html`). Declared here — on a module that
+     * is part of the `@dxos/app-framework/ui` export surface — so the React side
+     * and host apps (e.g. composer-app) can drive the loader without each
+     * re-declaring the type. The canonical definition lives in the plugin's
+     * `loader-app/types.ts`; this mirror exists because that source compiles in a
+     * separate (Solid) program that doesn't ship its globals to consumers.
+     */
+    __bootLoader?: {
+      status: (payload: {
+        event?: string;
+        module?: string;
+        humanized: string;
+        /**
+         * Optional `(index/total)` tick. When present, the loader replaces the
+         * current line in place ("Loading plugins (12/80)") instead of appending
+         * a new entry — keeps the visible log compact during long counted phases.
+         */
+        range?: { index: number; total: number };
+      }) => void;
+      progress: (fraction?: number) => void;
+      ready: () => void;
+      dismiss: () => void;
+    };
+  }
+}
+
+export type AppProps = Pick<UseAppOptions, 'debounce'> & {
   ready: boolean;
   error: unknown;
+  progress?: StartupProgress;
 };
 
-export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppProps) => {
+const FIRST_INTERACTIVE_MARK = 'app-framework:first-interactive';
+
+export const App = ({ 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;
+
+  // Relay the startup lifecycle into the boot loader injected by
+  // `@dxos/app-framework/vite-plugin` (a Solid app inlined into `index.html`,
+  // the only visible loading UI). Plugin activation fills the `[0.5, 1]` half
+  // of the ring; the raw `event` / `module` ids ride along so the loader owns
+  // how each transition is rendered and traced. No-op once the outro has
+  // started (`FadeOut`), so the dismissal runs uncontended.
+  useEffect(() => {
+    if (stage >= LoadingState.FadeOut) {
+      return;
+    }
+    const fraction = progress?.progress ?? 0;
+    window.__bootLoader?.progress(0.5 + fraction * 0.5);
+    if (progress?.humanizedName) {
+      window.__bootLoader?.status({
+        event: progress.event,
+        module: progress.module,
+        humanized: `Activating ${progress.humanizedName}`,
+      });
+    }
+  }, [stage, progress?.progress, progress?.event, progress?.module, progress?.humanizedName]);
+
+  // Hand off at fade-out: play the loader's graceful shrink-and-fade outro.
+  // `useLayoutEffect` runs before the next paint so the outro begins in the
+  // same frame the real shell starts rendering beneath it.
+  useLayoutEffect(() => {
+    if (stage >= LoadingState.FadeOut) {
+      window.__bootLoader?.ready();
+    }
+  }, [stage]);
+
+  // Emit a once-per-app `app-framework:first-interactive` mark the first time
+  // the loader is dismissed and the real app shell renders. Closes the gap
+  // between `Startup` activated and the first interactive paint.
+  //
+  // Also the framework-owned handoff-complete signal: `dismiss()` removes the
+  // loader immediately on the fast-load path (where `useLoading` skips
+  // `FadeOut`), and is a no-op once an outro is already in flight, so it never
+  // cuts the animation short.
+  useEffect(() => {
+    if (!placeholderDismissed) {
+      return;
+    }
+    if (performance.getEntriesByName(FIRST_INTERACTIVE_MARK).length === 0) {
+      performance.mark(FIRST_INTERACTIVE_MARK);
+    }
+    window.__bootLoader?.dismiss();
+  }, [placeholderDismissed]);
+
+  // Used in tests to exercise the error boundary & reset dialog (see
+  // composer-app's `basic.spec.ts`). Thrown into the surrounding `ErrorBoundary`.
+  if (location.search === '?throw') {
+    throw new Error('Test error');
+  }
 
   if (error) {
     // This triggers the error boundary to provide UI feedback for the startup error.
     throw error;
   }
 
+  // The boot loader owns the screen until handoff completes; render nothing
+  // until then (any DOM here would sit invisibly behind the `z-index: 10`
+  // loader anyway).
   // TODO(wittjosiah): Consider using Suspense instead.
-  if (stage < LoadingState.Done) {
-    if (!Placeholder) {
-      return null;
-    }
-
-    return <Placeholder stage={stage} />;
+  if (!placeholderDismissed) {
+    return null;
   }
 
   const ComposedContext = composeContexts(reactContexts);

package/src/ui/components/PluginManager/PluginManagerContext.stories.tsx

@@ -7,6 +7,7 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
 import React, { useEffect, useMemo, useState } from 'react';
 
+import { DXN } from '@dxos/keys';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { useWebComponentContext } from '@dxos/web-context-react';
 
@@ -38,7 +39,9 @@ const CountStatus = () => {
     }
   }, [counter]);
 
-  if (!manager) return null;
+  if (!manager) {
+    return null;
+  }
 
   const isEven = count % 2 === 0;
 
@@ -115,10 +118,13 @@ const CounterComponent = () => {
 };
 
 // Plugin that provides the Counter capability and renders the UI
-const CounterPlugin = Plugin.define({
-  id: 'org.dxos.plugin.counter',
-  name: 'Counter Plugin',
-}).pipe(
+const CounterPlugin = Plugin.define(
+  Plugin.makeMeta({
+    key: DXN.make('org.dxos.plugin.counter'),
+    name: 'Counter Plugin',
+    tags: ['system'],
+  }),
+).pipe(
   Plugin.addModule({
     id: 'CounterMain',
     activatesOn: ActivationEvents.Startup,
@@ -152,25 +158,15 @@ const CounterPlugin = Plugin.define({
 )();
 
 const plugins = [CounterPlugin];
-const core = ['org.dxos.plugin.counter'];
-const placeholder = () => (
-  <div className='flex h-screen items-center justify-center p-4 text-lg text-neutral-500'>
-    Initializing Application...
-  </div>
-);
 
 const DefaultStory = () => {
-  const App = useApp({
-    plugins,
-    core,
-    placeholder,
-  });
+  const App = useApp({ plugins });
 
   return <App />;
 };
 
 const meta = {
-  title: 'sdk/app-framework/PluginManagerContext',
+  title: 'sdk/app-framework/components/PluginManagerContext',
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
   parameters: {

package/src/ui/components/Surface/SurfaceComponent.stories.tsx

@@ -5,15 +5,14 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
 
-import { faker } from '@dxos/random';
-import { List, ListItem, Toolbar } from '@dxos/react-ui';
+import { random } from '@dxos/random';
+import { List, ListItem, Panel, Toolbar } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ColorStyles, getHashStyles, mx } from '@dxos/ui-theme';
 
 import { Capabilities } from '../../../common';
 import { withPluginManager } from '../../../testing';
 import { usePluginManager } from '../PluginManager';
-
 import { SurfaceComponent, useSurfaces } from './SurfaceComponent';
 import { create } from './types';
 
@@ -39,7 +38,7 @@ const DefaultStory = () => {
   const [selected, setSelected] = useState<string | undefined>();
 
   const handleAdd = useCallback(() => {
-    const id = `test-${faker.number.int({ min: 0, max: 1_000 })}`;
+    const id = `test-${random.number.int({ min: 0, max: 1_000 })}`;
     const styles = getHashStyles(id);
 
     manager.capabilities.contribute({
@@ -57,7 +56,7 @@ const DefaultStory = () => {
   }, [manager]);
 
   const handleSelect = useCallback(() => {
-    setSelected(faker.helpers.arrayElement(surfaces)?.id);
+    setSelected(random.helpers.arrayElement(surfaces)?.id);
   }, [surfaces]);
 
   const handleError = useCallback(() => {
@@ -88,7 +87,7 @@ const DefaultStory = () => {
           }
 
           return (
-            <div className='flex justify-center items-center border border-rose-fill rounded-sm'>
+            <div className='flex justify-center items-center border border-rose-bg rounded-sm'>
               <span className='font-mono'>Ticking... {count}</span>
             </div>
           );
@@ -105,13 +104,15 @@ const DefaultStory = () => {
   }, [ref]);
 
   return (
-    <div className='flex flex-col h-full overflow-hidden'>
-      <Toolbar.Root>
-        <Toolbar.Button onClick={handleAdd}>Add</Toolbar.Button>
-        <Toolbar.Button onClick={handleSelect}>Pick</Toolbar.Button>
-        <Toolbar.Button onClick={handleError}>Error</Toolbar.Button>
-      </Toolbar.Root>
-      <div className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
+    <Panel.Root>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root>
+          <Toolbar.Button onClick={handleAdd}>Add</Toolbar.Button>
+          <Toolbar.Button onClick={handleSelect}>Pick</Toolbar.Button>
+          <Toolbar.Button onClick={handleError}>Error</Toolbar.Button>
+        </Toolbar.Root>
+      </Panel.Toolbar>
+      <Panel.Content className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
         <SurfaceComponent role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
         <div className='overflow-y-auto h-full'>
           <List>
@@ -122,13 +123,13 @@ const DefaultStory = () => {
             ))}
           </List>
         </div>
-      </div>
-    </div>
+      </Panel.Content>
+    </Panel.Root>
   );
 };
 
 const meta = {
-  title: 'sdk/app-framework/Surface',
+  title: 'sdk/app-framework/components/Surface',
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withPluginManager({ capabilities: [] })],
   parameters: {