@dxos/app-framework 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

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

@@ -6,8 +6,63 @@ import type { FC, PropsWithChildren, ReactNode, RefCallback } from 'react';
 
 import type { MakeOptional, Position } from '@dxos/util';
 
+/**
+ * A typed role token. Carries a role string for runtime dispatch plus a phantom
+ * data type so consumers using `type={SomeToken}` and providers using
+ * `AppSurface.object(SomeToken, ...)` share a single type-level contract.
+ *
+ * Mint via {@link makeType}.
+ */
+export type RoleToken<TData> = {
+  readonly role: string;
+  /** Covariant phantom; never accessed at runtime. */
+  readonly _phantom?: TData;
+};
+
+/**
+ * One entry in a {@link SurfaceFilter} — a role plus the guard that validates
+ * the data shape when the Surface dispatcher is matching that role.
+ */
+export type SurfaceBinding = {
+  readonly role: string;
+  readonly guard: (data: unknown) => boolean;
+};
+
+/**
+ * Typed filter binding for {@link create}. Combines one or more `(role, guard)`
+ * pairs so a provider can register against multiple roles while keeping the
+ * role and its data shape in a single expression.
+ */
+export type SurfaceFilter<TData> = {
+  readonly bindings: ReadonlyArray<SurfaceBinding>;
+  /** Covariant phantom; never accessed at runtime. */
+  readonly _phantom?: TData;
+};
+
+/**
+ * Narrow data type carried by a role token.
+ */
+export type TokenData<T> = T extends RoleToken<infer D> ? D : never;
+
+/**
+ * Runtime guard for {@link SurfaceFilter}. Distinguishes new-style filter
+ * bindings from legacy predicate filters.
+ */
+export const isSurfaceFilter = (value: unknown): value is SurfaceFilter<any> =>
+  typeof value === 'object' && value !== null && Array.isArray((value as { bindings?: unknown }).bindings);
+
+/**
+ * Mints a typed role token. Identity is structural; all tokens with the same
+ * `role` string are interchangeable at runtime.
+ */
+export const makeType = <TData>(role: string): RoleToken<TData> => ({ role });
+
 /**
  * Props that are passed to the Surface component.
+ *
+ * The role can be provided either as a string via `role` or as a typed
+ * {@link RoleToken} via `type`. The typed form narrows `data` to the token's
+ * declared shape.
  */
 export type Props<T extends Record<string, any> = Record<string, unknown>> = {
   /**
@@ -21,16 +76,46 @@ export type Props<T extends Record<string, any> = Record<string, unknown>> = {
    * The placeholder component will be rendered while the surface component is loading.
    */
   placeholder?: ReactNode;
-} & MakeOptional<CoreProps<T>, 'id' | 'data'> &
-  /**
+} & MakeOptional<CoreProps<T>, 'id' | 'data' | 'role'> & {
+    /**
+     * Explicitly disallow `type` on the untyped Props overload — if the caller
+     * provides `type={AppSurface.X}`, TypeScript must route to the typed
+     * overload (where `data` is narrowed by the token). Without this, the
+     * catch-all index signature below would accept any `type` value and mask
+     * the typed overload entirely.
+     */
+    type?: undefined;
+  } /**
    * 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;
+   */ & {
+    [K in keyof Record<string, any>]: K extends keyof CoreProps<T> | 'fallback' | 'placeholder' | 'type' ? never : any;
   };
 
+/**
+ * Typed Surface consumer props — carries the role/data-shape contract via a
+ * {@link RoleToken}. Available as a typed overload of the Surface component so
+ * ad-hoc `type` fields on arbitrary spread props don't conflict with the
+ * untyped consumer form.
+ */
+export type TypedProps<TToken extends RoleToken<any>> = {
+  fallback?: FC<{ error: Error; data?: any }>;
+  placeholder?: ReactNode;
+  id?: string;
+  type: TToken;
+  data?: TokenData<TToken>;
+  limit?: number | undefined;
+} & {
+  /**
+   * Additional pass-through props. Known prop names are excluded so the
+   * catch-all doesn't widen `data` / `type` / etc. to `any` at the intersection.
+   */
+  [K in keyof Record<string, any>]: K extends 'fallback' | 'placeholder' | 'id' | 'type' | 'data' | 'limit'
+    ? never
+    : any;
+};
+
 /**
  * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
  */
@@ -41,7 +126,10 @@ export type CoreProps<T extends Record<string, any> = Record<string, unknown>> =
   id: string;
 
   /**
-   * Role defines how the data should be rendered.
+   * Role defines how the data should be rendered. For new code, prefer the
+   * typed overload of the Surface component which takes a {@link RoleToken}
+   * via the `type` prop instead — it enforces a role/data contract at compile
+   * time.
    */
   role: string;
 
@@ -71,6 +159,10 @@ export type ComponentFunction<T extends Record<string, any> = Record<string, any
 
 /**
  * Definition of when a React component surface should be rendered.
+ *
+ * The optional `filter` receives the consumer-supplied `role` as its second
+ * argument so a single definition can encode role-specific guards (used by the
+ * {@link SurfaceFilter}-based `create` overload).
  */
 export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'react';
@@ -78,7 +170,7 @@ export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
   role: string | string[];
   position?: Position;
   component: ComponentFunction<T>;
-  filter?: (data: Record<string, unknown>) => data is T;
+  filter?: (data: Record<string, unknown>, role?: string) => data is T;
 }>;
 
 /**
@@ -94,7 +186,7 @@ export type WebComponentDefinition<T extends Record<string, any> = any> = Readon
    * The Web Component will receive the same props as React surfaces via properties/attributes.
    */
   tagName: string;
-  filter?: (data: Record<string, unknown>) => data is T;
+  filter?: (data: Record<string, unknown>, role?: string) => data is T;
 }>;
 
 /**
@@ -102,16 +194,76 @@ export type WebComponentDefinition<T extends Record<string, any> = any> = Readon
  */
 export type Definition<T extends Record<string, any> = any> = ReactDefinition<T> | WebComponentDefinition<T>;
 
+/**
+ * Typed React surface definition — role is derived from the filter's bindings.
+ */
+export type TypedReactDefinition<T extends Record<string, any> = any> = Readonly<{
+  id: string;
+  filter: SurfaceFilter<T>;
+  component: ComponentFunction<T>;
+  position?: Position;
+}>;
+
+/**
+ * Typed Web Component surface definition.
+ */
+export type TypedWebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
+  id: string;
+  filter: SurfaceFilter<T>;
+  tagName: string;
+  position?: Position;
+}>;
+
+const expandBindings = <T extends Record<string, any>>(
+  filter: SurfaceFilter<T>,
+): { role: string | string[]; guard: (data: Record<string, unknown>, role?: string) => data is T } => {
+  const bindings = filter.bindings;
+  const roles = Array.from(new Set(bindings.map((binding) => binding.role)));
+  const guard = (data: Record<string, unknown>, role?: string): data is T => {
+    if (role != null) {
+      // Multiple bindings may share a role (e.g. via `oneOf` of same-role filters);
+      // the role matches if ANY of them passes.
+      return bindings.some((entry) => entry.role === role && entry.guard(data));
+    }
+    return bindings.some((entry) => entry.guard(data));
+  };
+  return { role: roles.length === 1 ? roles[0] : roles, guard };
+};
+
 /**
  * Creates a React surface definition.
  */
-export const create = <T extends Record<string, any> = any>(
+export function create<T extends Record<string, any> = any>(definition: TypedReactDefinition<T>): ReactDefinition<T>;
+export function create<T extends Record<string, any> = any>(
   definition: Omit<ReactDefinition<T>, 'kind'>,
-): ReactDefinition<T> => ({ ...definition, kind: 'react' });
+): ReactDefinition<T>;
+export function create<T extends Record<string, any> = any>(
+  definition: TypedReactDefinition<T> | Omit<ReactDefinition<T>, 'kind'>,
+): ReactDefinition<T> {
+  if (isSurfaceFilter(definition.filter)) {
+    const { id, filter, component, position } = definition as TypedReactDefinition<T>;
+    const { role, guard } = expandBindings(filter);
+    return { kind: 'react', id, role, position, component, filter: guard };
+  }
+  return { ...(definition as Omit<ReactDefinition<T>, 'kind'>), kind: 'react' };
+}
 
 /**
  * Creates a Web Component surface definition.
  */
-export const createWeb = <T extends Record<string, any> = any>(
+export function createWeb<T extends Record<string, any> = any>(
+  definition: TypedWebComponentDefinition<T>,
+): WebComponentDefinition<T>;
+export function createWeb<T extends Record<string, any> = any>(
   definition: Omit<WebComponentDefinition<T>, 'kind'>,
-): WebComponentDefinition<T> => ({ ...definition, kind: 'web-component' });
+): WebComponentDefinition<T>;
+export function createWeb<T extends Record<string, any> = any>(
+  definition: TypedWebComponentDefinition<T> | Omit<WebComponentDefinition<T>, 'kind'>,
+): WebComponentDefinition<T> {
+  if (isSurfaceFilter(definition.filter)) {
+    const { id, filter, tagName, position } = definition as TypedWebComponentDefinition<T>;
+    const { role, guard } = expandBindings(filter);
+    return { kind: 'web-component', id, role, position, tagName, filter: guard };
+  }
+  return { ...(definition as Omit<WebComponentDefinition<T>, 'kind'>), kind: 'web-component' };
+}

package/src/ui/components/index.ts

@@ -3,5 +3,6 @@
 //
 
 export * from './App';
+export * from './Placeholder';
 export * from './PluginManager';
 export * from './Surface';

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

@@ -20,7 +20,7 @@ const pluginLoader = (plugins: Plugin.Plugin[]) =>
     if (!plugin) {
       return yield* Effect.fail(new Error(`Plugin not found: ${id}`));
     }
-    return plugin;
+    return { plugin };
   });
 
 const TestHost = ({ manager }: { manager: PluginManager.PluginManager }) => {

package/src/ui/hooks/useApp.tsx

@@ -30,8 +30,33 @@ export type StartupProgress = {
   total: number;
   /** Fractional progress (0-1). */
   progress: number;
-  /** Human-readable label for the currently activating module. */
-  status?: string;
+  /**
+   * Raw activation event key (e.g. `org.dxos.app-framework.event.startup`).
+   * Set on event-level transitions, *and* on module-level transitions where
+   * it carries the parent activation event that first triggered the
+   * module's load (plumbed through `_loadCapabilitiesForModules` →
+   * `_loadModule`). Consumers can use this either as the primary id (when
+   * {@link module} is absent) or as an extra "context" field alongside
+   * {@link module}.
+   */
+  event?: string;
+  /**
+   * Raw module id (e.g. `org.dxos.plugin.observability.module.ReactSurface`)
+   * when the in-flight activation is module-level. When present,
+   * {@link event} may also be set, identifying the parent activation that
+   * triggered this module's load.
+   */
+  module?: string;
+  /**
+   * Pre-humanized label for the currently surfaced transition (module
+   * label if {@link module} is set, otherwise the event label), supplied
+   * for consumers that want a sensible default. Hosts that prefer to
+   * render their own label can read the raw {@link event}/{@link module}
+   * fields and ignore this — the framework leaves the policy choice
+   * (which transitions to surface, how to format them, whether to drop
+   * sub-modules entirely) to the host's `Placeholder`.
+   */
+  humanizedName?: string;
 };
 
 export type PlaceholderProps = {
@@ -42,6 +67,8 @@ export type PlaceholderProps = {
 export type UseAppOptions = {
   pluginManager?: PluginManager.PluginManager;
   pluginLoader?: PluginManager.ManagerOptions['pluginLoader'];
+  onPluginRemove?: PluginManager.ManagerOptions['onRemove'];
+  pluginRegistryProvider?: PluginManager.ManagerOptions['pluginRegistryProvider'];
   plugins?: Plugin.Plugin[];
   core?: string[];
   defaults?: string[];
@@ -86,6 +113,8 @@ export type UseAppOptions = {
 export const useApp = ({
   pluginManager,
   pluginLoader: pluginLoaderProp,
+  onPluginRemove,
+  pluginRegistryProvider,
   plugins: pluginsProp,
   core: coreProp,
   defaults: defaultsProp,
@@ -109,7 +138,7 @@ export const useApp = ({
         Effect.sync(() => {
           const plugin = plugins.find((plugin) => plugin.meta.id === id);
           invariant(plugin, `Plugin not found: ${id}`);
-          return plugin;
+          return { plugin };
         })),
     [pluginLoaderProp, plugins],
   );
@@ -131,10 +160,19 @@ export const useApp = ({
   );
   const isExternalManager = !!pluginManager;
   const manager = useMemo(() => {
-    const mgr = pluginManager ?? PluginManager.make({ pluginLoader, plugins, core, enabled });
+    const mgr =
+      pluginManager ??
+      PluginManager.make({
+        pluginLoader,
+        plugins,
+        core,
+        enabled,
+        onRemove: onPluginRemove,
+        pluginRegistryProvider,
+      });
     log('useApp: useMemo created/reused manager', { provided: !!pluginManager });
     return mgr;
-  }, [pluginManager, pluginLoader, plugins, core, enabled]);
+  }, [pluginManager, pluginLoader, plugins, core, enabled, onPluginRemove, pluginRegistryProvider]);
 
   useEffect(() => {
     if (!cacheEnabled) {
@@ -164,38 +202,89 @@ export const useApp = ({
       module: 'org.dxos.app-framework.atom-registry',
     });
 
-    // Poll manager atoms for progress (avoids PubSub subscription race).
-    const progressInterval = setInterval(() => {
-      if (readyRef.current) {
-        clearInterval(progressInterval);
-        return;
-      }
-      const active = manager.getActive();
-      const modules = manager.getModules();
-      const total = modules.length;
-      const activated = active.length;
-      const lastModule = active.length > 0 ? active[active.length - 1] : undefined;
-      setStartupProgress({
-        activated,
-        total,
-        progress: total > 0 ? activated / total : 0,
-        status: lastModule ? humanizeModuleId(lastModule) : undefined,
-      });
-    }, 100);
-
     const fiber = Effect.gen(function* () {
       const queue = yield* PubSub.subscribe(manager.activation);
       const listener = yield* Effect.forkDaemon(
         Queue.take(queue).pipe(
-          Effect.tap(({ event, state, error: error$ }) =>
+          Effect.tap(({ event, state, module, error: error$ }) =>
             Effect.sync(() => {
-              if (event === ActivationEvents.Startup.id && state === 'activated') {
+              // Event-level Startup activated (no `module` field) fires once,
+              // after every module triggered by Startup has finished. Module
+              // activations now also carry their parent event id (so the trace
+              // can attribute a module to its triggering event), which means
+              // each module activated under Startup publishes
+              // `{ event: 'startup', state: 'activated', module: <id> }`. Without
+              // the `!module` guard the listener would mark the app ready on
+              // the *first* such module rather than waiting for the event-level
+              // completion — leaving downstream capabilities (operation-invoker,
+              // app-graph, …) un-registered when the placeholder dismisses.
+              if (event === ActivationEvents.Startup.id && state === 'activated' && !module) {
                 clearTimeout(timeoutId);
-                clearInterval(progressInterval);
                 setReady(true);
                 readyRef.current = true;
                 // Trigger startup profiler dump if available.
                 (globalThis as any).composer?.profiler?.dump();
+                // Notify any host observability layer that startup completed.
+                // A `CustomEvent` keeps this generic — app-framework doesn't
+                // import a provider, and consumers can capture the startup
+                // summary without us picking one.
+                if (typeof window !== 'undefined') {
+                  window.dispatchEvent(new CustomEvent('app-framework:startup-activated'));
+                }
+                return;
+              }
+              // `activating` is the start-of-load signal. Surface the raw
+              // `module` (or `event`) plus a pre-humanized label so the
+              // host placeholder can decide what to render — show
+              // everything, suppress noisy sub-modules, group by plugin,
+              // or apply its own formatting. We intentionally do NOT touch
+              // these fields on `activated`: pairing the two would cause
+              // back-to-back identical updates to the host's effect, which
+              // the boot loader treats as a re-trigger because
+              // `progress.progress` moved. Leaving the label alone on
+              // completion keeps it accurate ("now activating X") until
+              // the next module starts.
+              if (module && state === 'activating' && !readyRef.current) {
+                setStartupProgress((current) => ({
+                  ...current,
+                  // `event` here is the activation event that first
+                  // triggered this module load (plumbed through
+                  // `_loadCapabilitiesForModules` → `_loadModule`).
+                  // Falsy/empty falls back to undefined so consumers can
+                  // tell "no parent context" from "parent context: <X>".
+                  event: event || undefined,
+                  module,
+                  humanizedName: humanizeModuleId(module),
+                }));
+              }
+              // Update the activation count when a module commits. The
+              // ring's fraction comes from this; `event`/`module`/
+              // `humanizedName` were set by the matching `activating`
+              // message above and are left alone so the count can advance
+              // without re-firing the host's status callback.
+              if (module && state === 'activated' && !readyRef.current) {
+                const active = manager.getActive();
+                const total = manager.getModules().length;
+                setStartupProgress((current) => ({
+                  ...current,
+                  activated: active.length,
+                  total,
+                  progress: total > 0 ? active.length / total : 0,
+                }));
+              }
+              // Event-level `activating` (no `module`) — fired at the start
+              // of `_activateModulesForEvent` and recursively for each
+              // before/after event. Surfaces a label during the gap before
+              // the first module-level message lands; subsequent module
+              // updates immediately overwrite this with a more specific
+              // label.
+              if (event && !module && state === 'activating' && !readyRef.current) {
+                setStartupProgress((current) => ({
+                  ...current,
+                  event,
+                  module: undefined,
+                  humanizedName: humanizeEventKey(event),
+                }));
               }
               if (error$ && !readyRef.current) {
                 setError(error$);
@@ -232,7 +321,6 @@ export const useApp = ({
     return () => {
       log('useApp: effect cleanup');
       clearTimeout(timeoutId);
-      clearInterval(progressInterval);
       void runAndForwardErrors(Fiber.interrupt(fiber));
       if (!isExternalManager) {
         void runAndForwardErrors(manager.shutdown());
@@ -240,6 +328,9 @@ export const useApp = ({
     };
   }, [manager]);
 
+  const progressRef = useRef(startupProgress);
+  progressRef.current = startupProgress;
+
   return useCallback(
     () => (
       <ErrorBoundary name='app' FallbackComponent={fallback}>
@@ -251,7 +342,7 @@ export const useApp = ({
                 ready={ready}
                 error={error}
                 debounce={debounce}
-                progress={startupProgress}
+                progress={progressRef.current}
               />
             </RegistryContext.Provider>
           </ContextProtocolProvider>
@@ -269,21 +360,65 @@ const setupDevtools = (manager: PluginManager.PluginManager) => {
 
 /**
  * Extracts a human-readable label from a module ID.
- * E.g., "org.dxos.plugin.markdown.module.ReactSurface" → "Markdown".
+ *
+ * Module IDs follow `org.dxos.plugin.<plugin-slug>.module.<module-name>`,
+ * where `<plugin-slug>` is kebab-case and `<module-name>` is either an
+ * explicit string (often kebab-case, e.g. `'observability'`, `'namespace'`)
+ * or a capability tag in PascalCase from `Capability.getModuleTag(...)`
+ * (e.g. `'ReactSurface'`, `'AppGraphBuilder'`). The output is
+ * `"Title Case Plugin: kebab-module"` so the visible status names both the
+ * plugin and the aspect being activated, helping disambiguate the multiple
+ * modules a plugin contributes.
+ *
+ * Examples:
+ *   - "org.dxos.plugin.markdown.module.ReactSurface" → "Markdown: react-surface"
+ *   - "org.dxos.plugin.observability.module.AppGraphBuilder" → "Observability: app-graph-builder"
+ *   - "org.dxos.plugin.observability.module.observability" → "Observability"
+ *     (the module name matches the plugin slug — collapsed to avoid
+ *     "Observability: observability" noise.)
  */
 const humanizeModuleId = (moduleId: string): string => {
-  // Extract plugin name from pattern: org.dxos.plugin.<name>.module.<capability>
-  const pluginMatch = moduleId.match(/\.plugin\.([^.]+)\./);
-  if (pluginMatch) {
-    const name = pluginMatch[1];
-    // Convert kebab-case to title case.
-    return name
-      .split('-')
-      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-      .join(' ');
+  const match = moduleId.match(/\.plugin\.([^.]+)\.module\.(.+)$/);
+  if (!match) {
+    // Fallback: use the last segment.
+    const parts = moduleId.split('.');
+    return parts[parts.length - 1];
+  }
+  const [, pluginSlug, moduleName] = match;
+  const pluginLabel = pluginSlug
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+  // Normalise the module name to kebab-case so PascalCase capability tags
+  // ("ReactSurface") read consistently with explicit kebab IDs
+  // ("operation-handler"). The two-step substitution handles consecutive
+  // uppercase runs (`URLLoader` → `url-loader`) without splitting them
+  // mid-acronym.
+  const moduleLabel = moduleName
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase();
+  // Capability modules whose name matches the plugin slug (e.g. the
+  // observability plugin's `observability` capability module) would render
+  // as "Observability: observability" — drop the redundant suffix.
+  if (moduleLabel === pluginSlug) {
+    return pluginLabel;
   }
+  return `${pluginLabel}: ${moduleLabel}`;
+};
 
-  // Fallback: use the last segment.
-  const parts = moduleId.split('.');
-  return parts[parts.length - 1];
+/**
+ * Extracts a human-readable label from an activation event key.
+ * E.g., "org.dxos.app-framework.event.setup-react-surface" → "Setup React Surface".
+ */
+const humanizeEventKey = (eventKey: string): string => {
+  // Strip a leading specifier (composite key form: "<id>:<specifier>").
+  const id = eventKey.split(':')[0];
+  // Match the trailing segment after `.event.`.
+  const match = id.match(/\.event\.(.+)$/);
+  const slug = match ? match[1] : (id.split('.').pop() ?? id);
+  return slug
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
 };

package/src/ui/hooks/useLoading.tsx

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 export enum LoadingState {
   Loading = 0,
@@ -23,6 +23,14 @@ export enum LoadingState {
  */
 export const useLoading = (ready: boolean, debounce = 0) => {
   const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
+  // Mirror `ready` into a ref so the interval's `setStage` callback can read
+  // the latest value without depending on the effect re-running. The pure
+  // closure-capture pattern (with `ready` in deps) sticks the FSM at
+  // `FadeIn` whenever HMR doesn't propagate the dep change end-to-end —
+  // a ref sidesteps that entirely and fires the read on every tick.
+  const readyRef = useRef(ready);
+  readyRef.current = ready;
+
   useEffect(() => {
     if (!debounce) {
       return;
@@ -30,18 +38,18 @@ export const useLoading = (ready: boolean, debounce = 0) => {
 
     const i = setInterval(() => {
       setStage((stage) => {
+        const isReady = readyRef.current;
         switch (stage) {
           case LoadingState.Loading: {
-            if (!ready) {
+            if (!isReady) {
               return LoadingState.FadeIn;
-            } else {
-              clearInterval(i);
-              return LoadingState.Done;
             }
+            clearInterval(i);
+            return LoadingState.Done;
           }
 
           case LoadingState.FadeIn: {
-            if (ready) {
+            if (isReady) {
               return LoadingState.FadeOut;
             }
             break;