Support for hosting Perfetto in a Theia Electron application

- enable generating .d.ts files. Some types had to be exported that
  previously weren't in order for TypeScript to be able to correctly
  resolve its generated type definitions
- prevent loading sidebar and other unnecessary parts of UI
- add other global flags to externally control Perfetto functionality
- support loading the trace database from a stream provided by the
  host application (such as from a remote Theia backend)
- optionally copy the Perfetto CSS and WASM Engine in the build for
  bundling in an Electron application
- adjust routing to work with applications that use hashes already
  (such as in Theia for for opening workspaces)
  - introduce routing that uses url search params and keeps existing
    values for the hash that are not params
  - if a new route has no page/subpage at all, don't reacting to
    the route change
- allow unsafe inline CSS via configuration option (required for Theia)
- allow to control cache keys because chromium only allows to cache
  http-family protocols. In Electron we have file:// however, so we may
  use a prefix to fake this.
- allow file CORS origins for Electron-based applications
- ensure we preserve empty strings in URL creation
- support opening multiple traces in same Electron application by
  making the port customizable on a per-AppImpl basis (using the window
  URL is impractical in a Theia application)
- support multiple instantiation of Perfetto. Add an optional build step
  to copy the transpiled code into the package so that it can be
  installed multiple times in an application without sharing one copy
  via symlink (and also because Theia's yarn build breaks the symlink
  when copying the package into the node_modules/ directory)
- make @types/mithril a dev dependency
- remove unused dependencies from package.json (#65)
- explicitly define which location TS @types should be read from.
  Otherwise the tsc compiler possibly finds the types in a parent's
  folder node_modules/@types directory, which then causes build failures
  in the host Theia/Electron application, as those files are not ignored
  like the local node_modules is
- support opening Perfetto pages such as the Trace Info page in separate
  subtrees of the DOM (in a Theia application, in different widget-tabs)
  via a new optional ViewOpener configured in the AppImpl. Employ this
  view opener in the Errors (info) button in the topbar
- Scope key handling to the viewer page so that it doesn't get key
  events from other UI elements in the host Theia/Electron application
- current script is null also in a Theia application, not just tests
- fix macro redef warning in trace processor build for macOS 15.4 SDK
- fill holes in painting the overview timeline panel (evident in Theia
  colour themes)
- allow embedding of the Perfetto UI via an explicit CSS class on its
  main element in addition to the default DOM nesting position
- implement a means to suppress the built-in handling of trace file drop
- add to the context a prop suppressing the dialog that prompts to open
  a trace already loaded in the trace_processor_shell, for applications
  that manage this externally
- provide API to remove all registered error handlers. An embedding
  application often has its own error handling so provide an API for
  such application to remove all registered error handlers and then it
  can supply its own
- return showHelp's showModal promise. This allows a host application to
  track whether the help dialog is (still) showing

Co-authored-by: Johannes Faltermeier <jfaltermeier@eclipsesource.com>
Co-authored-by: Martin Fleck <mfleck@eclipsesource.com>
Co-authored-by: Warren Paul <w.paul@samsung.com>
Co-authored-by: dfriederich <109323095+dfriederich@users.noreply.github.com>
Co-authored-by: Andrew Levans <121060410+ALevansSamsung@users.noreply.github.com>
Signed-off-by: Christian W. Damus <cdamus.ext@eclipsesource.com>

Author: 6 people

ui/src/base/adapter.ts

@@ -0,0 +1,81 @@
+// Copyright (C) 2025 The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/** A function that can _adapt_ some object to another type. */
+export type Adapter<T extends object> = (obj: object) => T | undefined;
+
+/**
+ * An adapter can adapt objects to types identified by adapter keys,
+ * being either
+ * - a class for object types, or
+ * - a symbol for interface types
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AdapterKey = symbol | ClassType<any>;
+
+export type ClassType<T extends object> = Function & { prototype: T };
+
+class AdapterRegistry {
+  private readonly adapters = new Map<AdapterKey, Adapter<object>[]>();
+
+  /** Register an adapter for some class type. */
+  register<T extends object>(adapter: Adapter<T>, forType: ClassType<T>): this;
+  /** Register an adapter for some interface type identified by a symbol. */
+  register<T extends object>(adapter: Adapter<T>, forType: symbol): this;
+  register<T extends object>(adapter: Adapter<T>, forKey: AdapterKey): this {
+    let adapters = this.adapters.get(forKey);
+    if (adapters === undefined) {
+      adapters = [];
+      this.adapters.set(forKey, adapters);
+    }
+    adapters.push(adapter);
+    return this;
+  }
+
+  /** Adapt the given object to some class type. */
+  adapt<T extends object>(obj: object, toType: ClassType<T>): T | undefined;
+  /** Adapt the given object to some interface type identified by a symbol. */
+  adapt<T extends object>(obj: object, toType: symbol): T | undefined;
+  adapt<T extends object>(obj: object, toKey: AdapterKey): T | undefined {
+    const adapters = this.adapters.get(toKey) ?? [];
+    if (typeof toKey === 'symbol') {
+      for (const adapter of adapters) {
+        const result = adapter(obj);
+        if (result !== undefined) {
+          return result as T;
+        }
+      }
+    } else {
+      for (const adapter of adapters) {
+        const result = adapter(obj);
+        if (result instanceof toKey) {
+          return result as T;
+        }
+      }
+    }
+    return undefined;
+  }
+}
+
+export const adapterRegistry = new AdapterRegistry();
+
+/** Adapt the given object to some class type. */
+export function adapt<T extends object>(obj: object, toType: ClassType<T>): T | undefined;
+/** Adapt the given object to some interface type identified by a symbol. */
+export function adapt<T extends object>(obj: object, toType: symbol): T | undefined;
+export function adapt<T extends object>(obj: object, toKey: AdapterKey): T | undefined {
+  return (typeof toKey === 'symbol') ?
+    adapterRegistry.adapt(obj, toKey) :
+    adapterRegistry.adapt(obj, toKey);
+}

ui/src/base/assets.ts

@@ -19,9 +19,11 @@ let rootUrl = '';
 /**
  * This function must be called once while bootstrapping in a direct script
  * context (i.e. not a promise or callback). Typically frontend/index.ts.
+ * @param hostApplicationRelative relative path of the app directory when integrated
+ *   in some host application
  */
-export function initAssets() {
-  rootUrl = getServingRoot();
+export function initAssets(hostApplicationRelative?: string) {
+  rootUrl = getServingRoot(hostApplicationRelative);
 }
 
 /**

ui/src/base/http_utils.ts

@@ -12,7 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import {IntegrationContext} from '../core/integration_context';
 import {assertTrue} from './logging';
 
 export function fetchWithTimeout(
@@ -72,17 +71,19 @@ export function fetchWithProgress(
  * NOTE: this function can only be called from synchronous contexts. It will
  * fail if called in timer handlers or async continuations (e.g. after an await)
  * Use assetSrc(relPath) which caches it on startup.
+ * @param hostApplicationRelative relative path of the app directory when integrated
+ *   in some host application
  * @returns the directory where the app is served from, e.g. 'v46.0-a2082649b'
  */
-export function getServingRoot() {
+export function getServingRoot(hostApplicationRelative?: string) {
   // Works out the root directory where the content should be served from
   // e.g. `http://origin/v1.2.3/`.
   const script = document.currentScript as HTMLScriptElement;
 
   if (script === null) {
     // Can be null in tests or embedding application.
-    assertTrue(typeof jest !== 'undefined' || IntegrationContext.instance !== undefined);
-    return '';
+    assertTrue(typeof jest !== 'undefined' || hostApplicationRelative !== undefined);
+    return hostApplicationRelative ?? '';
   }
 
   let root = script.src;

ui/src/base/logging.ts

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import {App} from '../public/app';
 import {VERSION} from '../gen/perfetto_version';
 import {exists} from './utils';
 
@@ -21,6 +22,7 @@ export interface ErrorStackEntry {
   location: string; // e.g. frontend_bundle.js:12:3
 }
 export interface ErrorDetails {
+  app: App;
   errType: ErrorType;
   message: string; // Uncaught StoreError: No such subtree: tracks,1374,state
   stack: ErrorStackEntry[];

ui/src/components/aggregation_panel.ts

@@ -131,7 +131,7 @@ export class AggregationPanel
     return m(
       '.time-range',
       'Selected range: ',
-      m(DurationWidget, {dur: duration}),
+      m(DurationWidget, {trace: this.trace, dur: duration}),
     );
   }
 

ui/src/components/details/add_ephemeral_tab.ts

@@ -12,16 +12,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import {uuidv4} from '../../base/uuid';
-import {AppImpl} from '../../core/app_impl';
 import {Tab} from '../../public/tab';
+import {Trace} from '../..//public/trace';
 
-// TODO(primiano): this method should take a Trace parameter (or probably
-// shouldn't exist at all in favour of some helper in the Trace object).
-export function addEphemeralTab(uriPrefix: string, tab: Tab): void {
+// TODO(primiano): this method probably shouldn't exist at all in favour
+// of some helper in the Trace object.
+export function addEphemeralTab(trace: Trace, uriPrefix: string, tab: Tab): void {
   const uri = `${uriPrefix}#${uuidv4()}`;
 
-  const tabManager = AppImpl.instance.trace?.tabs;
-  if (tabManager === undefined) return;
+  const tabManager = trace.tabs;
   tabManager.registerTab({
     uri,
     content: tab,

ui/src/components/details/slice_details.ts

@@ -79,33 +79,34 @@ export function renderDetails(
       }),
       m(TreeNode, {
         left: 'Start time',
-        right: m(Timestamp, {ts: slice.ts}),
+        right: m(Timestamp, {trace, ts: slice.ts}),
       }),
       exists(slice.absTime) &&
         m(TreeNode, {left: 'Absolute Time', right: slice.absTime}),
       m(
         TreeNode,
         {
           left: 'Duration',
-          right: m(DurationWidget, {dur: slice.dur}),
+          right: m(DurationWidget, {trace, dur: slice.dur}),
         },
         exists(durationBreakdown) &&
           slice.dur > 0 &&
           m(BreakdownByThreadStateTreeNode, {
+            trace,
             data: durationBreakdown,
             dur: slice.dur,
           }),
       ),
-      renderThreadDuration(slice),
+      renderThreadDuration(slice, trace),
       slice.thread &&
         m(TreeNode, {
           left: 'Thread',
-          right: renderThreadRef(slice.thread),
+          right: renderThreadRef(trace, slice.thread),
         }),
       slice.process &&
         m(TreeNode, {
           left: 'Process',
-          right: renderProcessRef(slice.process),
+          right: renderProcessRef(trace, slice.process),
         }),
       slice.process &&
         exists(slice.process.uid) &&
@@ -133,7 +134,7 @@ export function renderDetails(
   );
 }
 
-function renderThreadDuration(sliceInfo: SliceDetails) {
+function renderThreadDuration(sliceInfo: SliceDetails, trace: Trace) {
   if (exists(sliceInfo.threadTs) && exists(sliceInfo.threadDur)) {
     // If we have valid thread duration, also display a percentage of
     // |threadDur| compared to |dur|.
@@ -143,7 +144,7 @@ function renderThreadDuration(sliceInfo: SliceDetails) {
     return m(TreeNode, {
       left: 'Thread duration',
       right: [
-        m(DurationWidget, {dur: sliceInfo.threadDur}),
+        m(DurationWidget, {trace, dur: sliceInfo.threadDur}),
         threadDurFractionSuffix,
       ],
     });

ui/src/components/details/sql_table_tab.ts

@@ -57,7 +57,7 @@ export function addLegacyTableTab(
 }
 
 function addSqlTableTabWithState(state: SqlTableState) {
-  addEphemeralTab('sqlTable', new LegacySqlTableTab(state));
+  addEphemeralTab(state.trace, 'sqlTable', new LegacySqlTableTab(state));
 }
 
 class LegacySqlTableTab implements Tab {
@@ -163,7 +163,7 @@ class LegacySqlTableTab implements Tab {
             ...chartAttrs,
           },
         ],
-        addChart: (chart) => addChartTab(chart),
+        addChart: (chart) => addChartTab(this.state.trace, chart),
       }),
       m(MenuItem, {
         label: 'Pivot',
@@ -251,11 +251,13 @@ class LegacySqlTableTab implements Tab {
         ),
       this.selected.kind === 'table' &&
         m(SqlTable, {
+          trace: this.state.trace,
           state: this.selected.state,
           addColumnMenuItems: this.tableMenuItems.bind(this),
         }),
       this.selected.kind === 'pivot' &&
         m(PivotTable, {
+          trace: this.state.trace,
           state: this.selected.state,
           extraRowButton: (node) =>
             // Do not show any buttons for root as it doesn't have any filters anyway.

ui/src/components/details/thread_slice_details_tab.ts

@@ -255,8 +255,8 @@ export class ThreadSliceDetailsPanel implements TrackEventDetailsPanel {
   }
 
   private renderRhs(trace: Trace, slice: SliceDetails): m.Children {
-    const precFlows = this.renderPrecedingFlows(slice);
-    const followingFlows = this.renderFollowingFlows(slice);
+    const precFlows = this.renderPrecedingFlows(trace, slice);
+    const followingFlows = this.renderFollowingFlows(trace, slice);
     const args =
       hasArgs(slice.args) &&
       m(
@@ -272,7 +272,7 @@ export class ThreadSliceDetailsPanel implements TrackEventDetailsPanel {
     }
   }
 
-  private renderPrecedingFlows(slice: SliceDetails): m.Children {
+  private renderPrecedingFlows(trace: Trace, slice: SliceDetails): m.Children {
     const flows = this.trace.flows.connectedFlows;
     const inFlows = flows.filter(({end}) => end.sliceId === slice.id);
 
@@ -290,6 +290,7 @@ export class ThreadSliceDetailsPanel implements TrackEventDetailsPanel {
               title: 'Slice',
               render: (flow: Flow) =>
                 m(SliceRef, {
+                  trace,
                   id: asSliceSqlId(flow.begin.sliceId),
                   name:
                     flow.begin.sliceChromeCustomName ?? flow.begin.sliceName,
@@ -299,6 +300,7 @@ export class ThreadSliceDetailsPanel implements TrackEventDetailsPanel {
               title: 'Delay',
               render: (flow: Flow) =>
                 m(DurationWidget, {
+                  trace,
                   dur: flow.end.sliceStartTs - flow.begin.sliceEndTs,
                 }),
             },
@@ -316,7 +318,7 @@ export class ThreadSliceDetailsPanel implements TrackEventDetailsPanel {
     }
   }
 
-  private renderFollowingFlows(slice: SliceDetails): m.Children {
+  private renderFollowingFlows(trace: Trace, slice: SliceDetails): m.Children {
     const flows = this.trace.flows.connectedFlows;
     const outFlows = flows.filter(({begin}) => begin.sliceId === slice.id);
 
@@ -334,6 +336,7 @@ export class ThreadSliceDetailsPanel implements TrackEventDetailsPanel {
               title: 'Slice',
               render: (flow: Flow) =>
                 m(SliceRef, {
+                  trace,
                   id: asSliceSqlId(flow.end.sliceId),
                   name: flow.end.sliceChromeCustomName ?? flow.end.sliceName,
                 }),
@@ -342,6 +345,7 @@ export class ThreadSliceDetailsPanel implements TrackEventDetailsPanel {
               title: 'Delay',
               render: (flow: Flow) =>
                 m(DurationWidget, {
+                  trace,
                   dur: flow.end.sliceStartTs - flow.begin.sliceEndTs,
                 }),
             },

ui/src/components/details/thread_state.ts

@@ -14,6 +14,7 @@
 
 import m from 'mithril';
 import {duration, TimeSpan} from '../../base/time';
+import {Trace} from '../../public/trace';
 import {Engine} from '../../trace_processor/engine';
 import {
   LONG,
@@ -116,30 +117,31 @@ export async function breakDownIntervalByThreadState(
   };
 }
 
-function renderChildren(node: Node, totalDur: duration): m.Child[] {
+function renderChildren(trace: Trace, node: Node, totalDur: duration): m.Child[] {
   const res = Array.from(node.children.entries()).map(([name, child]) =>
-    renderNode(child, name, totalDur),
+    renderNode(trace, child, name, totalDur),
   );
   return res;
 }
 
-function renderNode(node: Node, name: string, totalDur: duration): m.Child {
+function renderNode(trace: Trace, node: Node, name: string, totalDur: duration): m.Child {
   const durPercent = (100 * Number(node.dur)) / Number(totalDur);
   return m(
     TreeNode,
     {
       left: name,
       right: [
-        m(DurationWidget, {dur: node.dur}),
+        m(DurationWidget, {trace, dur: node.dur}),
         ` (${durPercent.toFixed(2)}%)`,
       ],
       startsCollapsed: node.startsCollapsed,
     },
-    renderChildren(node, totalDur),
+    renderChildren(trace, node, totalDur),
   );
 }
 
 interface BreakdownByThreadStateTreeNodeAttrs {
+  trace: Trace,
   dur: duration;
   data: BreakdownByThreadState;
 }
@@ -149,6 +151,6 @@ export class BreakdownByThreadStateTreeNode
   implements m.ClassComponent<BreakdownByThreadStateTreeNodeAttrs>
 {
   view({attrs}: m.Vnode<BreakdownByThreadStateTreeNodeAttrs>): m.Child[] {
-    return renderChildren(attrs.data.root, attrs.dur);
+    return renderChildren(attrs.trace, attrs.data.root, attrs.dur);
   }
 }