@dxos/app-framework 0.10.0 → 0.11.1

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

@@ -0,0 +1,202 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Per-surface dev metrics, complementing the render-timing data collected by the
+ * React Profiler ({@link SurfaceProfilerStats}). Captures dispatch-level signals
+ * the Profiler cannot see: how many candidates matched, whether the consumer's
+ * `data` prop is referentially unstable (the most common Surface footgun), error
+ * boundary trips, and mount churn.
+ *
+ * Keyed by the same `surface/<id>/<role>` identifier the Profiler uses, so the
+ * two can be joined in the devtools panel.
+ */
+export type SurfaceMetric = {
+  /** `surface/<id>/<role>`. */
+  id: string;
+  /** Surface definition id. */
+  surfaceId: string;
+  /** Resolved role NSID. */
+  role: string;
+  /** Number of times the dispatcher resolved candidates for this surface. */
+  dispatches: number;
+  /** Candidates matched on the last dispatch. */
+  candidates: number;
+  /** `true` when more candidates matched than `limit` rendered. */
+  truncated: boolean;
+  /** `true` when the `data` prop identity churns across renders without changing value. */
+  dataUnstable: boolean;
+  /** Consecutive renders where `data` identity changed but value did not. */
+  dataChurn: number;
+  /** Error boundary trips. */
+  errors: number;
+  /** Mounts of the matched component. */
+  mounts: number;
+  /** Unmounts of the matched component. */
+  unmounts: number;
+};
+
+/** Consecutive unstable renders before `dataUnstable` is flagged. */
+const UNSTABLE_THRESHOLD = 3;
+
+export const surfaceMetricKey = (surfaceId: string, role: string): string => `surface/${surfaceId}/${role}`;
+
+/**
+ * Shallow (top-level) value equality. Used to distinguish a genuinely new `data`
+ * value from a new object/array carrying the same content (the unstable-prop case).
+ */
+const shallowEqual = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) {
+    return true;
+  }
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+    return false;
+  }
+  const aKeys = Object.keys(a as Record<string, unknown>);
+  const bKeys = Object.keys(b as Record<string, unknown>);
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  return aKeys.every((key) => Object.is((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]));
+};
+
+/**
+ * Singleton store of surface dev metrics. A module singleton (rather than a React
+ * context) so the debug overlay — which renders in its own root outside the app's
+ * provider tree — can read the same data as the in-app devtools panel.
+ */
+class SurfaceMetricsStore {
+  #metrics = new Map<string, SurfaceMetric>();
+  #snapshot: SurfaceMetric[] = [];
+  #listeners = new Set<() => void>();
+  #pendingNotify = false;
+
+  #entry(surfaceId: string, role: string): SurfaceMetric {
+    const id = surfaceMetricKey(surfaceId, role);
+    let metric = this.#metrics.get(id);
+    if (!metric) {
+      metric = {
+        id,
+        surfaceId,
+        role,
+        dispatches: 0,
+        candidates: 0,
+        truncated: false,
+        dataUnstable: false,
+        dataChurn: 0,
+        errors: 0,
+        mounts: 0,
+        unmounts: 0,
+      };
+      this.#metrics.set(id, metric);
+    }
+    return metric;
+  }
+
+  /**
+   * Records a dispatch. `previousData` is the consumer's prior `data` reference;
+   * the store derives churn/instability from the identity-vs-value comparison.
+   */
+  recordDispatch(
+    surfaceId: string,
+    role: string,
+    args: { candidates: number; truncated: boolean; dataChurn: number },
+  ): void {
+    const metric = this.#entry(surfaceId, role);
+    metric.dispatches += 1;
+    metric.candidates = args.candidates;
+    metric.truncated = args.truncated;
+    metric.dataChurn = args.dataChurn;
+    metric.dataUnstable = args.dataChurn >= UNSTABLE_THRESHOLD;
+    this.#schedule();
+  }
+
+  recordError(surfaceId: string, role: string): void {
+    this.#entry(surfaceId, role).errors += 1;
+    this.#schedule();
+  }
+
+  recordMount(surfaceId: string, role: string): void {
+    this.#entry(surfaceId, role).mounts += 1;
+    this.#schedule();
+  }
+
+  recordUnmount(surfaceId: string, role: string): void {
+    this.#entry(surfaceId, role).unmounts += 1;
+    this.#schedule();
+  }
+
+  clear(): void {
+    this.#metrics.clear();
+    this.#snapshot = [];
+    this.#notify();
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  };
+
+  getSnapshot = (): SurfaceMetric[] => this.#snapshot;
+
+  /** Defers notification to the next frame to coalesce bursts of records. */
+  #schedule(): void {
+    if (this.#pendingNotify || typeof requestAnimationFrame === 'undefined') {
+      if (typeof requestAnimationFrame === 'undefined') {
+        this.#notify();
+      }
+      return;
+    }
+    this.#pendingNotify = true;
+    requestAnimationFrame(() => {
+      this.#pendingNotify = false;
+      this.#notify();
+    });
+  }
+
+  #notify(): void {
+    this.#snapshot = [...this.#metrics.values()];
+    for (const listener of this.#listeners) {
+      listener();
+    }
+  }
+}
+
+export const surfaceMetrics = new SurfaceMetricsStore();
+
+/**
+ * Updates the running churn count for a consumer's `data` prop.
+ *
+ * @returns the new churn count (0 when `data` changed value or is unchanged).
+ */
+export const nextDataChurn = (previous: unknown, next: unknown, churn: number): number => {
+  // Unchanged reference: preserve churn. NOTE: do NOT reset to 0 here — `useDefaultValue`
+  // (used for the `data` default) lags one render, so each prop change yields two renders
+  // (stale-then-new); resetting on the stale (Object.is) render would wipe accumulated churn
+  // and never flag genuinely unstable data. The flag clears on the next genuine value change.
+  if (Object.is(previous, next)) {
+    return churn;
+  }
+  // New reference: churn only when the value is structurally the same (unstable identity).
+  return shallowEqual(previous, next) ? churn + 1 : 0;
+};
+
+/**
+ * Subscribes to surface dev metrics, sorted with the most concerning first
+ * (unstable data, then errors, then dispatch count).
+ */
+export const useSurfaceMetrics = (): SurfaceMetric[] => {
+  const metrics = useSyncExternalStore(
+    surfaceMetrics.subscribe,
+    surfaceMetrics.getSnapshot,
+    surfaceMetrics.getSnapshot,
+  );
+  return [...metrics].sort(
+    (a, b) => Number(b.dataUnstable) - Number(a.dataUnstable) || b.errors - a.errors || b.dispatches - a.dispatches,
+  );
+};

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

@@ -52,13 +52,22 @@ class SurfaceProfilerStore {
   private _snapshot: readonly SurfaceProfilerEntry[] = [];
   private _pendingNotify = false;
 
-  /** Records an entry and schedules a deferred notification to avoid re-render loops. */
+  /**
+   * Records an entry and schedules a deferred notification to avoid re-render loops.
+   * `_snapshot` is rebuilt only when the deferred notification actually fires
+   * ({@link _notifySync}) — not here — so `getSnapshot` stays referentially stable for any
+   * synchronous re-invocation React makes within the same commit (e.g. the tearing check a
+   * profiled subscriber's own `useSyncExternalStore` runs right after this Profiler's
+   * `onRender` callback). Rebuilding it synchronously here would change what `getSnapshot`
+   * returns before listeners are told, which React reads as a torn store and forces an
+   * immediate re-render — and if the re-rendering component is itself profiled, that
+   * re-render re-triggers `record`, looping forever.
+   */
   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();
   }
 
@@ -94,6 +103,7 @@ class SurfaceProfilerStore {
   }
 
   private _notifySync() {
+    this._snapshot = [...this._entries];
     for (const listener of this._listeners) {
       listener();
     }

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

@@ -2,11 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { DXN } from '@dxos/keys';
-
-// TODO(wittjosiah): Cleanup to avoid re-naming.
+import { Role } from '../../../common';
 import { SurfaceContext } from './context';
-import { SurfaceComponent, isSurfaceAvailable } from './SurfaceComponent';
+import { SurfaceComponent, useIsSurfaceAvailable } from './SurfaceComponent';
+import { isSurfaceDebugEnabled, setSurfaceDebug } from './SurfaceDebug';
+import { type SurfaceMetric, surfaceMetrics, useSurfaceMetrics } from './SurfaceMetrics';
 import {
   SurfaceProfilerProvider,
   useSurfaceProfilerCallback,
@@ -15,17 +15,15 @@ import {
   useSurfaceProfilerStats,
 } from './SurfaceProfilerContext';
 import {
-  type SurfaceBinding as SurfaceBindingType,
+  type Binding as SurfaceBindingType,
+  type ComponentProps as SurfaceComponentPropsType,
   type Definition as SurfaceDefinition,
-  type SurfaceFilter as SurfaceFilterType,
-  type RoleToken as SurfaceRoleToken,
-  type TokenData as SurfaceTokenData,
+  type Filter as SurfaceFilterType,
   type TypedProps as SurfaceTypedProps,
   create as createSurface,
   createWeb as createWebSurface,
-  isSurfaceFilter as isSurfaceFilterFn,
+  isFilter as isFilterFn,
   makeFilter as makeFilterFn,
-  makeType as makeTypeFn,
 } from './types';
 
 export namespace Surface {
@@ -37,29 +35,33 @@ export namespace Surface {
   export const Context = SurfaceContext;
 
   export const Surface = SurfaceComponent;
-  export const isAvailable = isSurfaceAvailable;
+  export const useIsAvailable = useIsSurfaceAvailable;
 
-  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 makeFilter = makeFilterFn;
+  export const isFilter = isFilterFn;
 
-  /** Mints a typed role token. The NSID is validated at compile time via {@link DXN.Name}. */
-  export const makeType: {
-    <TData = unknown, T extends string = string>(
-      nsid: [DXN.Name<T>] extends [never] ? `Invalid NSID "${T}": final segment must be camelCase (no hyphens)` : T,
-    ): SurfaceRoleToken<TData>;
-  } = makeTypeFn;
+  export type TypedProps<TToken extends Role.Role<any>> = SurfaceTypedProps<TToken>;
 
-  export const makeFilter = makeFilterFn;
-  export const isFilter = isSurfaceFilterFn;
+  /** Props a matched surface component receives, and the input to a definition's `props` mapper. */
+  export type ComponentProps<T extends Record<string, any> = Record<string, any>> = SurfaceComponentPropsType<T>;
+
+  export const isDebugEnabled = isSurfaceDebugEnabled;
+  export const setDebug = setSurfaceDebug;
 
   export const ProfilerProvider = SurfaceProfilerProvider;
   export const useProfilerCallback = useSurfaceProfilerCallback;
   export const useProfilerEntries = useSurfaceProfilerEntries;
   export const useProfilerStats = useSurfaceProfilerStats;
   export const useProfilerClear = useSurfaceProfilerClear;
+
+  export type Metric = SurfaceMetric;
+  export const useMetrics = useSurfaceMetrics;
+  export const clearMetrics = () => surfaceMetrics.clear();
 }
 
 export type { SurfaceProfilerEntry, SurfaceProfilerStats } from './SurfaceProfilerContext';
+export type { SurfaceMetric } from './SurfaceMetrics';
+export { SurfaceManager } from './SurfaceManager';
+export { SurfaceManagerProvider, useSurfaceManager } from './SurfaceManagerContext';

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

@@ -6,47 +6,26 @@ import { describe, test } from 'vitest';
 
 import { Position } from '@dxos/util';
 
-import { type CapabilityManager } from '../../../core';
-import { isSurfaceAvailable } from './SurfaceComponent';
-import { type RoleToken, type SurfaceFilter, create, isSurfaceFilter, makeFilter, makeType } from './types';
+import * as Role from '../../../common/Role';
+import { useIsSurfaceAvailable } from './SurfaceComponent';
+import { indexByRole } from './SurfaceManager';
+import { type Filter, create, isFilter, makeFilter } from './types';
 
-describe('Surface.makeType', () => {
-  test('creates a role token with the given NSID', ({ expect }) => {
-    const token = makeType<{ subject: string }>('org.dxos.test.role.testRole');
-    expect(token.role).toBe('org.dxos.test.role.testRole');
-  });
-
-  test('tokens with the same role are independent objects (identity-by-role)', ({ expect }) => {
-    const tokenOne = makeType<{ x: number }>('org.dxos.test.role.shared');
-    const tokenTwo = makeType<{ x: number }>('org.dxos.test.role.shared');
-    expect(tokenOne).not.toBe(tokenTwo);
-    expect(tokenOne.role).toBe(tokenTwo.role);
-  });
-
-  test('throws on invalid NSID at runtime (hyphenated final segment)', ({ expect }) => {
-    expect(() => makeType('org.dxos.test.role.bad-name' as any)).toThrow();
-  });
-
-  test('throws on single-segment NSID', ({ expect }) => {
-    expect(() => makeType('article' as any)).toThrow();
-  });
-});
-
-describe('isSurfaceFilter', () => {
+describe('isFilter', () => {
   test('distinguishes filter objects from predicate functions', ({ expect }) => {
-    const filter: SurfaceFilter<Record<string, any>> = {
+    const filter: Filter<Record<string, any>> = {
       bindings: [{ role: 'org.dxos.test.role.r', guard: () => true }],
     };
-    expect(isSurfaceFilter(filter)).toBe(true);
-    expect(isSurfaceFilter(() => true)).toBe(false);
-    expect(isSurfaceFilter({})).toBe(false);
-    expect(isSurfaceFilter(null)).toBe(false);
+    expect(isFilter(filter)).toBe(true);
+    expect(isFilter(() => true)).toBe(false);
+    expect(isFilter({})).toBe(false);
+    expect(isFilter(null)).toBe(false);
   });
 });
 
 describe('create', () => {
-  test('expands a single-binding SurfaceFilter into a role string', ({ expect }) => {
-    const token = makeType<Record<string, any>>('org.dxos.test.role.article');
+  test('expands a single-binding filter into a role string', ({ expect }) => {
+    const token = Role.make<Record<string, any>>('org.dxos.test.role.article');
     const filter = makeFilter(token, (data) => data.subject === 'ok');
     const def = create({ id: 'typedSingle', filter, component: () => null });
     expect(def.role).toBe('org.dxos.test.role.article');
@@ -54,10 +33,10 @@ describe('create', () => {
     expect(def.filter!({ subject: 'no' }, 'org.dxos.test.role.article')).toBe(false);
   });
 
-  test('expands a multi-binding SurfaceFilter into a role array with role-scoped guards', ({ expect }) => {
-    const tokenA = makeType<Record<string, any>>('org.dxos.test.role.article');
-    const tokenB = makeType<Record<string, any>>('org.dxos.test.role.section');
-    const filter: SurfaceFilter<Record<string, any>> = {
+  test('expands a multi-binding filter into a role array with role-scoped guards', ({ expect }) => {
+    const tokenA = Role.make<Record<string, any>>('org.dxos.test.role.article');
+    const tokenB = Role.make<Record<string, any>>('org.dxos.test.role.section');
+    const filter: Filter<Record<string, any>> = {
       bindings: [
         { role: tokenA.role, guard: (data) => (data as any).subject === 'a' },
         { role: tokenB.role, guard: (data) => (data as any).subject === 's' },
@@ -76,43 +55,57 @@ describe('create', () => {
   });
 
   test('passes position through untouched', ({ expect }) => {
-    const token = makeType<Record<string, any>>('org.dxos.test.role.r');
-    const filter: SurfaceFilter<Record<string, any>> = { bindings: [{ role: token.role, guard: () => true }] };
+    const token = Role.make<Record<string, any>>('org.dxos.test.role.r');
+    const filter: Filter<Record<string, any>> = { bindings: [{ role: token.role, guard: () => true }] };
     const def = create({ id: 'pos', filter, component: () => null, position: Position.last });
     expect(def.position).toBe(Position.last);
   });
+
+  test('does not throw on an invalid local id (dropped at dispatch instead)', ({ expect }) => {
+    const token = Role.make<Record<string, any>>('org.dxos.test.role.article');
+    const filter = makeFilter(token, () => true);
+    expect(() => create({ id: 'gallery-article', filter, component: () => null })).not.toThrow();
+  });
 });
 
-describe('role token typing', () => {
-  test('makeType preserves TData through token use-sites', ({ expect }) => {
-    // Type-level smoke test: if TS compiles, we're fine.
-    const token: RoleToken<{ subject: number }> = makeType('org.dxos.test.role.numeric');
-    expect(token.role).toBe('org.dxos.test.role.numeric');
+describe('indexByRole', () => {
+  const token = Role.make<Record<string, any>>('org.dxos.test.role.article');
+  const filter = makeFilter(token, () => true);
+
+  test('indexes definitions by role', ({ expect }) => {
+    const valid = create({ id: 'valid', filter, component: () => null });
+    const index = indexByRole([valid]);
+    expect(index.get(token.role)).toEqual([valid]);
+  });
+
+  test('does not filter on id validity (SurfaceManager is responsible for that)', ({ expect }) => {
+    const valid = create({ id: 'valid', filter, component: () => null });
+    const invalid = create({ id: 'gallery-article', filter, component: () => null });
+    const index = indexByRole([valid, invalid]);
+    expect(index.get(token.role)).toEqual([valid, invalid]);
   });
 });
 
-describe('isSurfaceAvailable typing', () => {
+describe('useIsSurfaceAvailable 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 }>('org.dxos.test.role.section');
-  const capabilityManager = { getAll: () => [] } as unknown as CapabilityManager.CapabilityManager;
+  // the typed overload narrows `data` to the token's declared contract. The
+  // hook is never invoked — only its return type is used to type-check calls.
+  const sectionToken = Role.make<{ attendableId: string; subject: string }>('org.dxos.test.role.section');
+  const isSurfaceAvailable = (() => false) as ReturnType<typeof useIsSurfaceAvailable>;
 
   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' },
-    });
+    isSurfaceAvailable({ 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' } });
+    isSurfaceAvailable({ 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' } });
+    isSurfaceAvailable({ type: sectionToken, data: { attendableId: 123, subject: 'x' } });
   });
 });