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

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

@@ -2,9 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
+import { useAtomValue } from '@effect-atom/atom-react';
 import React, {
   Fragment,
   type NamedExoticComponent,
+  Profiler,
   type RefAttributes,
   Suspense,
   forwardRef,
@@ -21,22 +23,29 @@ import { byPosition } from '@dxos/util';
 
 import { Capabilities } from '../../../common';
 import { type CapabilityManager } from '../../../core';
-import { useCapabilities } from '../../hooks';
-
+import { usePluginManager } from '../PluginManager/PluginManagerProvider';
 import { SurfaceContext } from './context';
 import { SurfaceInfo } from './SurfaceInfo';
-import { type Definition, type Props, type WebComponentDefinition } from './types';
-
-const DEFAULT_PLACEHOLDER = <Fragment />;
+import { useSurfaceProfilerCallback } from './SurfaceProfilerContext';
+import {
+  type Definition,
+  type Props,
+  type RoleToken,
+  type TokenData,
+  type TypedProps,
+  type WebComponentDefinition,
+} from './types';
 
 const DEBUG = import.meta.env.VITE_DEBUG;
 
+const DEFAULT_PLACEHOLDER = <Fragment />;
+
 /**
  * Wrapper component for rendering Web Component surfaces.
  * Handles creation, prop setting, and cleanup of Web Components.
  */
 const WebComponentWrapper = memo(
-  forwardRef<HTMLElement, Props & { definition: WebComponentDefinition }>(
+  forwardRef<HTMLElement, Omit<Props, 'role'> & { role: string; definition: WebComponentDefinition }>(
     ({ id, role, data, limit, definition, ...rest }, forwardedRef) => {
       const containerRef = useRef<HTMLDivElement>(null);
       const elementRef = useRef<HTMLElement | null>(null);
@@ -106,9 +115,11 @@ WebComponentWrapper.displayName = 'WebComponentWrapper';
  */
 // TODO(burdon): Allow DebugPlugin to provide different fallback using react-ui ErrorFallback.
 const SurfaceContextProvider = memo(
-  forwardRef<HTMLElement, Props & { definition: Definition }>(
+  forwardRef<HTMLElement, Omit<Props, 'role'> & { role: string; definition: Definition }>(
     ({ id, role, data, limit, fallback = ErrorFallback, definition, ...rest }, forwardedRef) => {
       const contextValue = useMemo(() => ({ id, role, data }), [id, role, data]);
+      const onProfilerRender = useSurfaceProfilerCallback();
+      const profilerId = `surface/${id}/${role}`;
 
       // Handle Web Component surfaces
       if (definition.kind === 'web-component') {
@@ -137,10 +148,16 @@ const SurfaceContextProvider = memo(
       if (debug) {
         return (
           <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={fallback}>
-            <div role='none' className='contents' data-id={id} data-role={role}>
+            <div className='contents' data-id={id} data-role={role}>
               <SurfaceContext.Provider value={contextValue}>
                 <SurfaceInfo ref={forwardedRef}>
-                  <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                  {onProfilerRender && !profilerId.includes('org.dxos.plugin.debug') ? (
+                    <Profiler id={profilerId} onRender={onProfilerRender}>
+                      <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                    </Profiler>
+                  ) : (
+                    <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                  )}
                 </SurfaceInfo>
               </SurfaceContext.Provider>
             </div>
@@ -150,7 +167,7 @@ const SurfaceContextProvider = memo(
 
       return (
         <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={fallback}>
-          <div role='none' className='contents' data-id={id} data-role={role}>
+          <div className='contents' data-id={id} data-role={role}>
             <SurfaceContext.Provider value={contextValue}>
               <Component id={id} role={role} data={data} limit={limit} {...rest} ref={forwardedRef} />
             </SurfaceContext.Provider>
@@ -167,43 +184,53 @@ SurfaceContextProvider.displayName = 'SurfaceContextProvider';
  * A surface is a named region of the screen that can be populated by plugins.
  */
 // TODO(burdon): Remove `ref` since relying on this would be error prone.
-export const SurfaceComponent: NamedExoticComponent<Props & RefAttributes<HTMLElement>> = memo(
-  forwardRef(({ id: _id, role, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
-    const data = useDefaultValue(dataProp, () => ({}));
-
-    // TODO(wittjosiah): This will make all surfaces depend on a single signal.
-    //   This isn't ideal because it means that any change to the data will cause all surfaces to re-render.
-    //   This effectively means that plugin modules which contribute surfaces need to all be activated at startup.
-    //   This should be fine for now because it's how it worked prior to capabilities api anyway.
-    //   In the future, it would be nice to be able to bucket the surface contributions by role.
-    const surfaces = useSurfaces();
-
-    // NOTE: Memoizing the candidates makes the surface not re-render based on reactivity within data.
-    const definitions = findCandidates(surfaces, { role, data });
-    const candidates = limit ? definitions.slice(0, limit) : definitions;
-    if (DEBUG && candidates.length === 0) {
-      log.warn('no candidates for surface', { role, data });
-      return null;
-    }
+export const SurfaceComponent = memo(
+  forwardRef<HTMLElement, Props & { type?: RoleToken<any> }>(
+    ({ id: _id, role, type, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
+      const data = useDefaultValue(dataProp, () => ({}));
+      // TODO(wittjosiah): This will make all surfaces depend on a single signal.
+      //   This isn't ideal because it means that any change to the data will cause all surfaces to re-render.
+      //   This effectively means that plugin modules which contribute surfaces need to all be activated at startup.
+      //   This should be fine for now because it's how it worked prior to capabilities api anyway.
+      //   In the future, it would be nice to be able to bucket the surface contributions by role.
+      const surfaces = useSurfaces();
+
+      const effectiveRole = role ?? type?.role;
+      if (effectiveRole == null) {
+        if (DEBUG) {
+          log.warn('Surface has neither `role` nor `type` prop', { id: _id });
+        }
+        return null;
+      }
 
-    return (
-      <Suspense fallback={placeholder}>
-        {candidates.map((definition) => (
-          <SurfaceContextProvider
-            key={definition.id}
-            id={definition.id}
-            role={role}
-            data={data}
-            limit={limit}
-            definition={definition}
-            ref={forwardedRef}
-            {...rest}
-          />
-        ))}
-      </Suspense>
-    );
-  }),
-);
+      // NOTE: Memoizing the candidates makes the surface not re-render based on reactivity within data.
+      const definitions = findCandidates(surfaces, { role: effectiveRole, data });
+      const candidates = limit ? definitions.slice(0, limit) : definitions;
+      if (DEBUG && candidates.length === 0) {
+        log.warn('no candidates for surface', { role: effectiveRole, data });
+        return null;
+      }
+
+      return (
+        <Suspense fallback={placeholder}>
+          {candidates.map((definition) => (
+            <SurfaceContextProvider
+              key={definition.id}
+              id={definition.id}
+              role={effectiveRole}
+              data={data}
+              limit={limit}
+              definition={definition}
+              ref={forwardedRef}
+              {...rest}
+            />
+          ))}
+        </Suspense>
+      );
+    },
+  ),
+) as (<TToken extends RoleToken<any>>(props: TypedProps<TToken> & RefAttributes<HTMLElement>) => React.ReactNode) &
+  NamedExoticComponent<Props & RefAttributes<HTMLElement>>;
 
 SurfaceComponent.displayName = 'Surface';
 
@@ -217,12 +244,12 @@ const ErrorFallback = ({ error }: Props) => {
   );
 };
 
-const findCandidates = (surfaces: Definition[], { role, data }: Pick<Props, 'role' | 'data'>) => {
+const findCandidates = (surfaces: Definition[], { role, data }: { role: string; data: Props['data'] }) => {
   return Object.values(surfaces)
     .filter((definition) =>
       Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
     )
-    .filter(({ filter }) => (filter ? filter(data ?? {}) : true))
+    .filter(({ filter }) => (filter ? filter(data ?? {}, role) : true))
     .toSorted(byPosition);
 };
 
@@ -230,18 +257,47 @@ const findCandidates = (surfaces: Definition[], { role, data }: Pick<Props, 'rol
  * @internal
  */
 export const useSurfaces = () => {
-  const surfaces = useCapabilities(Capabilities.ReactSurface);
-  return useMemo(() => surfaces.flat(), [surfaces]);
+  const manager = usePluginManager();
+  const surfacesByModule = useAtomValue(manager.capabilities.atomByModule(Capabilities.ReactSurface));
+  return useMemo(() => {
+    const result: Definition[] = [];
+    for (const [moduleId, surfaces] of Object.entries(surfacesByModule)) {
+      for (const def of surfaces.flat()) {
+        result.push({ ...def, id: `${moduleId}.${def.id}` });
+      }
+    }
+    return result;
+  }, [surfacesByModule]);
 };
 
 /**
  * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
+ *
+ * Two overloads:
+ * - Typed: pass a `type` role token and `data` is constrained to the token's
+ *   declared contract (e.g. `AppSurface.Section` requires `attendableId`).
+ * - Legacy: pass a string `role` and `data` is untyped.
  */
-export const isSurfaceAvailable = (
+export function isSurfaceAvailable<TToken extends RoleToken<any>>(
+  capabilityManager: CapabilityManager.CapabilityManager,
+  args: { type: TToken; data?: TokenData<TToken>; role?: never },
+): boolean;
+export function isSurfaceAvailable(
   capabilityManager: CapabilityManager.CapabilityManager,
-  { role, data }: Pick<Props, 'role' | 'data'>,
-) => {
+  args: Pick<Props, 'role' | 'data'> & { type?: undefined },
+): boolean;
+export function isSurfaceAvailable(
+  capabilityManager: CapabilityManager.CapabilityManager,
+  { role, type, data }: { role?: string; type?: RoleToken<any>; data?: unknown },
+): boolean {
+  const effectiveRole = role ?? type?.role;
+  if (effectiveRole == null) {
+    return false;
+  }
   const surfaces = capabilityManager.getAll(Capabilities.ReactSurface);
-  const candidates = findCandidates(surfaces.flat(), { role, data });
+  const candidates = findCandidates(surfaces.flat(), {
+    role: effectiveRole,
+    data: data as Props['data'],
+  });
   return candidates.length > 0;
-};
+}

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

@@ -65,7 +65,6 @@ export const SurfaceInfo = forwardRef<HTMLElement, SurfaceInfoProps>(({ children
       {rect &&
         createPortal(
           <div
-            role='none'
             className='z-[100] fixed flex flex-col-reverse scrollbar-none overflow-auto pointer-events-none'
             style={{
               top: rect.top + padding,

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/index.ts

@@ -5,7 +5,25 @@
 // TODO(wittjosiah): Cleanup to avoid re-naming.
 import { SurfaceContext } from './context';
 import { SurfaceComponent, isSurfaceAvailable } from './SurfaceComponent';
-import { type Definition as SurfaceDefinition, create as createSurface, createWeb as createWebSurface } from './types';
+import {
+  SurfaceProfilerProvider,
+  useSurfaceProfilerCallback,
+  useSurfaceProfilerClear,
+  useSurfaceProfilerEntries,
+  useSurfaceProfilerStats,
+} from './SurfaceProfilerContext';
+import {
+  type Definition as SurfaceDefinition,
+  type RoleToken as SurfaceRoleToken,
+  type SurfaceBinding as SurfaceBindingType,
+  type SurfaceFilter as SurfaceFilterType,
+  type TokenData as SurfaceTokenData,
+  type TypedProps as SurfaceTypedProps,
+  create as createSurface,
+  createWeb as createWebSurface,
+  isSurfaceFilter as isSurfaceFilterFn,
+  makeType as makeTypeFn,
+} from './types';
 
 export namespace Surface {
   export type Definition = SurfaceDefinition;
@@ -17,4 +35,20 @@ export namespace Surface {
 
   export const Surface = SurfaceComponent;
   export const isAvailable = isSurfaceAvailable;
+
+  export type RoleToken<TData> = SurfaceRoleToken<TData>;
+  export type Binding = SurfaceBindingType;
+  export type Filter<TData> = SurfaceFilterType<TData>;
+  export type TokenData<T> = SurfaceTokenData<T>;
+  export type TypedProps<TToken extends SurfaceRoleToken<any>> = SurfaceTypedProps<TToken>;
+  export const makeType = makeTypeFn;
+  export const isFilter = isSurfaceFilterFn;
+
+  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.test.ts

@@ -0,0 +1,126 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type CapabilityManager } from '../../../core';
+import { isSurfaceAvailable } from './SurfaceComponent';
+import { type RoleToken, type SurfaceFilter, create, isSurfaceFilter, makeType } from './types';
+
+describe('Surface.makeType', () => {
+  test('creates a role token carrying the role string', ({ expect }) => {
+    const token = makeType<{ subject: string }>('test-role');
+    expect(token.role).toBe('test-role');
+  });
+
+  test('tokens with the same role are independent objects (identity-by-role)', ({ expect }) => {
+    const a = makeType<{ x: number }>('shared');
+    const b = makeType<{ x: number }>('shared');
+    expect(a).not.toBe(b);
+    expect(a.role).toBe(b.role);
+  });
+});
+
+describe('isSurfaceFilter', () => {
+  test('distinguishes filter objects from predicate functions', ({ expect }) => {
+    const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: 'r', guard: () => true }] };
+    expect(isSurfaceFilter(filter)).toBe(true);
+    expect(isSurfaceFilter(() => true)).toBe(false);
+    expect(isSurfaceFilter({})).toBe(false);
+    expect(isSurfaceFilter(null)).toBe(false);
+  });
+});
+
+describe('create', () => {
+  test('accepts the legacy { role, filter } shape', ({ expect }) => {
+    const def = create({
+      id: 'legacy',
+      role: 'article',
+      filter: (data): data is { x: number } => typeof (data as any).x === 'number',
+      component: () => null,
+    });
+    expect(def.kind).toBe('react');
+    expect(def.role).toBe('article');
+    expect(def.filter!({ x: 1 })).toBe(true);
+    expect(def.filter!({})).toBe(false);
+  });
+
+  test('expands a single-binding SurfaceFilter into a role string', ({ expect }) => {
+    const filter: SurfaceFilter<Record<string, any>> = {
+      bindings: [{ role: 'article', guard: (d) => (d as any).subject === 'ok' }],
+    };
+    const def = create({ id: 'typed-single', filter, component: () => null });
+    expect(def.role).toBe('article');
+    expect(def.filter!({ subject: 'ok' }, 'article')).toBe(true);
+    expect(def.filter!({ subject: 'no' }, 'article')).toBe(false);
+  });
+
+  test('expands a multi-binding SurfaceFilter into a role array with role-scoped guards', ({ expect }) => {
+    const filter: SurfaceFilter<Record<string, any>> = {
+      bindings: [
+        { role: 'article', guard: (d) => (d as any).subject === 'a' },
+        { role: 'section', guard: (d) => (d as any).subject === 's' },
+      ],
+    };
+    const def = create({ id: 'typed-multi', filter, component: () => null });
+    expect(def.role).toEqual(['article', 'section']);
+    // Role-specific guard.
+    expect(def.filter!({ subject: 'a' }, 'article')).toBe(true);
+    expect(def.filter!({ subject: 'a' }, 'section')).toBe(false);
+    expect(def.filter!({ subject: 's' }, 'section')).toBe(true);
+    expect(def.filter!({ subject: 's' }, 'article')).toBe(false);
+    // Without role, any binding may match.
+    expect(def.filter!({ subject: 'a' })).toBe(true);
+    expect(def.filter!({ subject: 'unknown' })).toBe(false);
+  });
+
+  test('passes position through untouched', ({ expect }) => {
+    const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: 'r', guard: () => true }] };
+    const def = create({ id: 'pos', filter, component: () => null, position: 'last' });
+    expect(def.position).toBe('last');
+  });
+});
+
+describe('role token typing', () => {
+  test('makeType preserves TData through token use-sites', ({ expect }) => {
+    // Type-level smoke test: if TS compiles, we're fine. The `RoleToken<T>`
+    // phantom should not impose a runtime constraint.
+    const token: RoleToken<{ subject: number }> = makeType('numeric');
+    expect(token.role).toBe('numeric');
+  });
+});
+
+describe('isSurfaceAvailable typing', () => {
+  // These tests double as static assertions: the `@ts-expect-error` comments
+  // fail to compile if the surrounding expression typechecks, so they verify
+  // the typed overload narrows `data` to the token's declared contract.
+  const sectionToken = makeType<{ attendableId: string; subject: string }>('section');
+  const capabilityManager = { getAll: () => [] } as unknown as CapabilityManager.CapabilityManager;
+
+  test('typed overload accepts data matching the token contract', () => {
+    // No error — data has all required fields.
+    isSurfaceAvailable(capabilityManager, {
+      type: sectionToken,
+      data: { attendableId: 'id', subject: 'x' },
+    });
+  });
+
+  test('typed overload rejects data missing required fields', () => {
+    // @ts-expect-error — `data` is missing `attendableId` required by the token.
+    isSurfaceAvailable(capabilityManager, { type: sectionToken, data: { subject: 'x' } });
+  });
+
+  test('typed overload rejects data with wrong field type', () => {
+    // @ts-expect-error — `attendableId` must be a string, not a number.
+    isSurfaceAvailable(capabilityManager, { type: sectionToken, data: { attendableId: 123, subject: 'x' } });
+  });
+
+  test('legacy overload accepts loose data when `role` is a string', () => {
+    // No error — legacy overload's `data` is untyped (`Record<string, unknown>`).
+    isSurfaceAvailable(capabilityManager, {
+      role: 'article',
+      data: { anything: 'goes' },
+    });
+  });
+});