@dxos/app-framework 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

package/src/plugin-process-manager/history/history-tracker.test.ts

@@ -7,6 +7,8 @@ import * as Effect from 'effect/Effect';
 import * as Fiber from 'effect/Fiber';
 import * as Layer from 'effect/Layer';
 import * as ManagedRuntime from 'effect/ManagedRuntime';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
 import * as TestClock from 'effect/TestClock';
 import { describe, expect } from 'vitest';
 
@@ -15,7 +17,6 @@ import { OperationInvoker } from '@dxos/operation';
 
 const testRuntime = ManagedRuntime.make(Layer.empty) as unknown as ManagedRuntime.ManagedRuntime<any, any>;
 
-import { UndoOperation } from '../../common';
 import {
   Compute,
   HalveCompute,
@@ -66,7 +67,7 @@ describe('HistoryTracker', () => {
 
       yield* invoker.invoke(ToString, { value: 42 });
 
-      // Wait for event to be processed.
+      // Wait for the pending + success events to be processed.
       yield* collector.waitForEvents(1);
 
       // Without an undo mapping, canUndo should remain false.
@@ -123,7 +124,7 @@ describe('HistoryTracker', () => {
       const tracker = HistoryTracker.make(invoker, undoRegistry);
       const collector = yield* createEventCollector(invoker);
 
-      // Fork compute operation (should emit event).
+      // Fork compute operation (emits one success event).
       const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
       yield* TestClock.adjust('20 millis');
       yield* Fiber.join(fiber);
@@ -134,7 +135,7 @@ describe('HistoryTracker', () => {
       // Wait until the tracker has processed the event.
       yield* waitUntil(() => tracker.canUndo());
 
-      // Undo (should NOT emit event because it uses _invokeCore).
+      // Undo (should NOT emit events because it uses _invokeCore).
       yield* tracker.undo();
 
       // Verify no new events were emitted.
@@ -173,7 +174,7 @@ describe('HistoryTracker', () => {
       yield* TestClock.adjust('30 millis');
       yield* Fiber.join(fiber2);
 
-      // Wait for both events to be collected.
+      // Each invoke emits one success event.
       yield* collector.waitForEvents(2);
 
       // First undo should halve 6 (the output of the second compute).
@@ -193,8 +194,10 @@ describe('HistoryTracker', () => {
   it.effect('undo on empty history returns error', () =>
     Effect.gen(function* () {
       const invoker = OperationInvoker.make(() => Effect.succeed([]), testRuntime);
-      const undoRegistry = UndoRegistry.make(() => []);
-      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const tracker = HistoryTracker.make(
+        invoker,
+        UndoRegistry.make(() => []),
+      );
 
       const result = yield* tracker.undo().pipe(Effect.either);
       expect(result._tag).toBe('Left');
@@ -204,7 +207,7 @@ describe('HistoryTracker', () => {
     }),
   );
 
-  it.effect('fires ShowUndo operation when undoable operation is tracked', () =>
+  it.effect('publishes an undoable event with the resolved message', () =>
     Effect.gen(function* () {
       const testMessage: [string, { ns: string }] = ['test-undo.message', { ns: 'test' }];
       const undoMapping = UndoMapping.make({
@@ -214,39 +217,28 @@ describe('HistoryTracker', () => {
         message: testMessage,
       });
 
-      let showUndoWasCalled = false;
-      let showUndoMessage: unknown = undefined;
-      const showUndoHandler = Operation.withHandler(UndoOperation.ShowUndo, (input) => {
-        showUndoWasCalled = true;
-        showUndoMessage = input.message;
-        return Effect.succeed(undefined);
-      });
-
-      const invoker = OperationInvoker.make(
-        () => Effect.succeed([computeHandler, halveComputeHandler, showUndoHandler]),
-        testRuntime,
-      );
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
       const undoRegistry = UndoRegistry.make(() => [undoMapping]);
       const tracker = HistoryTracker.make(invoker, undoRegistry);
 
-      expect(showUndoWasCalled).toBe(false);
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const undoables = yield* PubSub.subscribe(tracker.undoable);
 
-      // Fork compute operation and advance clock.
-      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
-      yield* TestClock.adjust('20 millis');
-      yield* Fiber.join(fiber);
-
-      // Wait until the tracker has processed the event.
-      yield* waitUntil(() => tracker.canUndo());
+          // Fork compute operation and advance clock.
+          const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+          yield* TestClock.adjust('20 millis');
+          yield* Fiber.join(fiber);
 
-      // ShowUndo should have been called with the message from the undo mapping.
-      yield* waitUntil(() => showUndoWasCalled);
-      expect(showUndoWasCalled).toBe(true);
-      expect(showUndoMessage).toEqual(testMessage);
+          const undoable = yield* Queue.take(undoables);
+          expect(undoable.message).toEqual(testMessage);
+        }),
+      );
+      expect(tracker.canUndo()).toBe(true);
     }),
   );
 
-  it.effect('ShowUndo message can be derived from input and output', () =>
+  it.effect('undo message can be derived from input and output', () =>
     Effect.gen(function* () {
       // Dynamic message that depends on input/output.
       const dynamicMessage = (input: { value: number }, output: { value: number }): [string, { ns: string }] => [
@@ -260,36 +252,23 @@ describe('HistoryTracker', () => {
         message: dynamicMessage,
       });
 
-      let showUndoWasCalled = false;
-      let showUndoMessage: unknown = undefined;
-      const showUndoHandler = Operation.withHandler(UndoOperation.ShowUndo, (input) => {
-        showUndoWasCalled = true;
-        showUndoMessage = input.message;
-        return Effect.succeed(undefined);
-      });
-
-      const invoker = OperationInvoker.make(
-        () => Effect.succeed([computeHandler, halveComputeHandler, showUndoHandler]),
-        testRuntime,
-      );
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
       const undoRegistry = UndoRegistry.make(() => [undoMapping]);
       const tracker = HistoryTracker.make(invoker, undoRegistry);
 
-      expect(showUndoWasCalled).toBe(false);
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const undoables = yield* PubSub.subscribe(tracker.undoable);
 
-      // Fork compute operation and advance clock (same as passing test).
-      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
-      yield* TestClock.adjust('20 millis');
-      yield* Fiber.join(fiber);
-
-      // Wait until the tracker has processed the event.
-      yield* waitUntil(() => tracker.canUndo());
+          // Fork compute operation and advance clock (2 * 2 = 4).
+          const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+          yield* TestClock.adjust('20 millis');
+          yield* Fiber.join(fiber);
 
-      // ShowUndo should have been called with the derived message.
-      yield* waitUntil(() => showUndoWasCalled);
-      expect(showUndoWasCalled).toBe(true);
-      // Compute 2 * 2 = 4, so message should be 'computed 2 to 4'.
-      expect(showUndoMessage).toEqual(['computed-2-to-4', { ns: 'test' }]);
+          const undoable = yield* Queue.take(undoables);
+          expect(undoable.message).toEqual(['computed-2-to-4', { ns: 'test' }]);
+        }),
+      );
     }),
   );
 
@@ -320,7 +299,7 @@ describe('HistoryTracker', () => {
       yield* TestClock.adjust('20 millis');
       yield* Fiber.join(fiber);
 
-      // Wait for event to be processed.
+      // Wait for the pending + success events to be processed.
       yield* collector.waitForEvents(1);
 
       // Even though there's an undo mapping, deriveContext returned undefined,
@@ -359,7 +338,7 @@ describe('HistoryTracker', () => {
       yield* TestClock.adjust('50 millis');
       yield* Fiber.join(fiber);
 
-      // Wait for event to be processed.
+      // Wait for the pending + success events to be processed.
       yield* collector.waitForEvents(1);
 
       // Wait until the tracker has processed the event.

package/src/plugin-process-manager/history/history-tracker.ts

@@ -3,13 +3,14 @@
 //
 
 import * as Effect from 'effect/Effect';
+import * as PubSub from 'effect/PubSub';
 import * as Stream from 'effect/Stream';
 
 import { runAndForwardErrors } from '@dxos/effect';
 import { log } from '@dxos/log';
 import { OperationInvoker } from '@dxos/operation';
 
-import { UndoOperation } from '../../common';
+import { type Label } from '../../common';
 import { EmptyHistoryError } from './errors';
 import type { HistoryEntry } from './types';
 import { resolveMessage } from './undo-mapping';
@@ -21,6 +22,15 @@ const HISTORY_LIMIT = 100;
 // Public Interface
 //
 
+/**
+ * Emitted when a new undoable action is recorded; consumed by the UI to surface an undo affordance
+ * (e.g. the deck notification tracker's undo toast).
+ */
+export type UndoableEvent = {
+  /** Message describing the undoable action. */
+  message?: Label;
+};
+
 /**
  * HistoryTracker interface - tracks operation history and provides undo.
  */
@@ -28,6 +38,8 @@ export interface HistoryTracker {
   undo: () => Effect.Effect<void, Error>;
   undoPromise: () => Promise<{ error?: Error }>;
   canUndo: () => boolean;
+  /** Stream of undoable actions, published as they are recorded. */
+  undoable: PubSub.PubSub<UndoableEvent>;
 }
 
 //
@@ -35,27 +47,29 @@ export interface HistoryTracker {
 //
 
 /**
- * Creates a HistoryTracker that subscribes to invocation events and provides undo.
+ * Creates a HistoryTracker that subscribes to (successful) invocation events, derives undoability from
+ * the undo registry, maintains the undo stack, and publishes an {@link UndoableEvent} for each undoable
+ * action so the UI can offer an undo affordance. The invoker itself is undo-agnostic.
  */
 export const make = (
   invoker: OperationInvoker.OperationInvokerInternal,
   undoRegistry: UndoRegistry,
 ): HistoryTracker => {
   const history: HistoryEntry[] = [];
+  const undoable = Effect.runSync(PubSub.unbounded<UndoableEvent>());
 
-  // Subscribe to invocation stream.
-  const handleInvocation = (event: OperationInvoker.InvocationEvent) => {
+  // Record an invocation; returns the undoable event to publish, or undefined if not undoable.
+  const recordInvocation = (event: OperationInvoker.InvocationEvent): UndoableEvent | undefined => {
     const mapping = undoRegistry.lookup(event.operation);
     if (!mapping) {
-      // Operation is not undoable, skip.
-      return;
+      // Operation is not undoable.
+      return undefined;
     }
 
     const inverseInput = mapping.deriveContext(event.input, event.output);
     if (inverseInput === undefined) {
       // Operation is conditionally not undoable (deriveContext returned undefined).
-      log('operation not undoable', { key: event.operation.meta.key });
-      return;
+      return undefined;
     }
 
     const entry: HistoryEntry = {
@@ -75,19 +89,20 @@ export const make = (
       history.splice(0, history.length - HISTORY_LIMIT);
     }
 
-    // Show undo toast (resolve message if it's a function).
-    const resolvedMessage = resolveMessage(mapping.message, event.input, event.output);
-    Effect.runFork(
-      invoker.invoke(UndoOperation.ShowUndo, {
-        message: resolvedMessage,
-      }),
-    );
+    return { message: resolveMessage(mapping.message, event.input, event.output) };
   };
 
   // Fork a fiber to consume the invocation stream.
   Effect.runFork(
     Stream.fromPubSub(invoker.invocations).pipe(
-      Stream.runForEach((event) => Effect.sync(() => handleInvocation(event))),
+      Stream.runForEach((event) =>
+        Effect.gen(function* () {
+          const undoableEvent = recordInvocation(event);
+          if (undoableEvent) {
+            yield* PubSub.publish(undoable, undoableEvent);
+          }
+        }),
+      ),
     ),
   );
 
@@ -124,5 +139,6 @@ export const make = (
     undo,
     undoPromise,
     canUndo,
+    undoable,
   };
 };

package/src/plugin-process-manager/history/undo-mapping.ts

@@ -7,7 +7,7 @@ import type { Operation } from '@dxos/compute';
 /**
  * Label type for translatable text (canonical definition in @dxos/app-toolkit).
  */
-type Label = string | [string, { ns: string; count?: number; defaultValue?: string }];
+type Label = string | [string, { ns: string | readonly string[]; count?: number; defaultValue?: string }];
 
 /**
  * Extract the input type from an OperationDefinition.

package/src/plugin-process-manager/history/undo-registry.test.ts

@@ -4,6 +4,8 @@
 
 import { describe, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
 import { Compute, HalveCompute } from '../testing';
 import * as UndoMapping from './undo-mapping';
 import * as UndoRegistry from './undo-registry';
@@ -19,7 +21,7 @@ describe('UndoRegistry', () => {
 
     const result = registry.lookup(Compute);
     expect(result).not.toBe(undefined);
-    expect(result?.inverse.meta.key).toBe('test.halve-compute');
+    expect(result?.inverse.meta.key).toBe(DXN.make('org.dxos.test.halveCompute'));
   });
 
   test('returns undefined for unmapped operations', ({ expect }) => {

package/src/plugin-process-manager/meta.ts

@@ -2,13 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Plugin } from '../core';
+import { DXN } from '@dxos/keys';
 
-export const meta: Plugin.Meta = {
-  id: 'org.dxos.plugin.process-manager',
+import { Plugin } from '../core';
+
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.processManager'),
   name: 'Process Manager Plugin',
   author: 'DXOS',
   description:
     'Hosts the process-manager runtime that composes contributed layer specs into a service resolver, exposes the operation invoker built on top of it, and registers undo/history tracking.',
   tags: ['system'],
-};
+});

package/src/plugin-process-manager/testing.ts

@@ -10,6 +10,7 @@ import * as Schema from 'effect/Schema';
 import * as Stream from 'effect/Stream';
 
 import { Operation } from '@dxos/compute';
+import { DXN } from '@dxos/keys';
 import { OperationInvoker } from '@dxos/operation';
 
 //
@@ -19,31 +20,31 @@ import { OperationInvoker } from '@dxos/operation';
 export const Compute = Operation.make({
   input: Schema.Struct({ value: Schema.Number }),
   output: Schema.Struct({ value: Schema.Number }),
-  meta: { key: 'test.compute' },
+  meta: { key: DXN.make('org.dxos.test.compute') },
 });
 
 export const HalveCompute = Operation.make({
   input: Schema.Struct({ value: Schema.Number }),
   output: Schema.Struct({ value: Schema.Number }),
-  meta: { key: 'test.halve-compute' },
+  meta: { key: DXN.make('org.dxos.test.halveCompute') },
 });
 
 export const ToString = Operation.make({
   input: Schema.Struct({ value: Schema.Number }),
   output: Schema.Struct({ string: Schema.String }),
-  meta: { key: 'test.to-string' },
+  meta: { key: DXN.make('org.dxos.test.toString') },
 });
 
 export const Add = Operation.make({
   input: Schema.Tuple(Schema.Number, Schema.Number),
   output: Schema.Number,
-  meta: { key: 'test.add' },
+  meta: { key: DXN.make('org.dxos.test.add') },
 });
 
 export const SideEffect = Operation.make({
   input: Schema.Void,
   output: Schema.Void,
-  meta: { key: 'test.side-effect' },
+  meta: { key: DXN.make('org.dxos.test.sideEffect') },
 });
 
 //

package/src/testing/react.test.tsx

@@ -6,13 +6,15 @@ import * as Effect from 'effect/Effect';
 import React from 'react';
 import { describe, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
 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 testMeta = Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.test.reactHarness'), name: 'ReactHarnessTest' });
 
 const TestPlugin = Plugin.define(testMeta).pipe(
   Plugin.addModule({

package/src/testing/withPluginManager.tsx

@@ -8,6 +8,7 @@ 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';
 
@@ -119,11 +120,11 @@ const WithPluginManagerApp = ({ fireEvents, pluginManager, setupEvents, storyId
   return <App />;
 };
 
-const storyMeta = {
-  id: 'org.dxos.app-framework.story',
+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.

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,11 +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',
-  tags: ['system'],
-}).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,
@@ -50,12 +53,7 @@ const TestPlugin = Plugin.define<{ error?: boolean }>({
 type DefaultStoryProps = { plugins?: Plugin.Plugin[] };
 
 const DefaultStory = ({ plugins }: DefaultStoryProps) => {
-  const App = useApp({
-    plugins,
-    placeholder: () => {
-      return <div className='text-description'>Loading...</div>;
-    },
-  });
+  const App = useApp({ plugins });
 
   return <App />;
 };

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

@@ -2,13 +2,43 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type PropsWithChildren, useEffect } from 'react';
+import React, { type PropsWithChildren, useEffect, useLayoutEffect } 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'> & {
+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;
@@ -16,22 +46,50 @@ export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
 
 const FIRST_INTERACTIVE_MARK = 'app-framework:first-interactive';
 
-export const App = ({ placeholder: Placeholder, ready, error, debounce, progress }: AppProps) => {
+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 placeholder is dismissed and the real app shell renders. Closes the
-  // gap between `Startup` activated and the first interactive paint.
+  // the loader 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).
+  // 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;
@@ -39,21 +97,26 @@ export const App = ({ placeholder: Placeholder, ready, error, debounce, progress
     if (performance.getEntriesByName(FIRST_INTERACTIVE_MARK).length === 0) {
       performance.mark(FIRST_INTERACTIVE_MARK);
     }
-    (window as { __bootLoader?: { dismiss?: () => void } }).__bootLoader?.dismiss?.();
+    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 (!placeholderDismissed) {
-    if (!Placeholder) {
-      return null;
-    }
-
-    return <Placeholder stage={stage} progress={progress} />;
+    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';
 
@@ -117,11 +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',
-  tags: ['system'],
-}).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,
@@ -155,17 +158,9 @@ const CounterPlugin = Plugin.define({
 )();
 
 const plugins = [CounterPlugin];
-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,
-    placeholder,
-  });
+  const App = useApp({ plugins });
 
   return <App />;
 };