@dxos/app-framework 0.10.0 → 0.11.0

package/src/core/plugin-manager.ts

@@ -2,17 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom, Registry } from '@effect-atom/atom-react';
+import { Atom, Registry } from '@effect-atom/atom';
 import * as Array from 'effect/Array';
 import * as Cause from 'effect/Cause';
 import * as Deferred from 'effect/Deferred';
 import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
 import * as Fiber from 'effect/Fiber';
 import * as Function from 'effect/Function';
 import * as HashSet from 'effect/HashSet';
 import * as PubSub from 'effect/PubSub';
 import * as Ref from 'effect/Ref';
+import * as Scope from 'effect/Scope';
 
 import { EffectEx, Performance } from '@dxos/effect';
 import { BaseError } from '@dxos/errors';
@@ -298,6 +300,7 @@ class ManagerImpl implements PluginManager {
   private readonly _loadTimeout: Duration.DurationInput;
   private readonly _activationTimeout: Duration.DurationInput;
   private readonly _capabilities = new Map<string, Capability.Any[]>();
+  private readonly _moduleScopes = new Map<string, Scope.CloseableScope>();
   private readonly _moduleMemoMap = new Map<Plugin.PluginModule['id'], Deferred.Deferred<Capability.Any[], Error>>();
   private readonly _moduleSemaphores = new Map<Plugin.PluginModule['id'], Effect.Semaphore>();
   // Coalesces concurrent `_resolveLazyPlugin` calls per plugin id. Without
@@ -991,6 +994,10 @@ class ManagerImpl implements PluginManager {
         this._set(this._eventsFiredAtom, []);
         this._set(this._pendingResetAtom, []);
         this._moduleMemoMap.clear();
+        for (const scope of this._moduleScopes.values()) {
+          yield* Scope.close(scope, Exit.void);
+        }
+        this._moduleScopes.clear();
         yield* Ref.set(this._activatingEvents, []);
         yield* Ref.set(this._activatingModules, []);
 
@@ -1534,6 +1541,7 @@ class ManagerImpl implements PluginManager {
         const deferred = yield* Deferred.make<Capability.Any[], Error>();
         this._moduleMemoMap.set(module.id, deferred);
 
+        const scope = yield* Scope.make();
         const loadEffect = Effect.gen(this, function* () {
           log('loading module', { module: module.id, parentEvent });
           performance.mark(`module:${module.id}:start`);
@@ -1542,6 +1550,7 @@ class ManagerImpl implements PluginManager {
           const [duration, capabilities] = yield* module.activate().pipe(
             Effect.provideService(Capability.Service, this.capabilities),
             Effect.provideService(Plugin.Service, this),
+            Scope.extend(scope),
             // Cap activation so a single misbehaving module can't hold the
             // event chain open. On timeout the failure is recorded against
             // the plugin and surfaced as `PluginTimeoutError`.
@@ -1555,6 +1564,7 @@ class ManagerImpl implements PluginManager {
             Effect.timed,
           );
           const normalized = capabilities == null ? [] : Array.isArray(capabilities) ? capabilities : [capabilities];
+          this._moduleScopes.set(module.id, scope);
           const elapsed = Duration.toMillis(duration);
           performance.mark(`module:${module.id}:end`);
           performance.measure(`module:${module.id}`, `module:${module.id}:start`, `module:${module.id}:end`);
@@ -1567,6 +1577,7 @@ class ManagerImpl implements PluginManager {
           });
           return normalized as Capability.Any[];
         }).pipe(
+          Effect.tapErrorCause(() => Scope.close(scope, Exit.void)),
           Effect.withSpan('PluginManager._loadModule'),
           together(
             Effect.sleep(Duration.seconds(10)).pipe(
@@ -1654,6 +1665,12 @@ class ManagerImpl implements PluginManager {
         this._capabilities.delete(id);
       }
 
+      const scope = this._moduleScopes.get(id);
+      if (scope) {
+        yield* Scope.close(scope, Exit.void);
+        this._moduleScopes.delete(id);
+      }
+
       const activeIndex = this._get(this._activeAtom).findIndex((event) => event === id);
       if (activeIndex !== -1) {
         this._update(this._activeAtom, (active) => active.filter((event) => event !== id));

package/src/core/plugin.ts

@@ -7,6 +7,7 @@ import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
 import * as Pipeable from 'effect/Pipeable';
 import * as Schema from 'effect/Schema';
+import type * as Scope from 'effect/Scope';
 
 import { BaseError } from '@dxos/errors';
 import { invariant } from '@dxos/invariant';
@@ -79,6 +80,18 @@ export const isPluginModule = (value: unknown): value is PluginModule => {
 /**
  * A unit of containment of modular functionality that can be provided to an application.
  * Activation of a module is async allowing for code to split and loaded lazily.
+ *
+ * Ordering between modules is expressed through shared activation events, not registration
+ * order: a module `activatesOn` an event, fires events *after* it activates via
+ * {@link PluginModule.firesAfterActivation} (publishing "I'm ready"), and forces prerequisites
+ * to complete *before* it activates via {@link PluginModule.firesBeforeActivation}. To run
+ * module B after module A, A declares `firesAfterActivation: [E]` and B declares
+ * `activatesOn: E`. See `plugin-client/src/ClientPlugin.ts` for a worked example.
+ *
+ * @idiom org.dxos.app-framework.moduleActivationOrdering
+ *   applies: sequencing one plugin module's activation before or after another
+ *   instead-of: assuming module registration order controls activation order
+ *   uses: {@link PluginModule.firesAfterActivation}, {@link PluginModule.firesBeforeActivation}
  */
 export interface PluginModule {
   readonly [PluginModuleTypeId]: PluginModuleTypeId;
@@ -128,7 +141,9 @@ export interface PluginModule {
    * @param props Optional props passed to the module.
    * @returns The capabilities of the module.
    */
-  activate: (props?: any) => Effect.Effect<Capability.ModuleReturn, Error, Capability.Service | Service | never>;
+  activate: (
+    props?: any,
+  ) => Effect.Effect<Capability.ModuleReturn, Error, Capability.Service | Service | Scope.Scope | never>;
 }
 
 export type PluginModuleOptions = Omit<PluginModule, 'id' | typeof PluginModuleTypeId> & { id?: string };

package/src/core/registry.ts

@@ -2,7 +2,7 @@
 // Copyright 2026 DXOS.org
 //
 
-import { Atom, type Registry as AtomRegistry } from '@effect-atom/atom-react';
+import { Atom, type Registry as AtomRegistry } from '@effect-atom/atom';
 import * as Effect from 'effect/Effect';
 
 import { EffectEx } from '@dxos/effect';

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

@@ -8,8 +8,15 @@ import * as Layer from 'effect/Layer';
 import * as ManagedRuntime from 'effect/ManagedRuntime';
 
 import { LayerSpec, OperationHandlerSet, Process, ServiceResolver, Trace } from '@dxos/compute';
-import { LayerStack, ProcessManager } from '@dxos/compute-runtime';
+import {
+  LayerStack,
+  ProcessManager,
+  ProcessMonitor,
+  RemoteProcessManager,
+  RemoteTraceMonitor,
+} from '@dxos/compute-runtime';
 import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
 // Explicit import so the emitted `.d.ts` references the package via its public
 // alias instead of a relative `node_modules` path (TS2883).
 import { OperationInvoker } from '@dxos/operation';
@@ -50,6 +57,10 @@ export default Capability.makeModule(
 
     const layerSpecs = yield* Capability.getAll(Capabilities.LayerSpec);
     const traceSinkFactories = yield* Capability.getAll(Capabilities.TraceSink);
+    // Optional swarm-backed remote trace source (DX-1125); first contribution wins, else empty.
+    const remoteTraceMonitors = yield* Capability.getAll(Capabilities.RemoteTraceMonitor);
+
+    log.info('setup process manager', { traceSinkFactories });
 
     // Forward reference to `ProcessManager.ProcessManagerService`. The runtime
     // that owns the manager depends transitively on `ServiceResolver` (which is
@@ -121,7 +132,19 @@ export default Capability.makeModule(
       Layer.provide(Layer.mergeAll(processManagerLayer, baseLayer)),
     );
 
-    const runtimeLayer = Layer.mergeAll(baseLayer, processManagerLayer, operationInvokerLayer);
+    // App-framework has no EDGE runtime, so the remote process view is empty;
+    // the aggregate monitor therefore equals the local process tree.
+    const remoteProcessManagerLayer = RemoteProcessManager.layerNoop.pipe(Layer.provide(baseLayer));
+    // Remote ephemeral trace (DX-1125): use the first contributed swarm-backed monitor, else no-op.
+    const remoteTraceMonitorLayer =
+      remoteTraceMonitors.length > 0
+        ? Layer.succeed(RemoteTraceMonitor.Service, remoteTraceMonitors[0])
+        : RemoteTraceMonitor.layerNoop;
+    const processMonitorLayer = ProcessMonitor.layer.pipe(
+      Layer.provide(Layer.mergeAll(processManagerLayer, remoteProcessManagerLayer, remoteTraceMonitorLayer, baseLayer)),
+    );
+
+    const runtimeLayer = Layer.mergeAll(baseLayer, processManagerLayer, operationInvokerLayer, processMonitorLayer);
 
     const managedRuntime = ManagedRuntime.make(runtimeLayer as Layer.Layer<any, any, never>);
 

package/src/testing/StorybookErrorFallback.tsx

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { ErrorFallback, type FallbackProps } from '@dxos/react-error-boundary';
+import { downloadLogs } from '@dxos/storybook-addon-logger/download';
+
+/**
+ * Default `ErrorBoundary` fallback for storybook-hosted apps (`withPluginManager`/`useApp`). Adds
+ * a "Download logs" action alongside the theme-independent default `ErrorFallback`, so a crashed
+ * story still offers a one-click way to grab the story's buffered logs, matching the manager
+ * toolbar's button (see `@dxos/storybook-addon-logger`).
+ *
+ * Deliberately does NOT depend on `@dxos/react-ui`'s themed components: `useApp`'s `ErrorBoundary`
+ * can catch failures that happen before/during an app's own theme setup, so its fallback must keep
+ * working even when no theme context is available — the same reason `ErrorFallback` itself uses
+ * inline styles rather than Tailwind/theme dependencies.
+ */
+export const StorybookErrorFallback = (props: FallbackProps) => (
+  <div>
+    <ErrorFallback {...props} />
+    <button
+      type='button'
+      onClick={downloadLogs}
+      style={{
+        margin: '0 1rem 1rem',
+        padding: '0.25rem 0.75rem',
+        fontSize: '0.875rem',
+        background: 'transparent',
+        border: '1px solid #888888',
+        borderRadius: '0.375rem',
+        cursor: 'pointer',
+      }}
+    >
+      Download logs
+    </button>
+  </div>
+);

package/src/testing/harness.ts

@@ -2,7 +2,7 @@
 // Copyright 2026 DXOS.org
 //
 
-import { type Registry } from '@effect-atom/atom-react';
+import { type Registry } from '@effect-atom/atom';
 import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as PubSub from 'effect/PubSub';

package/src/testing/index.ts

@@ -5,4 +5,6 @@
 export * from './harness';
 export * from './operationCapture';
 export * from './service';
+export * from './StorybookErrorFallback';
 export * from './withPluginManager';
+export * from './withSurfaceDebug';

package/src/testing/react.test.tsx

@@ -9,6 +9,7 @@ import { describe, test } from 'vitest';
 import { DXN } from '@dxos/keys';
 
 import { ActivationEvents, Capabilities } from '../common';
+import * as Role from '../common/Role';
 import { Capability, Plugin } from '../core';
 import { Surface } from '../ui';
 import { createTestApp } from './harness';
@@ -16,7 +17,7 @@ import { render, renderSurface } from './react';
 
 const testMeta = Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.test.reactHarness'), name: 'ReactHarnessTest' });
 
-const GreetingRole = Surface.makeType<{ message: string }>('org.dxos.test.role.greeting');
+const GreetingRole = Role.make<{ message: string }>('org.dxos.test.role.greeting');
 
 const TestPlugin = Plugin.define(testMeta).pipe(
   Plugin.addModule({

package/src/testing/react.tsx

@@ -4,16 +4,18 @@
 
 import { RegistryContext } from '@effect-atom/atom-react';
 import { type RenderOptions, type RenderResult, render as rtlRender } from '@testing-library/react';
-import React, { type FC, Fragment, type PropsWithChildren, type ReactNode } from 'react';
+import React, { type FC, Fragment, type PropsWithChildren, type ReactNode, useMemo } from 'react';
 
 import { ContextProtocolProvider } from '@dxos/web-context-react';
 
 import { Capabilities } from '../common';
+import * as Role from '../common/Role';
 import { PluginManagerContext } from '../context';
 import { topologicalSort } from '../helpers';
 import { PluginManagerProvider } from '../ui/components/PluginManager/PluginManagerProvider';
 import { SurfaceComponent } from '../ui/components/Surface/SurfaceComponent';
-import { type RoleToken } from '../ui/components/Surface/types';
+import { SurfaceManager } from '../ui/components/Surface/SurfaceManager';
+import { SurfaceManagerProvider } from '../ui/components/Surface/SurfaceManagerContext';
 import { type TestHarness } from './harness';
 
 export type HarnessRenderOptions = Omit<RenderOptions, 'wrapper'> & {
@@ -35,9 +37,9 @@ export const render = (harness: TestHarness, ui: ReactNode, options?: HarnessRen
   return rtlRender(<>{ui}</>, { ...rest, wrapper: Wrapper });
 };
 
-export type RenderSurfaceProps<TToken extends RoleToken<any>> = {
+export type RenderSurfaceProps<TToken extends Role.Role<any>> = {
   type: TToken;
-  data?: TToken extends RoleToken<infer D> ? D : never;
+  data?: TToken extends Role.Role<infer D> ? D : never;
   limit?: number;
   fallback?: FC<{ error: Error; data?: any }>;
   placeholder?: ReactNode;
@@ -46,7 +48,7 @@ export type RenderSurfaceProps<TToken extends RoleToken<any>> = {
 /**
  * Renders a `Surface` with the given role token/data inside the harness provider tree.
  */
-export const renderSurface = <TToken extends RoleToken<any>>(
+export const renderSurface = <TToken extends Role.Role<any>>(
   harness: TestHarness,
   props: RenderSurfaceProps<TToken>,
   options?: HarnessRenderOptions,
@@ -68,13 +70,17 @@ const HarnessProviders = ({ harness, extra, children }: HarnessProvidersProps) =
   const contributed = harness.getAll(Capabilities.ReactContext);
   const ContributedContext = composeContexts(contributed);
   const ExtraContext = composeExtra(extra);
+  // Mirror useApp's provider stack (see SurfaceManager) so the unit-test render path matches the app.
+  const surfaces = useMemo(() => new SurfaceManager(harness.manager.capabilities), [harness]);
   return (
     <PluginManagerProvider value={harness.manager}>
       <ContextProtocolProvider value={harness.manager} context={PluginManagerContext}>
         <RegistryContext.Provider value={harness.registry}>
-          <ContributedContext>
-            <ExtraContext>{children}</ExtraContext>
-          </ContributedContext>
+          <SurfaceManagerProvider value={surfaces}>
+            <ContributedContext>
+              <ExtraContext>{children}</ExtraContext>
+            </ContributedContext>
+          </SurfaceManagerProvider>
         </RegistryContext.Provider>
       </ContextProtocolProvider>
     </PluginManagerProvider>

package/src/testing/withPluginManager.stories.tsx

@@ -5,14 +5,16 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
+import { ThrowError } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
 
 import { Capabilities } from '../common';
+import * as Role from '../common/Role';
 import { Capability } from '../core';
 import { Surface } from '../ui';
 import { withPluginManager } from './withPluginManager';
 
-const MainRole = Surface.makeType<Record<string, never>>('org.dxos.test.role.main');
+const MainRole = Role.make<Record<string, never>>('org.dxos.test.role.main');
 
 const DefaultStory = () => {
   console.log('Render');
@@ -49,3 +51,16 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
+
+/**
+ * Demonstrates `withPluginManager`'s default fallback (`StorybookErrorFallback`): when the app
+ * throws, the theme-independent `ErrorFallback` renders with a "Download logs" button alongside
+ * the usual "Copy" action.
+ */
+export const Crashes: Story = {
+  render: () => <ThrowError />,
+  play: async () => {
+    // This story intentionally renders an ErrorBoundary fallback; clear the smoke-test error flag.
+    (window as any).__ERROR_BOUNDARY_ERRORS__ = [];
+  },
+};

package/src/testing/withPluginManager.tsx

@@ -15,6 +15,7 @@ import { type MaybeProvider, getProviderValue } from '@dxos/util';
 import { ActivationEvents, Capabilities } from '../common';
 import { type ActivationEvent, Capability, type CapabilityManager, Plugin, PluginManager } from '../core';
 import { type UseAppOptions, useApp } from '../ui';
+import { StorybookErrorFallback } from './StorybookErrorFallback';
 
 /**
  * @internal
@@ -50,6 +51,7 @@ export const setupPluginManager = ({
 };
 
 type ManagedPluginManagerState = {
+  fallback?: UseAppOptions['fallback'];
   fireEvents?: (ActivationEvent.ActivationEvent | string)[];
   pluginManager: PluginManager.PluginManager;
   setupEvents?: ActivationEvent.ActivationEvent[];
@@ -94,6 +96,7 @@ export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args
         pluginManager,
         setupEvents: options.setupEvents,
         fireEvents: options.fireEvents,
+        fallback: options.fallback,
         storyId,
       });
 
@@ -112,13 +115,21 @@ export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args
   };
 };
 
-const WithPluginManagerApp = ({ fireEvents, pluginManager, setupEvents, storyId }: ManagedPluginManagerState) => {
+const WithPluginManagerApp = ({
+  fallback,
+  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 });
+  // Default to a fallback that offers "Download logs" so a crashed story is still debuggable;
+  // callers can override via `withPluginManager({ fallback })`.
+  const App = useApp({ pluginManager, setupEvents, fallback: fallback ?? StorybookErrorFallback });
   return <App />;
 };
 

package/src/testing/withSurfaceDebug.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Decorator } from '@storybook/react';
+import React from 'react';
+
+import { Surface } from '../ui';
+
+/**
+ * Storybook decorator that enables the surface debug overlays (`<dx-surface>` wrappers + boundary
+ * badges) for the wrapped story. The flag is a `window` singleton, so it is (re)applied on every
+ * render — enabling it on decorated stories and clearing it otherwise, so the setting never leaks
+ * between stories. Prefer this over the `.storybook/preview` flag when the story must also render
+ * under the aggregate root Storybook, which does not load a per-package preview.
+ */
+export const withSurfaceDebug =
+  (enabled = true): Decorator =>
+  (Story) => {
+    Surface.setDebug(enabled);
+    return <Story />;
+  };

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

@@ -7,36 +7,9 @@ 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';
+import { bootLoader } from './loader';
 
-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;
-    };
-  }
-}
+const FIRST_INTERACTIVE_MARK = 'app-framework:first-interactive';
 
 export type AppProps = Pick<UseAppOptions, 'debounce'> & {
   ready: boolean;
@@ -44,8 +17,6 @@ export type AppProps = Pick<UseAppOptions, 'debounce'> & {
   progress?: StartupProgress;
 };
 
-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);
@@ -62,10 +33,11 @@ export const App = ({ ready, error, debounce, progress }: AppProps) => {
     if (stage >= LoadingState.FadeOut) {
       return;
     }
+
     const fraction = progress?.progress ?? 0;
-    window.__bootLoader?.progress(0.5 + fraction * 0.5);
+    bootLoader?.progress(0.5 + fraction * 0.5);
     if (progress?.humanizedName) {
-      window.__bootLoader?.status({
+      bootLoader?.status({
         event: progress.event,
         module: progress.module,
         humanized: `Activating ${progress.humanizedName}`,
@@ -78,7 +50,7 @@ export const App = ({ ready, error, debounce, progress }: AppProps) => {
   // same frame the real shell starts rendering beneath it.
   useLayoutEffect(() => {
     if (stage >= LoadingState.FadeOut) {
-      window.__bootLoader?.ready();
+      bootLoader?.ready();
     }
   }, [stage]);
 
@@ -97,7 +69,7 @@ export const App = ({ ready, error, debounce, progress }: AppProps) => {
     if (performance.getEntriesByName(FIRST_INTERACTIVE_MARK).length === 0) {
       performance.mark(FIRST_INTERACTIVE_MARK);
     }
-    window.__bootLoader?.dismiss();
+    bootLoader?.dismiss();
   }, [placeholderDismissed]);
 
   // Used in tests to exercise the error boundary & reset dialog (see

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

@@ -3,3 +3,4 @@
 //
 
 export * from './App';
+export * from './loader';

package/src/ui/components/App/loader.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+declare global {
+  interface 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;
+  }
+
+  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?: BootLoader;
+  }
+}
+
+// Guarded: `@dxos/app-framework/ui` has a `node` export and this module is re-exported through the
+// UI barrel, so a bare top-level `window` read would throw when imported in SSR / tests / tooling.
+export const bootLoader = typeof window !== 'undefined' ? window.__bootLoader : undefined;

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

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Button } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { HomeSection } from './HomeSection';
+
+const DefaultStory = () => (
+  <HomeSection.Root>
+    <HomeSection.Header title='Recent' onClose={() => {}} />
+    <div className='rounded-sm bg-group-surface p-4 text-description'>Section content.</div>
+  </HomeSection.Root>
+);
+
+const WithActionsStory = () => (
+  <HomeSection.Root>
+    <HomeSection.Header title='Activity' onClose={() => {}}>
+      <Button variant='ghost'>All</Button>
+      <Button variant='ghost'>30d</Button>
+    </HomeSection.Header>
+    <div className='rounded-sm bg-group-surface p-4 text-description'>Section content.</div>
+  </HomeSection.Root>
+);
+
+const meta = {
+  title: 'sdk/app-framework/components/HomeSection',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen', classNames: 'p-4' })],
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithActions: Story = { render: WithActionsStory };

package/src/ui/components/HomeSection/HomeSection.tsx

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, forwardRef } from 'react';
+
+import { SystemIconButton, type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+//
+// Root
+//
+
+type HomeSectionRootProps = ThemedClassName<PropsWithChildren>;
+
+/**
+ * Shared container for a Home content section: a centered, max-width column. Home surface
+ * contributors (welcome, recent, dashboard, suggestions) render inside one so they share a
+ * consistent width and rhythm regardless of which plugin owns them.
+ */
+const HomeSectionRoot = forwardRef<HTMLDivElement, HomeSectionRootProps>(({ classNames, children }, forwardedRef) => (
+  <div ref={forwardedRef} className={mx('flex flex-col w-full mx-auto max-w-[40rem]', classNames)}>
+    {children}
+  </div>
+));
+
+HomeSectionRoot.displayName = 'HomeSection.Root';
+
+//
+// Header
+//
+
+type HomeSectionHeaderProps = ThemedClassName<
+  PropsWithChildren<{
+    /** Section heading. */
+    title?: string;
+    /** When provided, renders a close affordance that hides the section. */
+    onClose?: () => void;
+  }>
+>;
+
+/**
+ * Header row for a Home section: a muted title, an optional trailing actions slot (`children`),
+ * and an optional close affordance. `children` render before the close button so section-specific
+ * controls (e.g. a range selector) sit inline with it.
+ */
+const HomeSectionHeader = forwardRef<HTMLDivElement, HomeSectionHeaderProps>(
+  ({ title, onClose, classNames, children }, forwardedRef) => (
+    <div ref={forwardedRef} className={mx('flex items-center gap-2', classNames)}>
+      {title && <h2 className='grow truncate text-sm font-medium text-description'>{title}</h2>}
+      {!title && <span className='grow' />}
+      {children}
+      {onClose && <SystemIconButton.Close variant='ghost' iconOnly onClick={onClose} />}
+    </div>
+  ),
+);
+
+HomeSectionHeader.displayName = 'HomeSection.Header';
+
+//
+// HomeSection
+//
+
+export const HomeSection = {
+  Root: HomeSectionRoot,
+  Header: HomeSectionHeader,
+};
+
+export type { HomeSectionHeaderProps, HomeSectionRootProps };