@dxos/app-framework 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/testing/harness.ts

@@ -0,0 +1,247 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Registry } from '@effect-atom/atom-react';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
+
+import { type Operation } from '@dxos/compute';
+import { runAndForwardErrors } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { ActivationEvent, type Capability, type CapabilityManager, type Plugin, PluginManager } from '../core';
+
+export type TestAppOptions = {
+  /**
+   * Plugins to register. Plugins whose `meta.tags` includes `'system'` are treated as core
+   * (force-enabled). For test convenience, plugins without a `'system'` tag are enabled by
+   * default unless `enabled` is provided.
+   */
+  plugins: Plugin.Plugin[];
+  /** Plugin ids that are enabled by default in addition to core. Defaults to all non-system plugin ids. */
+  enabled?: string[];
+  /** Additional activation events fired alongside SetupReactSurface. */
+  setupEvents?: ActivationEvent.ActivationEvent[];
+  /**
+   * Whether to automatically fire SetupReactSurface + Startup during setup.
+   * Defaults to true.
+   */
+  autoStart?: boolean;
+  /**
+   * Whether to register the PluginManager + AtomRegistry framework capabilities.
+   * Defaults to true.
+   */
+  registerFrameworkCapabilities?: boolean;
+};
+
+/**
+ * A running plugin manager plus helpers for driving it in tests.
+ */
+export interface TestHarness {
+  readonly manager: PluginManager.PluginManager;
+  readonly capabilities: CapabilityManager.CapabilityManager;
+  readonly registry: Registry.Registry;
+
+  /** Activate the given event. Equivalent to `manager.activate(event)`. */
+  fire(event: ActivationEvent.ActivationEvent | string): Promise<boolean>;
+  /** Re-activate all modules that were activated by the given event. */
+  reset(event: ActivationEvent.ActivationEvent | string): Promise<boolean>;
+
+  /** Returns the first contributed capability for the given interface. Throws if none are present. */
+  get<T>(iface: Capability.InterfaceDef<T>): T;
+  /** Returns all contributed capabilities for the given interface. */
+  getAll<T>(iface: Capability.InterfaceDef<T>): T[];
+  /** Waits until at least one capability is contributed for the given interface. */
+  waitForCapability<T>(iface: Capability.InterfaceDef<T>, opts?: { timeout?: number }): Promise<T>;
+  /** Waits until the given activation event has completed. */
+  waitForEvent(event: ActivationEvent.ActivationEvent | string, opts?: { timeout?: number }): Promise<void>;
+
+  /** Invokes an operation through the `Capabilities.OperationInvoker` capability. */
+  invoke<I, O>(op: Operation.Definition<I, O>, ...args: void extends I ? [input?: I] : [input: I]): Promise<O>;
+
+  /**
+   * Waits for `Capabilities.ProcessManagerRuntime` and runs the given effect on it.
+   * Convenience around `waitForCapability(ProcessManagerRuntime).runPromise(effect)`.
+   */
+  runPromise<A, E>(
+    effect: Effect.Effect<A, E, Capabilities.ProcessManagerRuntimeServices>,
+    options?: { readonly timeout?: number; readonly signal?: AbortSignal },
+  ): Promise<A>;
+
+  enable(id: string): Promise<boolean>;
+  disable(id: string): Promise<boolean>;
+
+  /** Shuts down the underlying plugin manager. */
+  dispose(): Promise<void>;
+
+  /** Async-disposable support so tests can use `await using harness = ...`. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+/**
+ * Creates a TestHarness with the same bootstrap sequence that `useApp` performs,
+ * minus the React provider tree.
+ *
+ * For Node-only tests, this is enough to fire activation events, read
+ * capabilities, and invoke operations.
+ *
+ * For React tests, pass the returned harness to `render` or `renderSurface`
+ * from `@dxos/app-framework/testing-react`.
+ */
+export const createTestApp = async (opts: TestAppOptions): Promise<TestHarness> => {
+  const {
+    plugins,
+    enabled = plugins.filter(({ meta }) => !meta.tags?.includes('system')).map((plugin) => plugin.meta.id),
+    setupEvents = [],
+    autoStart = true,
+    registerFrameworkCapabilities = true,
+  } = opts;
+
+  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, enabled });
+
+  if (registerFrameworkCapabilities) {
+    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',
+    });
+  }
+
+  if (autoStart) {
+    try {
+      await runAndForwardErrors(
+        Effect.all([
+          ...setupEvents.map((event) => manager.activate(event)),
+          manager.activate(ActivationEvents.SetupReactSurface),
+          manager.activate(ActivationEvents.Startup),
+        ]),
+      );
+    } catch (err) {
+      await runAndForwardErrors(manager.shutdown()).catch(() => undefined);
+      throw err;
+    }
+  }
+
+  return new TestHarnessImpl(manager);
+};
+
+class TestHarnessImpl implements TestHarness {
+  constructor(readonly manager: PluginManager.PluginManager) {}
+
+  get capabilities(): CapabilityManager.CapabilityManager {
+    return this.manager.capabilities;
+  }
+
+  get registry(): Registry.Registry {
+    return this.manager.registry;
+  }
+
+  fire(event: ActivationEvent.ActivationEvent | string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.activate(event));
+  }
+
+  reset(event: ActivationEvent.ActivationEvent | string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.reset(event));
+  }
+
+  get<T>(iface: Capability.InterfaceDef<T>): T {
+    return this.manager.capabilities.get(iface);
+  }
+
+  getAll<T>(iface: Capability.InterfaceDef<T>): T[] {
+    return this.manager.capabilities.getAll(iface);
+  }
+
+  waitForCapability<T>(iface: Capability.InterfaceDef<T>, opts?: { timeout?: number }): Promise<T> {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+    return runAndForwardErrors(
+      this.manager.capabilities.waitFor(iface).pipe(
+        Effect.timeoutFail({
+          duration: Duration.millis(timeout),
+          onTimeout: () => timeoutError(iface.identifier),
+        }),
+      ),
+    );
+  }
+
+  waitForEvent(event: ActivationEvent.ActivationEvent | string, opts?: { timeout?: number }): Promise<void> {
+    const key = typeof event === 'string' ? event : ActivationEvent.eventKey(event);
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+
+    const program = Effect.gen(this, function* () {
+      const queue = yield* PubSub.subscribe(this.manager.activation);
+      // Re-check after subscribing to avoid a race where the event fires
+      // between the caller invoking this and the subscription being installed.
+      if (this.manager.getEventsFired().includes(key)) {
+        return;
+      }
+      while (true) {
+        const message = yield* Queue.take(queue);
+        if (message.event === key && message.state === 'activated') {
+          return;
+        }
+      }
+    }).pipe(
+      Effect.scoped,
+      Effect.timeoutFail({
+        duration: Duration.millis(timeout),
+        onTimeout: () => timeoutError(key),
+      }),
+    );
+
+    return runAndForwardErrors(program);
+  }
+
+  async invoke<I, O>(op: Operation.Definition<I, O>, ...args: [input?: I]): Promise<O> {
+    const invoker = await this.waitForCapability(Capabilities.OperationInvoker);
+    const result = await invoker.invokePromise(op as any, ...(args as [any]));
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data as O;
+  }
+
+  async runPromise<A, E>(
+    effect: Effect.Effect<A, E, Capabilities.ProcessManagerRuntimeServices>,
+    options?: { readonly timeout?: number; readonly signal?: AbortSignal },
+  ): Promise<A> {
+    const runtime = await this.waitForCapability(Capabilities.ProcessManagerRuntime, { timeout: options?.timeout });
+    return runtime.runPromise(effect, options?.signal ? { signal: options.signal } : undefined);
+  }
+
+  enable(id: string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.enable(id));
+  }
+
+  disable(id: string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.disable(id));
+  }
+
+  async dispose(): Promise<void> {
+    await runAndForwardErrors(this.manager.shutdown());
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.dispose();
+  }
+}
+
+const timeoutError = (id: string) => new Error(`Timed out waiting for ${id}`);

package/src/testing/index.ts

@@ -2,5 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './harness';
 export * from './service';
 export * from './withPluginManager';

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

@@ -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

@@ -21,13 +21,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,
   });
 
@@ -75,7 +77,6 @@ export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args
     // 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: storyId,
         root: () => <Story />,
@@ -115,13 +116,13 @@ const WithPluginManagerApp = ({ fireEvents, pluginManager, setupEvents, storyId
   }, [fireEvents, pluginManager, storyId]);
 
   const App = useApp({ pluginManager, setupEvents });
-
   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.

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

@@ -16,6 +16,7 @@ import { useApp } from '../../hooks';
 const TestPlugin = Plugin.define<{ error?: boolean }>({
   id: 'org.dxos.plugin.test',
   name: 'Test Plugin',
+  tags: ['system'],
 }).pipe(
   Plugin.addModule(({ error }) => ({
     id: 'TestMain',
@@ -46,20 +47,13 @@ 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 DefaultStory = ({ plugins }: DefaultStoryProps) => {
   const App = useApp({
     plugins,
-    core,
     placeholder: () => {
-      return (
-        <div role='none' className='text-description'>
-          Loading...
-        </div>
-      );
+      return <div className='text-description'>Loading...</div>;
     },
   });
 
@@ -67,7 +61,7 @@ const DefaultStory = ({ plugins }: StoryProps) => {
 };
 
 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,21 +2,45 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type PropsWithChildren } from 'react';
+import React, { type PropsWithChildren, useEffect } 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'> & {
   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 = ({ 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.
@@ -24,12 +48,12 @@ export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppPro
   }
 
   // TODO(wittjosiah): Consider using Suspense instead.
-  if (stage < LoadingState.Done) {
+  if (!placeholderDismissed) {
     if (!Placeholder) {
       return null;
     }
 
-    return <Placeholder stage={stage} />;
+    return <Placeholder stage={stage} progress={progress} />;
   }
 
   const ComposedContext = composeContexts(reactContexts);

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();
+  },
+};