RFC-0009: Embeddable UI

[github-actions[bot]]

📄 RFC Doc: 0009-embeddable-ui.md

---

Embeddable UI

Authors: @stevegolton

Status: Draft

Problem

This doc outlines the process of making the UI embeddable - i.e. make it
possible to instantiate one or more instances of the UI within another web-based
application and control the instances from the host application, without the use
of iframes or other isolation techniques.

Perfetto currently expects to be the only thing in the web page and thus
directly accesses things like the DOM, the URL, and postmessage channels. What's
more, it is entirely written to be self-contained, and doesn't offer any
interface through which it can be configured programmatically.

Compelling Example

A web app that embeds two instances of the perfetto UI, loads two traces from
some arbitrary source and injects them into each instance. Traces are managed
entirely from the host application. The two instances should look and feel like
the host application as much as possible.

Requirements

• Avoid Collisions: Allow instantiating the UI directly within another web
  app, avoiding collisions and conflicts with the host app also other instances
  of the Perfetto UI.
  • Control mount point (don't just mount to document.main).
  • Contain Router & anchors (don't allow anchors to change the URL & control
    router logic).
  • Avoid CSS naming collisions.
  • Avoid localstorage naming collisions and add prefixes for certain frameworks
    restrictions?
  • Disable listening on the postmessage interface.
• Host Integration: Allow the embedder to programmatically control and
  customize the UI's behavior and appearance.
  • Allow complete control of trace management up to the embedder.
  • Customize theme colors & other settings.
  • Control page / route.
  • Configure CSP.
  • Install custom error handlers.
  • Routing hooks - intercept or override route handling.
  • Delegate app state persistence to the host app.
  • Inject appinitargs (e.g what would usually come from the URL on initial
    load).
  • Control analytics.
  • Themability - allow the embedder to inject styles to make Perfetto
    look more like their own app.

Design

The design outlined in this doc revolves around the idea of splitting Perfetto
into two parts:

1. An isolated and configurable central core packaged as a JS library with TS
   bindings. This is the reusable core which can be used in the standalone and
   embedded contexts. This idea is that this library will be configurable,
   conservative, and avoid touching the DOM or too many browser APIs, and won't
   have any import time.
2. A standalone application which uses this library and hooks it up to the
   browser and mounts the root mithril node, etc. This is the UI that will be
   hosted at ui.perfetto.dev.

This separation actually somewhat exists right now with frontend/index.ts +
common.scss being the standalone part, and the rest of the code being the
library. The separation however is not perfect. The core of the app definitely
directly accesses a lot of DOM and browser APIs but the general outline is
already there, we just need to lean into this architecture a little more.

Building and Importing

How would an embedder actually import and use the generated bundle?

If we imported the current frontend bundle directly, we would end up importing
all of the frontend/index.ts code as well which would immediately run on
startup, which is not what we want. Ideally we should have two builds - one for
the library that doesn't run anything and simply exports the classes and
functions required by the embedding application.

We can configure rollup to build us two bundles - a library and a standalone
webapp:

export default [
  // 1. Standalone App Config
  {
    input: "src/main.ts",
    output: {
      file: "dist/app.bundle.js",
      format: "iife", // or umd
      name: "MyApp",
    },
    // ... plugins for webapp
  },
  // 2. Library Config
  {
    input: "src/lib.ts",
    output: [
      { file: "dist/lib.esm.js", format: "es" },
      { file: "dist/lib.cjs.js", format: "cjs" },
    ],
    // Ensure you don't bundle peer dependencies (like mithril) in the lib build
    external: ["mithril"],
  },
];

Then in the embedder or the standalone we can use the bundle like so:

import {AppImpl} from 'perfetto'; // Import from the library.

// Configure hooks and callbacks so that Perfetto can talk to the DOM + browser APIs, or stub them out.
AppImpl.initialize({...config});

// Render (or mount) the UI into an element on the page.
m.render(targetElem, m(UiMain, {...}));

This will allow us to ship the library to 3rd parties and package the standalone
version for us. It's crucial that the library doesn't have any side effects at
the root level (e.g. when importing).

Shared app vs separate apps

If we can have multiple instances of Perfetto in a single page, this raises the
question of whether we have one app or many?

Shared 'App' (Preferred)

// Initialize a common, global app - this function must be called first.
AppImpl.initialize(config);

// Load the first trace and inject it into the first UI instance
const trace1 = app.openTraceFromFile(traceFile1);
m.render(elem1, m(UiMain, { trace1 }));

// Load the second trace and inject it into the second UI instance
const trace2 = app.openTraceFromFile(traceFile2);
m.render(elem2, m(UiMain, { trace2 }));

Pros:

• Very similar to the current design - limited refactoring. We can leave the
  globals in place.
• Plugins currently assume there is only one app, and plugins often use the
  global state to store app related entities, such as settings, in their
  onActivate function.
• No need to prop drill the app through multiple layers of mithril components,
  we can access the global instance AppImpl.instance.

Cons:

• All instances of the UI share the same app state settings (not trace state, as
  this is stored in the trace object).
• The app can no longer contain a reference to the trace e.g. app.trace,
  because one app can now be used with many traces. We would need to invert the
  dependencies, and also separate the shared registries such as commands,
  sidebar entries, and pages so that the trace object has its own set of
  registries.

Separate Apps

const app1 = new AppImpl({ ...config1 });
app1.openTraceFromFile(traceFileHandle1);
m.render(elem1, m(UiMain, { app1 }));

const app2 = new AppImpl({ ...config2 });
app2.openTraceFromFile(traceFileHandle2);
m.render(elem2, m(UiMain, { app2 }));

Pros:

• We can have different settings and configuration per app.
• We can keep the notion of one trace per app (e.g. app.trace).

Cons:

• We need to be very careful with mutable global state. Plugins tend to write
  settings references registered in onActivate for instance to global storage so
  that it can be used inside onTraceLoad().
• Large refactor removing all globals including:
  • AppImpl.instance
  • Router
  • Flags
• We need to prop-drill app through potentially many layers of mithril
  components.

Multi-trace Tenancy

Given that we have one app and many traces, we must remove any state from any
given trace from the app.

Trace-scoped Entities

Right now, when commands et al are registered with a trace, they are actually
added to the app's registry and removed when the trace is disposed. This won't
work if we can have multiple traces loaded simultaneously with a shared single
app instance.

Instead we should:

• Store the commands et al on the trace object itself inside its own registries.
• When a command is requested on a trace object, the trace's own registry is
  searched first, followed by the app's registry.
• To avoid accidentally shadowing commands et al in the app with the same id, when an
  entity is added to the trace, it first checks for the existence of that entity
  in the app and throws if there exists a duplicate.

Example implementation:

class CommandManager {
  constructor(private readonly app: AppImpl) {}

  registerCommand(cmd: Command) {
    if (app.commands.has(cmd.id)) {
      throw new Error(`Duplicate command ${cmd.id}`);
    }
    this.registry.set(cmd.id, cmd);
  }

  runCommand(id: string, ...args: unknown[]) {
    const cmd = this.registry.get(id) ?? app.registry.get(id);
    return cmd?.cb(args);
  }
}

This decoupling also makes it much easier to dispose of a trace, as all state
related to a trace is contained within the trace object itself. We can simply
drop all references to a given trace object when we're done with it, we don't
need an explicit dispose step (with the exception of stopping the web worker
perhaps).

App-scoped Entities

Right now, the app stores a reference to the currently loaded trace. This is
useful for app-registered entities (e.g. commands) as they can simply call
app.trace to look up which trace they're working on.

Only one trace can be loaded at a time within the current environment so that
makes perfect sense. However, if we're now saying that the embedder takes
control of the trace, and the app has no concept of which traces are available,
what are the legitimate uses of the trace. Which trace do app-registered
entities work with?

In order to do this, we must now inject the trace into the command's callback
via some attribute. This trace object must originate from the calling context.

E.g.

// MyPlugin.ts
app.commands.registerCommand({
  id: "myCommand",
  callback: (ctx) => {
    console.log(ctx.trace);
  },
});

// Calling the command from somewhere else
trace.commands.runCommand("myCommand"); // ctx.trace === trace
app.commands.runCommand("myCommand"); /// ctx.trace === undefined

Trace Management

Right now, plugins et al can simply open a trace by calling openTrace on the
app, however in this new model we are taking the stance that the currently
loaded trace is controlled by the embedder and injected into the UI. However, it
can still be useful to allow plugins to be able to ask the embedder to open a
trace from within a plugin etc.

E.g. how do we manage this:

// MyPlugin.ts
app.sidebar.register({
  name: 'Open My Custom Trace',
  callback: () => {
    // Open a trace from somewhere.... (e.g. cloud / gdrive / multi-trace / etc).
    const mytrace: Trace = ...;

    // How does this work? The app has no concept of the current trace anymore.
    app.setCurrentTrace(mytrace);
  },
})

The most logical solution here is to defer this to the embedder.

let currentTrace: Trace | undefined;

AppImpl.initialize({
  onOpenTraceRequested: (trace) => {
    currentTrace = trace;
  },
});

In our embedded scenario:

AppImpl.initialize({
  onOpenTraceRequested: () => {
    throw new Error("Not possible to switch traces!");
  },
});

The embedder in this scenario would simply avoid adding any plugins that open
traces to avoid this error from ever occurring.

Trace loading statuses

When loading a trace load_trace.ts currently calls into the app to set the
omnibox text when the trace is loading in order to provide feedback to the user
about the trace loading process - now this state needs to be stored in the
individual trace object that's doing the loading. This way, the UiMain object
that's looking at the trace object can just glean the status from that instead.

WASM and HTTP-RPC Engines

When we call app.openTraceFromFile(), this will kick off a new independent
background thread and WASM instance per trace, rather than attempting to keep
the same background worker instance.

Cons: Could produce memory spikes when switching traces.

CSS

CSS has been largely fixed by the introduction of the pf-* prefix to avoid
collisions with classes in the parent page. We still do use some generic
selectors in common.scss such as h1, h2, h3 and similar, but in the standalone
example these are very reasonable. We could either include them in the
standalone build and omit for the embedded, or we could move them behind
specific style classes.

See: #2436

Within the embedded application, Perfetto's bundled CSS may be imported
dynamically or just added to the HTML header.

There still exists a lot of element styling - CSS rules targeting element types
directly e.g. h1, html, body, in common.scss. These styles belong squarely in
the domain of the standalone UI so we should bundle them separately (in the same
vein as we will bundle the JS bundles separately) and only include these
dedicated styles in the standalone build.

Theming

Similarly to the above, theming is supported via standalone CSS variables.

In the standalone application, we inject this in using the ThemeProvider
mithril component. This injects the CSS variables depending on the theme
setting.

AppImpl.initialize({...config});

const themeSetting = AppImpl.instance.settings.register({
  id: 'theme',
  name: '[Experimental] UI Theme',
  description: 'Warning: Dark mode is not fully supported yet.',
  schema: z.enum(['dark', 'light']),
  defaultValue: 'light',
} as const);

raf.mount(target, {
  view: () => {
    return m(ThemeProvider, {theme: themeSetting.get()}, m(UiMain));
  },
});

Within an embedded application, this ThemeProvider can be omitted assuming the
variables are injected via some other method.

Hotkey Capturing

Currently hotkeys are bound to the document. We currently use a HotkeyContext
mithril component which wraps most of the UI, and provides a focusable wrapper
which, when clicked on, becomes the focused element on the page and can capture
all following keyboard events. This is used in the current standalone UI like
so:

raf.mount(target, {
  view: () => {
    return m(
      HotkeyContext,
      {
        ...hotkeys,
        autoFocus: true, // Automatically focus on creation
      },
      m(UiMain),
    );
  },
});

However, this is largely disabled in the current UI as it causes focus loss
issues. It doesn't work well with programmatic element.blur() as used in the
omnibox for example. When this function is called, the user agent moves the
focus back to the root, not the nearest focusable ancestor. We would need to
implement something to handle this for us - possibly using a custom event.

// Omnibox.ts
// Don't call omnibox.blur()!
const focusEvent = new CustomEvent("delegatefocus", {
  bubbles: true,
});
omniboxElem.dispatchEvent(focusEvent);

// HotkeyContext.ts
// Capture the delegatefocus event if any of our children want to give up focus
// we can capture it!
hotkeyContextElem.addEventListener("delegatefocus", (e) => {
  hotkeyContextElem.focus();
  e.stopPropagation(); // Stop any ancestor HotkeyContexts from receiving focus
});

We would have to scour the codebase for all .blur() calls and instead dispatch
one of these delegatefocus events. Any embedder won't have any idea
what this even is and won't capture it, so it's unlikely to cause any issues
with the embedder.

This mechanism can actually even be used quite effectively to define hotkeys for
specific subpages - e.g. the explore page - by wrapping the page in a
HotkeyContext and providing a custom set of hotkeys/callbacks for that page.

Error Handling

We configure error handlers in frontend/index.ts currently. This can remain
as-is and these will not be configured in the embedded build. It's up to the
embedder to register root level error handlers to catch Perfetto crashes by
registering handlers for uncaught errors that propagate to the window:

window.addEventListener("error", (e) => reportError(e));
window.addEventListener("unhandledrejection", (e) => reportError(e));

Reporting errors from workers

Currently logging.reportError is called directly when errors occur inside
traceconv worker and/or the service worker. TODO: Needs more work to understand
exactly how these should behave. Ideally they should invoke an error that gets
thrown on the window's context so that it can propagate up and get handled at
the root level as above.

Modals

showModal() uses a global to store the current modal. This causes problems
when we have multiple UI instances in the same page - that one modal triggered
from one UI will show up in both UIs. We could fix this by storing the modal
state at the root of the UIMain instead, seeing as it's squarely a property of
the UI.

Plugins

The embedder should be in control of which plugins are
initiated. We can make this an option when initializing Perfetto.

import CORE_PLUGINS from "../gen/all_core_plugins";
import NON_CORE_PLUGINS from "../gen/all_plugins";
import defaultPlugins from "./core/default_plugins.ts";

AppImpl.initialize({
  // Core plugins might have special treatment in the future (such as not
  // allowing them to be disabled) - for now they're just concatenated with the
  // regular plugins.
  corePlugins: CORE_PLUGINS,
  plugins: NON_CORE_PLUGINS,
  defaultEnabledPlugins: defaultPlugins,
});

The standalone app will naturally import all of them and enable those only in
the default list.

Because of the global app state, we don't have to separate out the plugin
enabled/disabled settings (which are currently stored in the perfettoFlag
setting in localstorage). This does mean however, that if a plugin is enabled in
one instance, it'll also be enabled in another instance and vice versa. I think
this isn't the end of the world and is an understandable tradeoff.

It makes sense that the embedder should omit plugins that don't make any sense
in the embedded case - e.g. the example traces or the 'Open trace from file'
button. We will have to go through the plugins we have and perhaps separate them
out into smaller reusable chunks so that the embedder may pick and choose the
ones they need vs the ones that make no sense for the app.

Storage

In order to avoid collisions with local and cache storage keys between Perfetto
and the embedder, we should make it so that the key can be prefixed.

AppImpl.initialize({
  localStorageKeyPrefix: "perfetto-",
  cacheKeyPrefix: "perfetto-",
});

Routing

It makes sense that the embedder should have complete control over the route of
the UI so that it can keep the UI focused on a given page and change it
programmatically.

AppImpl.initialize({
  router: {
    navigate: () => {}, // Stubbed out
    currentRoute: () => {
      return "#!/viewer";
    },
  },
});

Anchors

Anchors that change the hash route are now just never going to work as they will
change the embedder's route. This could be quite complex. We could try and leave
the anchors in place and override them in embedders, though that goes against
the rest of the ethos in this doc of doing nothing by default.

We should probably introduce a new API on router so anchors can now link to new
pages and change the route like this:

app.router.navigate("query"); // Links to the query page
app.router.navigate("viewer"); // Links to the timeline page
app.router.navigate("settings/mysetting"); // Links to a specific setting on the settings page

We could even wrap this up behind the Anchor widget, and grey out the widget
if the embedder has not injected the correct link.

m(Anchor, { internalHref: "viewer" });

The href attribute is still supported for external links.

RAF Scheduler

While it would be nice to isolate refreshes to only the UI instance that needs
it - the most practical solution to dealing with the raf would be to just keep
it as a global object. Indeed the 'm' (mithril object) is global anyway, so we'd
have the same problem if we were to use m.mount() rather than raf.mount().

The ramifications of this mean that if one UI instance triggers an update, then
all UI instances will refresh, but that's a reasonable tradeoff for the
complexity that attempting to separate them would involve.

Analytics

Analytics would be configured by the standalone app, we can inject an analytics
handler into Perfetto at configuration time.

const analytics = initializeAnalytics();

AppImpl.initialize({
  onAnalyticsEvent: (e) => analytics.logEvent(),
});

By default logEvent() will just be a no-op.

Other

The following functionality will be entirely handled by the standalone app or the
embedder. Perfetto doesn't need to get involved at all.

• Loading traces via postmessage.
• Service worker.
• CSP configuration.

API Surface

The AppImpl.initialize() function is the primary entry point for both standalone and
embedded applications. It initializes the global app instance and configures all
the hooks that allow Perfetto to interact with its hosting environment.

Complete TypeScript Interface

/**
 * Configuration for initializing Perfetto.
 *
 * In standalone mode, most of these options will use their default values.
 * In embedded mode, the embedder has full control over how Perfetto interacts
 * with the host application.
 */
interface InitPerfettoConfig {
  /**
   * Initial route arguments, typically parsed from the URL in standalone mode.
   * In embedded mode, these can be used to control initial state (e.g., which
   * page to show, UI theme preferences, etc.)
   *
   * Default: Empty object {}
   */
  initialRouteArgs?: RouteArgs;

  /**
   * Core plugins that are fundamental to Perfetto's operation.
   * These may receive special treatment in the future (e.g., not allowing
   * them to be disabled).
   *
   * Default: All core plugins from gen/all_core_plugins
   */
  corePlugins?: PluginDescriptor[];

  /**
   * Additional plugins beyond the core set.
   *
   * Default: All plugins from gen/all_plugins
   */
  plugins?: PluginDescriptor[];

  /**
   * List of plugin IDs that should be enabled by default.
   * Users can still enable/disable plugins via settings, but this controls
   * the initial state.
   *
   * Default: Platform-specific defaults (see core/default_plugins.ts)
   */
  defaultEnabledPlugins?: string[];

  /**
   * Callback invoked when Perfetto (or a plugin) requests opening a new trace.
   * This allows the embedder to control trace loading behavior.
   *
   * In standalone mode: Switches the current trace and updates the UI
   * In embedded mode: Can throw an error to prevent trace switching, or
   *                   delegate to the embedder's trace management system
   *
   * Default: Switches the global app trace
   */
  onOpenTraceRequested?: (trace: Trace) => void;

  /**
   * Router configuration. Allows the embedder to control navigation behavior.
   *
   * In standalone mode: Uses the browser's URL hash for routing
   * In embedded mode: Embedder controls routing, can stub out navigation
   */
  router?: RouterConfig;

  /**
   * Prefix for localStorage keys to avoid collisions with the host application.
   * All Perfetto localStorage keys will be prefixed with this string.
   *
   * Default: '' (no prefix)
   */
  localStorageKeyPrefix?: string;

  /**
   * Prefix for cache storage keys (for service worker caches, IndexedDB, etc.)
   * to avoid collisions with the host application.
   *
   * Default: '' (no prefix)
   */
  cacheKeyPrefix?: string;

  /**
   * Callback invoked when Perfetto logs an analytics event.
   * This allows the embedder to implement custom analytics handling.
   *
   * In standalone mode: Logs to Google Analytics (if enabled)
   * In embedded mode: Typically a no-op or custom analytics handler
   *
   * Default: No-op function
   */
  onAnalyticsEvent?: (event: AnalyticsEvent) => void;
}

/**
 * Router configuration for controlling navigation in Perfetto.
 */
interface RouterConfig {
  /**
   * Called when Perfetto wants to navigate to a new route.
   * The embedder can handle this however they want (e.g., update their own
   * routing state, show a different view, or ignore it entirely).
   *
   * @param route - The route string (e.g., 'viewer', 'query', 'settings/theme')
   */
  navigate: (route: string) => void;

  /**
   * Returns the current route that Perfetto should display.
   * This is called frequently to determine which page to render.
   *
   * @returns Route string (e.g., '#!/viewer', '/query', etc.)
   */
  currentRoute: () => string;
}

Risks

• Some of these design decisions will involve an ongoing cost to maintain,
  essentially making sure that all new code doesn't assume that the standalone
  application is the only deployment context. This will introduce an additional
  review burden.
• There is guaranteed to be additional issues and roadblocks that haven't been
  addressed in this document.
• Designing for the UI to be purposely used as a library exposes an API surface
  that is difficult to change in the future. Is this something we want to agree
  to and maintain going forward? There will be some additional overhead to test
  for regressions?

---

💬 Discussion Guidelines:

• This discussion is automatically synced with the RFC document
• Please provide constructive feedback and suggestions

[stevegolton]

@cdamus Apologies for how long it took me to get this together, but I would really value your feedback on this :)

[cdamus]

Thanks @stevegolton ! This is a very thorough exploration of the issues and maps very well to my application's requirements. I'll spend some time mulling it all over to provide some useful comments.

[stevegolton]

A glaring omission from this doc is any mention of the omnibox, and practically how modals will work.

The concern is mostly around how to trigger an omnibox prompt or modal in the correct UI instance if we can now have multiple instances.

Currently for modals we just call the global showModal() function. And for omnibox prompts we call app.omnibox.prompt().

It seems that some state currently in the app or globals actually needs to be per UI instance, rather than one global one for all instances.

[cdamus]

On the matter of the omnibox: I have had success in my application and my fork of Perfetto by moving the OmniboxManager into the Trace where the App's OmniboxManager

• creates and maintains sub-managers for each open Trace. Therefore each such child omnibox manager must be disposed of when a trace is closed
• tracks which child OmniboxManager is active. In my fork, at most one instance of the UiMain can be active at any time because only a single widget/editor in my application can have the input focus. And that focus determines which trace is active and, therefore, which child OmniboxManager is active
• when no child is active, then the omnibox provides its app-level services

So, for example, in my fork the calls to app.omnibox.prompt() are routed through the contextual trace of the UiMain where applicable. It seems to work well but perhaps I just haven't yet encountered the corners of the UI where it falls over.

[cdamus]

On the matter of modals: my application has not yet addressed their singletonness. (It would be next on my to-do list). The proposal so far suggests that their state could be maintained in the UiMain. That makes sense to me and would work in my application.

However, currently the rendering of the modals also is confined to the UiMain. For my application it would actually be nice for the embedder API to support provision of the DOM element into which the modal backdrop (and therefore dialogs) is portal-injected. That would allow the modals in my application to cover also some of the chrome that it puts around the UiMain and, ideally, to unify the look-and-feel of Perfetto's modals with the modal dialogs of the framework on which my application is built.

[primiano]

Thanks a lot for this. this is... A LOT.
I read through this and added some comments below.

My main reaction after getting to the bottom of this proposal is that IMHO this should be split really into two different discussions:

1. How to move most things to TraceImpl, split cleanly AppImpl from TraceImpl, and wrap a UI component that can be instantiated more than once. This is really the most niche (and perhpas controversial part) because, to the day, I am not aware of nobody other than @cdamus's project who want to do this (this: >1 TraceImpl at the same time within the same page)

2. How to cleanly decouple our UI to separate the more "core" features from the "embedder customizable ones".
   The use case here is: somebody wants to embed ui.perfetto.dev somewhere else, and they want to do so by just forking the repo and just touching one file (site.ts/deployment.ts which does the outer wiring).
   It's precisely the same story between "Chrome (the google owned browser)" and "Chromium content API" (the thing that Edge, Opera and other wrap to build their own browser). Chromium content API is 90% of the core thing that everybody wants, and then Chrome injects on top things like bookmarks, download manager etc.

The same applies here. We want to split out things like analytics, default plugins, error reporting, to give flexibility to embedders.

I find a bit difficult to reason atomically about both 1+2 (although at some point they will not be completely disjoint)

Avoid localstorage naming collisions and add prefixes for certain frameworks

Ok but we need to handle backward compat somehow.
Maybe the pragmatic thing is to plumb a prefix string that the embedder passes, and we leave that prefix empty by default for us?

Disable listening on the postmessage interface.

An isolated and configurable central core packaged as a JS library with TS
bindings.

Do we actually need this? This feels a further mainteinance burden TBH with little value for ourselves.

I think we should stop at "the codebase is in the right shape... now other people can make a good use of it"

I'd be more in favour of splitting things in folders in a way that clearly decouples the "common embeddable part" vs "our App (with our postmessage etc)"

I would NOT split bundles for ourselves, as that seems a recipe for further debugging headaches, which would not benefit us at all.

In other words, I am in favour of the architectural cleanup, but I am not a fan of the "splitting into library and figuring out redist" part.
Leave this to other parties, in the same way chrome leaves this to Electron.

I think we should limit our support to "you can define a site.ts / installtion.ts (name TBD) and you can configure hooks when forking the repo"

Shared 'App' (Preferred)

+1. >1 AppImpl has too many edge cases and, more importantly, increased cognitive load that we'd have to keep in mind for a use case we never use (which means we'd break it regularly)

Trace-scoped Entities

Strong +1, just I'd probably do something at the registry level (e.g. introduce the notion of "parent registry" or similar) rather than doing on a case-by-case basis? (unless practicalities prove otherwise)?

There is also something else to say, probably more for the longer term to avoid scope creep: I'd probably switch to a model where the intersection of AppImpl and TraceImpl is empty. So rather than saying "there is an omnibox manager, which works both for app and trace, etc etc" I'd say:

• Move everything to TraceImpl (sidebar, omnibox etc)
• Create some dedicated class/UX for the "open a blank ui.perfetto.dev instance").
• Some few people will be a bit sad (what if I wanted to have a command that can operate without traces) but overall i feel this simplifies a lot our thinking.
• So we leave AppImpl only for things that are truly global like Analytics, Settings, & PluginManager
• Create some dedicated alternative (e.g. GlobalCommands) for it

When loading a trace load_trace.ts currently calls into the app to set the omnibox text when the trace is loading in order to provide feedback to the user about the trace loading process

We should prob invert this dependency and have loadTrace to take a listener interface, and wire it up on the other end

There still exists a lot of element styling - CSS rules targeting element types directly e.g. h1, html, body, in common.scss. These styles belong squarely in the domain of the standalone UI so we should bundle them separately (in the same vein as we will bundle the JS bundles separately) and only include these dedicated styles in the standalone build.

Well pragmatically we need to rely on reset.js or similar.
If the embedder doesn't reset the core CSS classes or does something funky there is nothing we can do.

We could fix this by storing the modal state at the root of the UIMain instead, seeing as it's squarely a property of the UI.

+1 although the css styling might be tricky. we should audit all cases of position:fixed in css (I think the drag & drop handler is another one)

Routing

I think this is going to be more complicated...perhaps the trickiest part of all this proposal.
but I need to think more / hard to elaborate in writing on this.

If you just stub out router.navigate() various things will break as plugins depend on that.

Anchors

The problem is that in order for this to work you need to pass down the TraceImpl object into the m(Anchor) no?

Maybe there is some alternative approach where we can intercept navigation attempts and re-route them to the specific TraceImpl?
I need to think more loud in a room about this.

RAF Scheduler

Yes this needs to stay global. AnimationFrame scheduling is necessarily global.
We can/should just have the ability to register more than one mount points.
And yes every m.refresh() will have global impact, and that's okay.

[cdamus]

Thanks @stevegolton this proposal largely aligns with the current implementation in my fork of the Perfetto repository of support for embedding and multiple open traces. I have some specific comments to offer in-line, below.

This separation actually somewhat exists right now with frontend/index.ts + common.scss being the standalone part, and the rest of the code being the library. The separation however is not perfect. The core of the app definitely directly accesses a lot of DOM and browser APIs but the general outline is already there, we just need to lean into this architecture a little more.

Yes, I think one of the principal architectural points currently is the small number of global singletons that various far-flung bits of code reach out to. I'm thinking especially of the AppImpl, the Router and its static methods, and the HttpRpcEngine (really only the static TCP port to connect to). The trace converter and other webworkers don't seem like they would likely figure into an embedding application (they don't in mine, though its does use the WASM trace processor), the HttpRpcEngine is easily dealt with, the Router could be injected into components that need it, and as discussed in this document the AppImpl can remain a singleton if it is separated from the trace(s). At least, that has not presented any difficulties for my embedding application. I suppose even the Router could be published by the AppImpl, then its API could be non-static.

If we imported the current frontend bundle directly, we would end up importing all of the frontend/index.ts code as well which would immediately run on startup, which is not what we want. Ideally we should have two builds - one for the library that doesn't run anything and simply exports the classes and functions required by the embedding application.

A separate embedder build would be very helpful. That can also then help embedders to integrate the CSS stylesheet in the most efficient way for them.

This raises the question of some other assets such as the stdlib_docs.json file required by the SQL modules plug-in. For the most part my application's own packaging scripts have had no difficultly sorting these out and picking out only what it needs. So not sure whether this proposal needs to consider these assets.

Shared app vs separate apps

If we can have multiple instances of Perfetto in a single page, this raises the question of whether we have one app or many?

Shared 'App' (Preferred)

...

Cons:

• All instances of the UI share the same app state settings (not trace state, as
  this is stored in the trace object).

I don't imagine that it would make sense for many applications to have different configurations for multiple AppImpls, for example different plug-ins activated or different feature flags enabled. It certainly doesn't make sense for mine. So this isn't much of a "con" ;-)

• The app can no longer contain a reference to the trace e.g. app.trace,
  because one app can now be used with many traces. We would need to invert the
  dependencies, and also separate the shared registries such as commands,
  sidebar entries, and pages so that the trace object has its own set of
  registries.

In theory the AppImpl could hold the complete set of loaded traces (make them available for perusal) and could track an "active" trace as the one that the user is currently engaged with. This is what the fork of Perfetto UI in my application does. In general, I would anticipate that in any embedding application there will be a singular "input focus" and whatever trace was last implicated by the input focus could be the "active" trace. And an application for which this doesn't make sense could simply never "activate" a trace in the AppImpl. But then that would have consequences for any component or plug-in that expects the AppImpl to be able to provide a trace for it to act on. But it's already the case that the AppImpl may not have a trace if none has yet been loaded in the session. Moreover, UI components requiring a trace have already been refactored to inject the trace into them (that was merged in August 2025)

Multi-trace Tenancy

Given that we have one app and many traces, we must remove any state from any given trace from the app.

As mentioned above, there could be the half-way position of maintaining an "active" trace, but I can understand that this may be deprecated. If for no other reason than it may become too easy to rely on it as the "one true trace" as in olden times.

App-scoped Entities

Right now, the app stores a reference to the currently loaded trace. This is useful for app-registered entities (e.g. commands) as they can simply call app.trace to look up which trace they're working on.

...

In order to do this, we must now inject the trace into the command's callback via some attribute. This trace object must originate from the calling context.

I don't understand what is the advantage of parameterizing a Command with a trace provided by the caller versus requiring the Command to be registered in the context (CommandManager) of the Trace and not of the AppImpl.

Commands are contributed by plug-ins, which instances are already scoped to a trace. So would it not be feasible to require them to register commands that operate on a trace in the context of the trace and not the AppImpl? I half expect that plug-ins are doing this already.

Trace Management

Right now, plugins et al can simply open a trace by calling openTrace on the app, however in this new model we are taking the stance that the currently loaded trace is controlled by the embedder and injected into the UI. However, it can still be useful to allow plugins to be able to ask the embedder to open a trace from within a plugin etc.

This raises an interesting question. Perfetto UI has long provided a mechanism by which to suppress the sidebar (the "embedded mode"). Would it be necessary/useful to provide some API by which plug-ins can learn that extension points they would contribute to, such as the sidebar, are not in play, so they would simply not offer those contributions? Or would do something else?

Would it make sense to allow embedder applications to replace the omnibox altogether? For example, my application is implemented on a framework that itself provides a command palette after the VS Code fashion, with commands covering a much wider scope (obviously) than a loaded Perfetto trace. This function of the omnibox is duplicative in my application, and even the other use cases such of ad hoc SQL queries and text input would be straight-forward to implement in my application's palette ... if I could hook into Perfetto UI's omnibox manager to delegate the UI.

Trace loading statuses

When loading a trace load_trace.ts currently calls into the app to set the omnibox text when the trace is loading in order to provide feedback to the user about the trace loading process - now this state needs to be stored in the individual trace object that's doing the loading. This way, the UiMain object that's looking at the trace object can just glean the status from that instead.

Ideally any "progress activity" incurred by a trace could be reported via a pluggable interface to the host application, to manifest it in its own UI (status bar, progress toast, etc.). Some kind of ProgressMonitor interface, very loosely sketched:

> // Initialize a common, global app - this function must be called first.
> AppImpl.initialize({
    progressMonitor: {
        onActivityStarted(activity: { id: unknown; title: string; description?: string; totalWork?: number ) { /* */ },
        onActivityProgress(progress: { activityId: unknown; task?: string; work?: number ) { /* */ },
        onActivityDone(status: { activityId: unknown; success?: true; error?: any} ) { /* */ },
    },
    // ... other embedder hooks ...
});

Anchors

Anchors that change the hash route are now just never going to work as they will change the embedder's route. This could be quite complex. We could try and leave the anchors in place and override them in embedders, though that goes against the rest of the ethos in this doc of doing nothing by default.

If the Anchor component had the contextual Trace injected into it as so many other UI components do, it would be able to access the trace's Router (as configured by the embedding application) from that.

RAF Scheduler

While it would be nice to isolate refreshes to only the UI instance that needs it - the most practical solution to dealing with the raf would be to just keep it as a global object. Indeed the 'm' (mithril object) is global anyway, so we'd have the same problem if we were to use m.mount() rather than raf.mount().

The ramifications of this mean that if one UI instance triggers an update, then all UI instances will refresh, but that's a reasonable tradeoff for the complexity that attempting to separate them would involve.

This consequence has not been an issue for my application at all, if it helps to know that. It makes perfect sense that there should be only a single RafScheduler to manage the browser's single series of animation frames.

However, in an application that presents multiple open traces (such as mine) it is natural to expect that these might be implemented in some sort of tabbed/paged interface within the browser such that some open timelines are actually hidden from view. These, then, would not need to redraw until they are next shown. Ideally the RafScheduler could know that some mounts are dormant in this way and skip them in the redraw, keeping their redraw requests deferred until those mounts are shown.

Risks

• Some of these design decisions will involve an ongoing cost to maintain,
  essentially making sure that all new code doesn't assume that the standalone
  application is the only deployment context. This will introduce an additional
  review burden.
• There is guaranteed to be additional issues and roadblocks that haven't been
  addressed in this document.
• Designing for the UI to be purposely used as a library exposes an API surface
  that is difficult to change in the future. Is this something we want to agree
  to and maintain going forward? There will be some additional overhead to test
  for regressions?

All good points. Even if the outcome of this process is not a formal API and long-term commitment to compatibility with the embedded scenario, it can bring about architectural changes that will make it feasible for forks to maintain for themselves the integration hooks that make it work. As it stands, a fork must make some rather deep changes in code that sees continual churn, making on-going synchronization from upstream Perfetto repository difficult. Of course, the best case is a Perfetto UI that I can just drop into my app, configure, and go :-)

Having seen for myself, in a project that has been embedding Perfetto UI since about March 2023, how much the architecture has evolved and crystallized since then already to bring us much closer a fully functional integration, I am hopeful that there is not so much further to go!