@dxos/app-framework 0.8.4-main.b97322e → 0.8.4-main.bcb3aa67d6

package/src/ui/components/Surface/SurfaceProfilerContext.tsx

@@ -0,0 +1,207 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, {
+  type Context,
+  type PropsWithChildren,
+  type ProfilerOnRenderCallback,
+  createContext,
+  useContext,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+
+const MAX_ENTRIES = 500;
+
+/**
+ * Single profiler record captured from React Profiler onRender callback.
+ */
+export type SurfaceProfilerEntry = {
+  id: string;
+  phase: 'mount' | 'update' | 'nested-update';
+  actualDuration: number;
+  baseDuration: number;
+  startTime: number;
+  commitTime: number;
+  timestamp: number;
+};
+
+/**
+ * Aggregated stats for a single profiled surface.
+ */
+export type SurfaceProfilerStats = {
+  id: string;
+  mountCount: number;
+  updateCount: number;
+  totalRenders: number;
+  avgActualDuration: number;
+  maxActualDuration: number;
+  avgBaseDuration: number;
+  lastActualDuration: number;
+  lastCommitTime: number;
+};
+
+/**
+ * Store that collects profiler entries and notifies subscribers.
+ */
+class SurfaceProfilerStore {
+  private _entries: SurfaceProfilerEntry[] = [];
+  private _listeners = new Set<() => void>();
+  private _snapshot: readonly SurfaceProfilerEntry[] = [];
+  private _pendingNotify = false;
+
+  /** Records an entry and schedules a deferred notification to avoid re-render loops. */
+  record(entry: SurfaceProfilerEntry) {
+    this._entries.push(entry);
+    if (this._entries.length > MAX_ENTRIES) {
+      this._entries = this._entries.slice(-MAX_ENTRIES);
+    }
+    this._snapshot = [...this._entries];
+    this._scheduleNotify();
+  }
+
+  clear() {
+    this._entries = [];
+    this._snapshot = [];
+    this._notifySync();
+  }
+
+  subscribe = (listener: () => void) => {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  };
+
+  getSnapshot = (): readonly SurfaceProfilerEntry[] => {
+    return this._snapshot;
+  };
+
+  /**
+   * Defers notification to the next animation frame to break the
+   * Profiler onRender → record → notify → re-render → onRender loop.
+   */
+  private _scheduleNotify() {
+    if (!this._pendingNotify) {
+      this._pendingNotify = true;
+      requestAnimationFrame(() => {
+        this._pendingNotify = false;
+        this._notifySync();
+      });
+    }
+  }
+
+  private _notifySync() {
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+}
+
+type SurfaceProfilerContextValue = {
+  store: SurfaceProfilerStore;
+};
+
+const SurfaceProfilerContext: Context<SurfaceProfilerContextValue | undefined> = createContext<
+  SurfaceProfilerContextValue | undefined
+>(undefined);
+
+/**
+ * Provider that collects React Profiler data from Surface components.
+ */
+export const SurfaceProfilerProvider = ({ children }: PropsWithChildren) => {
+  const storeRef = useRef<SurfaceProfilerStore>(null);
+  if (!storeRef.current) {
+    storeRef.current = new SurfaceProfilerStore();
+  }
+  return (
+    <SurfaceProfilerContext.Provider value={{ store: storeRef.current }}>{children}</SurfaceProfilerContext.Provider>
+  );
+};
+
+/**
+ * Returns a stable onRender callback for use with React Profiler.
+ */
+export const useSurfaceProfilerCallback = (): ProfilerOnRenderCallback | undefined => {
+  const store = useContext(SurfaceProfilerContext)?.store;
+  return useMemo<ProfilerOnRenderCallback | undefined>(() => {
+    if (!store) {
+      return undefined;
+    }
+    return (id, phase, actualDuration, baseDuration, startTime, commitTime) => {
+      store.record({
+        id,
+        phase,
+        actualDuration,
+        baseDuration,
+        startTime,
+        commitTime,
+        timestamp: Date.now(),
+      });
+    };
+  }, [store]);
+};
+
+/**
+ * Returns all profiler entries reactively.
+ */
+export const useSurfaceProfilerEntries = (): readonly SurfaceProfilerEntry[] => {
+  const context = useContext(SurfaceProfilerContext);
+  return useSyncExternalStore(context?.store.subscribe ?? noop, context?.store.getSnapshot ?? emptySnapshot);
+};
+
+/**
+ * Returns aggregated stats grouped by surface id.
+ */
+export const useSurfaceProfilerStats = (): SurfaceProfilerStats[] => {
+  const entries = useSurfaceProfilerEntries();
+  const statsMap = new Map<string, SurfaceProfilerStats>();
+
+  for (const entry of entries) {
+    let stats = statsMap.get(entry.id);
+    if (!stats) {
+      stats = {
+        id: entry.id,
+        mountCount: 0,
+        updateCount: 0,
+        totalRenders: 0,
+        avgActualDuration: 0,
+        maxActualDuration: 0,
+        avgBaseDuration: 0,
+        lastActualDuration: 0,
+        lastCommitTime: 0,
+      };
+      statsMap.set(entry.id, stats);
+    }
+
+    if (entry.phase === 'mount') {
+      stats.mountCount++;
+    } else {
+      stats.updateCount++;
+    }
+    stats.totalRenders++;
+    stats.avgActualDuration =
+      (stats.avgActualDuration * (stats.totalRenders - 1) + entry.actualDuration) / stats.totalRenders;
+    stats.avgBaseDuration =
+      (stats.avgBaseDuration * (stats.totalRenders - 1) + entry.baseDuration) / stats.totalRenders;
+    stats.maxActualDuration = Math.max(stats.maxActualDuration, entry.actualDuration);
+    stats.lastActualDuration = entry.actualDuration;
+    stats.lastCommitTime = entry.commitTime;
+  }
+
+  return [...statsMap.values()].sort((a, b) => b.maxActualDuration - a.maxActualDuration);
+};
+
+/**
+ * Clears all collected profiler entries.
+ */
+export const useSurfaceProfilerClear = (): (() => void) | undefined => {
+  const store = useContext(SurfaceProfilerContext)?.store;
+  return useMemo(() => (store ? () => store.clear() : undefined), [store]);
+};
+
+const noop = () => () => {};
+const EMPTY_SNAPSHOT: readonly SurfaceProfilerEntry[] = [];
+const emptySnapshot = () => EMPTY_SNAPSHOT;

package/src/ui/components/Surface/context.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Context, createContext } from 'react';
+
+import { type Props } from './types';
+
+export type SurfaceContext = Pick<Props, 'id' | 'role' | 'data'>;
+
+// TODO(burdon): Use @radix-ui/react-context
+export const SurfaceContext: Context<SurfaceContext | undefined> = createContext<SurfaceContext | undefined>(undefined);

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

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Cleanup to avoid re-naming.
+import { SurfaceContext } from './context';
+import { SurfaceComponent, isSurfaceAvailable } from './SurfaceComponent';
+import {
+  SurfaceProfilerProvider,
+  useSurfaceProfilerCallback,
+  useSurfaceProfilerClear,
+  useSurfaceProfilerEntries,
+  useSurfaceProfilerStats,
+} from './SurfaceProfilerContext';
+import { type Definition as SurfaceDefinition, create as createSurface, createWeb as createWebSurface } from './types';
+
+export namespace Surface {
+  export type Definition = SurfaceDefinition;
+  export const create = createSurface;
+  export const createWeb = createWebSurface;
+
+  export type Context = SurfaceContext;
+  export const Context = SurfaceContext;
+
+  export const Surface = SurfaceComponent;
+  export const isAvailable = isSurfaceAvailable;
+
+  export const ProfilerProvider = SurfaceProfilerProvider;
+  export const useProfilerCallback = useSurfaceProfilerCallback;
+  export const useProfilerEntries = useSurfaceProfilerEntries;
+  export const useProfilerStats = useSurfaceProfilerStats;
+  export const useProfilerClear = useSurfaceProfilerClear;
+}
+
+export type { SurfaceProfilerEntry, SurfaceProfilerStats } from './SurfaceProfilerContext';

package/src/ui/components/Surface/types.ts

@@ -0,0 +1,117 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { FC, PropsWithChildren, ReactNode, RefCallback } from 'react';
+
+import type { MakeOptional, Position } from '@dxos/util';
+
+/**
+ * Props that are passed to the Surface component.
+ */
+export type Props<T extends Record<string, any> = Record<string, unknown>> = {
+  /**
+   * If specified, the Surface will be wrapped in an error boundary.
+   * The fallback component will be rendered if an error occurs.
+   */
+  fallback?: FC<{ error: Error; data?: any }>;
+
+  /**
+   * If specified, the Surface will be wrapped in a suspense boundary.
+   * The placeholder component will be rendered while the surface component is loading.
+   */
+  placeholder?: ReactNode;
+} & MakeOptional<CoreProps<T>, 'id' | 'data'> &
+  /**
+   * Additional props to pass to the component.
+   * These props are not used by Surface itself but may be used by components which resolve the surface.
+   * Exclude known prop names to prevent overriding well-defined props.
+   */
+  {
+    [K in keyof Record<string, any>]: K extends keyof CoreProps<T> | 'fallback' | 'placeholder' ? never : any;
+  };
+
+/**
+ * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
+ */
+export type CoreProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+  /**
+   * ID for debugging.
+   */
+  id: string;
+
+  /**
+   * Role defines how the data should be rendered.
+   */
+  role: string;
+
+  /**
+   * The data to be rendered by the surface.
+   * NOTE: This must be a stable value.
+   */
+  data: T;
+
+  /**
+   * If more than one component is resolved, the limit determines how many are rendered.
+   */
+  limit?: number | undefined;
+}>;
+
+// TODO(burdon): Remove ref since relying on this would be error prone.
+export type ComponentProps<T extends Record<string, any> = Record<string, any>> = CoreProps<T> & {
+  ref?: RefCallback<HTMLElement>;
+} & Record<string, any>;
+
+/**
+ * React component used to render a surface once is has matched.
+ */
+export type ComponentFunction<T extends Record<string, any> = Record<string, any>> = (
+  props: ComponentProps<T>,
+) => ReactNode;
+
+/**
+ * Definition of when a React component surface should be rendered.
+ */
+export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'react';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  component: ComponentFunction<T>;
+  filter?: (data: Record<string, unknown>) => data is T;
+}>;
+
+/**
+ * Definition of when a Web Component surface should be rendered.
+ */
+export type WebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'web-component';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  /**
+   * The tag name of the Web Component to render.
+   * The Web Component will receive the same props as React surfaces via properties/attributes.
+   */
+  tagName: string;
+  filter?: (data: Record<string, unknown>) => data is T;
+}>;
+
+/**
+ * Definition of when a surface (React or Web Component) should be rendered.
+ */
+export type Definition<T extends Record<string, any> = any> = ReactDefinition<T> | WebComponentDefinition<T>;
+
+/**
+ * Creates a React surface definition.
+ */
+export const create = <T extends Record<string, any> = any>(
+  definition: Omit<ReactDefinition<T>, 'kind'>,
+): ReactDefinition<T> => ({ ...definition, kind: 'react' });
+
+/**
+ * Creates a Web Component surface definition.
+ */
+export const createWeb = <T extends Record<string, any> = any>(
+  definition: Omit<WebComponentDefinition<T>, 'kind'>,
+): WebComponentDefinition<T> => ({ ...definition, kind: 'web-component' });

package/src/ui/components/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './App';
+export * from './PluginManager';
+export * from './Surface';

package/src/ui/hooks/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useApp';
+export * from './useCapabilities';
+export * from './useLoading';
+export * from './useSettingsState';
+export * from './useSurface';

package/src/ui/hooks/useApp.test.tsx

@@ -0,0 +1,159 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assert, describe, it } from '@effect/vitest';
+import { render, waitFor } from '@testing-library/react';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { ActivationEvents, Capabilities } from '../../common';
+import { Capability, Plugin, PluginManager } from '../../core';
+import { useApp } from './useApp';
+
+const String = Capability.make<{ string: string }>('org.dxos.test.string');
+const testMeta = { id: 'org.dxos.plugin.test', name: 'Test' };
+
+const pluginLoader = (plugins: Plugin.Plugin[]) =>
+  Effect.fn(function* (id: string) {
+    const plugin = plugins.find((plugin) => plugin.meta.id === id);
+    if (!plugin) {
+      return yield* Effect.fail(new Error(`Plugin not found: ${id}`));
+    }
+    return plugin;
+  });
+
+const TestHost = ({ manager }: { manager: PluginManager.PluginManager }) => {
+  const App = useApp({ pluginManager: manager });
+  return <App />;
+};
+
+describe('useApp cleanup integration', () => {
+  it.effect('external manager is not shut down when useApp does not own it', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      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',
+      });
+
+      const view = yield* Effect.promise(() => Promise.resolve(render(<TestHost manager={manager} />)));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* Effect.promise(() => Promise.resolve(view.unmount()));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+
+  it.effect('shutdown deactivates modules and clears bookkeeping', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      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',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+      assert.isTrue(manager.getActive().length > 0);
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+      assert.deepStrictEqual(manager.getEventsFired(), []);
+    }),
+  );
+
+  it.effect('shutdown is idempotent when called multiple times', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      yield* manager.shutdown();
+      assert.deepStrictEqual(manager.getActive(), []);
+
+      // Second shutdown should succeed without error.
+      const result = yield* manager.shutdown();
+      assert.isTrue(result);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+});