@dxos/app-framework 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

package/src/testing/withPluginManager.tsx

@@ -2,29 +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 { useApp, type CreateAppOptions } from '../App';
-import { Capabilities, Events } from '../common';
-import {
-  contributes,
-  defineModule,
-  definePlugin,
-  type ActivationEvent,
-  type AnyCapability,
-  PluginManager,
-  type PluginContext,
-} from '../core';
-
-// TODO(burdon): Factor out (use consistently in plugin framework?)
-export type Provider<C, R> = (context: C) => R;
-export type ProviderOrValue<C, R> = Provider<C, R> | R;
-export const getValue = <C, R>(providerOrValue: ProviderOrValue<C, R>, context: C): R => {
-  return typeof providerOrValue === 'function' ? (providerOrValue as Provider<C, R>)(context) : providerOrValue;
-};
+import { ActivationEvents, Capabilities } from '../common';
+import { type ActivationEvent, Capability, type CapabilityManager, Plugin, PluginManager } from '../core';
+import { type UseAppOptions, useApp } from '../ui';
 
 /**
  * @internal
@@ -32,19 +21,21 @@ export const getValue = <C, R>(providerOrValue: ProviderOrValue<C, R>, context:
 export const setupPluginManager = ({
   capabilities,
   plugins = [],
-  core = plugins.map(({ meta }) => meta.id),
   ...options
-}: CreateAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
-  const pluginManager = new PluginManager({
+}: 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: [STORY_PLUGIN, ...core],
+    plugins: [StoryPlugin, ...plugins],
+    enabled,
     ...options,
   });
 
   if (capabilities) {
-    getValue(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',
@@ -55,56 +46,92 @@ export const setupPluginManager = ({
   return pluginManager;
 };
 
-export type WithPluginManagerOptions = CreateAppOptions & {
-  capabilities?: ProviderOrValue<PluginContext, AnyCapability[]>;
-  fireEvents?: (ActivationEvent | string)[];
+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>;
+  /** @deprecated */
+  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.
-    useEffect(() => {
-      const timeout = setTimeout(async () => {
-        await Promise.all(options.fireEvents?.map((event) => pluginManager.activate(event)) ?? []);
-      });
+    // Avoid mounting useApp with a stale manager from the previous story.
+    if (!managerState || managerState.storyId !== storyId) {
+      return <></>;
+    }
+
+    return <WithPluginManagerApp {...managerState} />;
+  };
+};
 
-      return () => clearTimeout(timeout);
-    }, [pluginManager]);
+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]);
 
-    // Create app.
-    const App = useApp({ pluginManager });
+  const App = useApp({ pluginManager, setupEvents });
+  return <App />;
+};
 
-    return <App />;
-  };
+const storyMeta = {
+  id: 'org.dxos.app-framework.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 STORY_PLUGIN = 'dxos.org/app-framework/story';
-const storyPlugin = () =>
-  definePlugin({ id: STORY_PLUGIN, name: 'Story' }, [
-    defineModule({ id: STORY_PLUGIN, 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,86 @@
+//
+// 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',
+  tags: ['system'],
+}).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,
+);
+
+type DefaultStoryProps = { plugins?: Plugin.Plugin[] };
+
+const DefaultStory = ({ plugins }: DefaultStoryProps) => {
+  const App = useApp({
+    plugins,
+    placeholder: () => {
+      return <div 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/logger → 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();
+  },
+};

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

@@ -0,0 +1,155 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type ReactNode, useEffect, useLayoutEffect, useRef } from 'react';
+
+import { ThemeProvider } from '@dxos/react-ui';
+import { defaultTx, mx } from '@dxos/ui-theme';
+
+import { type PlaceholderProps as PlaceholderSlotProps } from '../../hooks';
+
+declare global {
+  interface Window {
+    /**
+     * Driver injected by `@dxos/app-framework/vite-plugin`'s `bootLoaderPlugin`.
+     * Declared here so the {@link Placeholder} can dismiss the native-DOM
+     * loader once the React placeholder commits without each host having to
+     * re-declare the type.
+     */
+    __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 like plugin chunk-loading or module activation.
+         */
+        range?: { index: number; total: number };
+      }) => void;
+      progress: (fraction?: number) => void;
+      dismiss: () => void;
+    };
+  }
+}
+
+export type PlaceholderComponentProps = PlaceholderSlotProps & {
+  /**
+   * Brand mark rendered while the React tree settles. Pass either a static
+   * `ReactNode` (the framework wraps it in a sizing/animation div) or a
+   * render function that receives the precomputed `className` so the host
+   * can apply it directly to its logo (e.g. an SVG that accepts `className`
+   * — `composer-app` passes `(p) => <Composer {...p} />` from `@dxos/brand`).
+   */
+  logo?: ReactNode | ((props: { className: string }) => ReactNode);
+};
+
+/**
+ * React placeholder. The native-DOM boot loader is the visible UI through
+ * stages 0 (Loading) and 1 (FadeIn): we render `null` until `stage >= 2`
+ * (FadeOut) and instead feed activation progress + status into the still-
+ * alive boot loader. At stage 2 the loader dismisses and the React mark
+ * appears for the cross-fade to the real shell:
+ *
+ *   - composer-app fills `0 → 50%` from `getPlugins`'s per-chunk counter.
+ *   - this component fills `50 → 100%` from `useApp`'s
+ *     `startupProgress.progress` (`activated / total` modules) and pushes
+ *     the per-module status text to the loader's status line.
+ *   - at `stage >= 2` the boot loader is dismissed and the React mark
+ *     starts its `FadeOut → Done` shrink-and-fade.
+ *
+ * Stage progression (driven by `useApp`):
+ *   - `0` — Loading: native-DOM boot loader visible. Placeholder renders nothing.
+ *   - `1` — FadeIn: same — boot loader still owns the screen.
+ *   - `2` — FadeOut: boot loader dismissed, React mark visible at full opacity then shrinks.
+ */
+export const Placeholder = ({ stage = 1, progress, logo }: PlaceholderComponentProps) => {
+  // Used in tests to exercise the error boundary & reset dialog.
+  if (location.search === '?throw') {
+    throw new Error('Test error');
+  }
+
+  // Phase B: feed activation progress + status to the still-visible boot
+  // loader. Maps `[0, 1]` activation → `[0.5, 1]` of the ring; forwards
+  // the raw activation source (`event` / `module`) plus the pre-humanised
+  // label to `__bootLoader.status` so the loader gets to decide how to
+  // render and trace each transition (current default policy: "Activating
+  // <humanizedName>"; trace mode and timings track the structured fields).
+  // No-op once the loader has been dismissed (its `status()` early-returns
+  // when the boot DOM is gone). Skipping `stage >= 2` lets the dismissal
+  // run uncontended.
+  useEffect(() => {
+    if (stage >= 2) {
+      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 from the native-DOM boot loader once the placeholder starts
+  // fading out — keeping the loader visible through `stage 0` and `stage 1`
+  // means the ring stays the visible source of truth for activation
+  // progress. `useLayoutEffect` runs before the next paint so the loader
+  // DOM is removed in the same frame the cross-fade begins.
+  useLayoutEffect(() => {
+    if (stage >= 2) {
+      window.__bootLoader?.dismiss();
+    }
+  }, [stage]);
+
+  // Backstop for the fast-load path where `useLoading` can skip straight
+  // from stage 0 to `Done` (ready=true at the first debounce tick) — the
+  // stage-driven effect above never sees `stage >= 2`, so dismiss on
+  // unmount instead. The `stageRef` guard is what keeps StrictMode's
+  // synthetic mount → cleanup → remount cycle from prematurely dismissing
+  // the loader: the synthetic cleanup runs while `stageRef.current === 0`,
+  // skips the dismiss, and the real unmount (later, at stage `Done`)
+  // performs it.
+  const stageRef = useRef(stage);
+  stageRef.current = stage;
+  useEffect(() => {
+    return () => {
+      if (stageRef.current >= 3 /* Done */) {
+        window.__bootLoader?.dismiss();
+      }
+    };
+  }, []);
+
+  // Defer rendering anything until the FadeOut stage. The boot loader owns
+  // the screen during stages 0 and 1, so any DOM we render here would just
+  // sit invisibly behind it — and rendering null avoids paint cost during
+  // the longest part of the loading sequence (plugin activation).
+  if (stage < 2) {
+    return null;
+  }
+
+  const logoClassName = mx(
+    'h-[300px] w-[300px] scale-600 transition-all duration-500 ease-in-out filter grayscale opacity-0',
+    stage >= 1 && 'scale-100 grayscale-0 opacity-70',
+    stage >= 2 && 'scale-50 opacity-0',
+  );
+
+  return (
+    <ThemeProvider tx={defaultTx}>
+      <div className='relative dx-container h-dvh flex flex-col'>
+        <div className='flex flex-col grow justify-center items-center'>
+          {typeof logo === 'function' ? (
+            logo({ className: logoClassName })
+          ) : logo ? (
+            <div className={logoClassName}>{logo}</div>
+          ) : null}
+        </div>
+      </div>
+    </ThemeProvider>
+  );
+};

package/src/ui/components/Placeholder/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Placeholder';