feat: split decorator architecture and add universal entry points by mattcosta7 · Pull Request #41 · github/storybook-addon-performance-panel

mattcosta7 · 2026-02-22T21:51:56Z

Summary

Split the single React-only withPerformanceMonitor decorator into a two-layer architecture, enabling framework-agnostic performance monitoring.

What changed

Core extraction (`core/preview-core.ts`)

New PerformanceMonitorCore class that encapsulates all browser-level metric collection:

Frame timing, CLS, long tasks, input latency, memory, DOM mutation tracking
Channel event wiring (metrics emission, reset, inspect element)
Container observation via MutationObserver

Decorator split

decorators/universal.ts — Framework-agnostic decorator using PerformanceMonitorCore directly (no React dependency). Observes #storybook-root container.

decorators/react.tsx — React.Profiler bridge that layers on top for React-specific render profiling.

preview.ts — Two-decorator stack: [withPerformanceMonitor, withReactProfiler]

New entry points

Entry	Purpose
`index-universal.ts`	Universal (non-React) public API
`index-react.ts`	React-specific API with Profiler support
`preset-universal.ts`	Storybook preset for non-React frameworks
`preview-universal.ts`	Preview with universal decorator only

Other changes

react/performance-decorator.tsx — Simplified to use PerformanceMonitorCore
performance-panel.tsx — refId keying for composed storybook isolation
package.json — New subpath exports: ./universal, ./react, ./components
index.ts — Updated to type-only exports (public API moved to index-react.ts)
New test suite: performance-decorator-universal.browser.test.ts (11 tests x 3 browsers)

Testing

51 test files, 738 assertions passing (all browsers)
Build clean (attw + publint)
ESLint clean

Depends on

Restructure: docs site, examples storybook, addon file reorganization #39 (restructure branch)

Extract PerformanceMonitorCore from the React-specific decorator into a shared core (core/preview-core.ts) that can be used by any framework. Decorator split: - decorators/universal.ts: framework-agnostic decorator using PerformanceMonitorCore directly (browser-level metrics) - decorators/react.tsx: React.Profiler bridge that layers on top for React-specific render profiling - preview.ts: two-decorator stack [withPerformanceMonitor, withReactProfiler] New entry points: - index-universal.ts: universal (non-React) public API - index-react.ts: React-specific public API with Profiler support - preset-universal.ts: Storybook preset for non-React frameworks - preview-universal.ts: preview with universal decorator only - react/performance-decorator.tsx simplified to use PerformanceMonitorCore - performance-panel.tsx: refId keying for composed storybook isolation - package.json: new subpath exports (./universal, ./react, ./components) - New test suite for universal decorator

- Add packages/examples-html with Counter, LayoutThrashing, and WebComponent stories demonstrating the universal (non-React) addon - Update docs site: introduction, setup, collectors, metrics pages with HTML/universal usage details - Update storybook-config with HTML storybook sidebar links - Update CI workflow to build HTML storybook - Add root package.json scripts for HTML examples - Add universal-split changeset (minor)

Rajdeepc · 2026-02-23T09:34:28Z

@mattcosta7 This is exactly the architecture we were hoping for. We integrated the addon into Spectrum Web Components (Storybook 10 + @storybook/web-components-vite) and had to write a ~600-line custom decorator to bridge the gap -- a WebComponentMetricsCollector class that reimplements the browser-level metric collection and channel communication, loaded alongside the /preset entry point to avoid the React decorator.
The core/adapter split here maps cleanly to what we ended up building manually.

One suggestion: It would be helpful if the metrics schema gracefully handled missing groups -- e.g., if the universal decorator doesn't emit React Profiler fields, the panel could hide that section entirely rather than requiring them to be present as zeroes. That way framework-specific adapters don't need to be aware of each other's fields.
Happy to validate the universal entry points against our setup once this is ready for testing. We'd adopt it immediately.

Rajdeepc

This is the right architecture and liked the direction. Let me know if you want to collaborate to get this in. Would be very helpful for non-React projects.

Rajdeepc · 2026-02-23T09:37:52Z

+    const createdCore = core
+    requestAnimationFrame(() => {
+      if (getActiveCore() !== createdCore) return
+
+      const root = document.getElementById('storybook-root')
+      if (root) {
+        createdCore.observeContainer(root)
+      }


The stale-core guard is good, but if the story renders but #storybook-root hasn't been populated yet (e.g., async rendering frameworks), root will be null and container observation silently fails. Can you possible add a retry with MutationObserver on document.body or requestAnimationFrame loop (with a bounded retry count) to catch late-mounting roots. This matters for frameworks like Vue/Svelte that may mount asynchronously.

yes! I added a mutation observer for this here: 0b64f49

Rajdeepc · 2026-02-23T09:38:12Z

+  return dirname(fileURLToPath(import.meta.url))
+}
+
+export function managerEntries(entry: string[] = []): string[] {


No preview entries? The panel UI will be shown but decorator won't be auto a-pplied. We have to manually add withperformanceMonitor in preview.ts. React presets auto-applies both. Can you consider adding a previewAnnotation export to preset-universal.ts that points to preview-universal.ts for parity.

I believe (and could be wrong on the ideal state)

When we declare exports in package.json like https://github.com/github/storybook-addon-performance-panel/pull/41/changes#diff-3896b9c4823a797986b71e274747e4f96dfa597fb4aa8519ef99c253718289d4R45-R48 storybook add /preview entry via autodiscovery to the addon path in main.ts and resolves via the the decorator which handles the auto-loading behavior

Adding previewAnnotations() on top of that causes a duplicate symbol crash:

Identifier 'preview_universal_11416' has already been declared

The bundler sees two resolution paths to the same module (one absolute path from previewAnnotations, one package export from auto-discovery) and can't deduplicate them.

The React preset works the same way — [managerEntries()] only, no previewAnnotations(). Both rely on auto-discovery via the exports map

I believe that should work for each case?

I have 2 storybooks building now react and html in the pages deployment on the pr

universal

react

as well as some updated docs here

https://github-763cfd1909-71141468.drafts.github.io/

Rajdeepc · 2026-02-23T09:41:16Z

+    })
+  }
+
+  return storyFn() as unknown


This looses type safety. Can you consider using a generic parameter `Decorator to get proper typing without the cast?

Yep! I think this was just to silence an eslint warning, we can disable instead - storyFn() returns any since it's framework specified - but safety wise disabling seems more correct than an unknown cast - so done!

mattcosta7 · 2026-02-23T15:23:41Z

The core/adapter split here maps cleanly to what we ended up building manually.

Awesome! glad this is shaping up to fit nicely for you!

One suggestion: It would be helpful if the metrics schema gracefully handled missing groups -- e.g., if the universal decorator doesn't emit React Profiler fields, the panel could hide that section entirely rather than requiring them to be present as zeroes. That way framework-specific adapters don't need to be aware of each other's fields.
Happy to validate the universal entry points against our setup once this is ready for testing. We'd adopt it immediately.

Agreed! In the current 'universal' setup we avoid listing the react specific fields for this reason! I think we can provide better wrappers in the future for more frameworks specific tools (and integration points for adding them when necessary) in this architecture.

Let me know if you want to collaborate to get this in. Would be very helpful for non-React projects.

yes, definitely. I'll try to publish a canary version so we can test it out! Happy to take PRs onto this branch as well, or guidance as we make this a bit more useful outside of react!

github-actions · 2026-02-23T15:50:12Z

📦 Canary Release

Package	Version
`@github-ui/storybook-addon-performance-panel`	`1.0.1-canary.d6c4f43`

npm install @github-ui/storybook-addon-performance-panel@1.0.1-canary.d6c4f43

Published from 9f574eb

mattcosta7 · 2026-02-23T15:50:38Z

📦 Canary Release

Package Version
@github-ui/storybook-addon-performance-panel 1.0.1-canary.e4e58ab
npm install @github-ui/storybook-addon-performance-panel@1.0.1-canary.e4e58ab
Published from 64bce0d

@Rajdeepc - let me know how this canary looks for y'all!

Copilot

Pull request overview

This PR introduces framework-agnostic performance monitoring by splitting the React-only decorator into a two-layer architecture with universal browser-level metrics collection and optional React profiling.

Changes:

Extracted core performance monitoring into a framework-agnostic PerformanceMonitorCore class
Split decorators into universal (browser metrics) and React-specific (Profiler) layers
Added new entry points (./universal, ./react, ./components) for different framework support

Reviewed changes

Copilot reviewed 39 out of 41 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`packages/storybook-addon-performance-panel/core/preview-core.ts`	New core class extracting browser-level metrics collection from React decorator
`packages/storybook-addon-performance-panel/decorators/universal.ts`	Framework-agnostic decorator using PerformanceMonitorCore directly
`packages/storybook-addon-performance-panel/decorators/react.tsx`	React.Profiler bridge wrapping stories with profiler integration
`packages/storybook-addon-performance-panel/preview.ts`	Updated to use decorator stack: universal + React profiler
`packages/storybook-addon-performance-panel/performance-panel.tsx`	Added hasReactProfiler state and conditional rendering for React section
`packages/storybook-addon-performance-panel/package.json`	New subpath exports for universal, react, and components entries
`packages/storybook-addon-performance-panel/index-universal.ts`	Universal-only public API entry point
`packages/storybook-addon-performance-panel/index-react.ts`	React-specific component exports
`packages/examples-html/`	New HTML docs storybook demonstrating universal entry usage
`packages/website/app/content/`	Documentation updates for universal entry point

Comments suppressed due to low confidence (2)

packages/storybook-addon-performance-panel/tsconfig.json:1

The removal of the exclude array may cause TypeScript to include the dist directory in compilation. If dist is auto-generated during the build process, this could lead to compilation errors or slower type-checking. Consider re-adding \"exclude\": [\"dist\"] to prevent these issues.
packages/storybook-addon-performance-panel/react/performance-decorator.tsx:1
The return value of observeContainer() is not being stored or returned from the useLayoutEffect. According to the core implementation, observeContainer() returns a cleanup function that should be returned from the effect to properly disconnect the observer when the component unmounts or dependencies change.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-23T15:52:00Z

 export default start

-// Public API for manual per-story usage
+// Public API for manual per-story usage (framework-agnostic)


The comment states this is "framework-agnostic" but the file exports withPerformanceMonitor from the universal decorator while the default preview still uses both decorators (universal + React). This may confuse users about which exports are truly framework-agnostic. Consider clarifying that this public API is universal-only while the preset/preview includes React support.

Suggested change

// Public API for manual per-story usage (framework-agnostic)

// Public API for manual per-story usage using universal, framework-agnostic decorators.

// Framework-specific integrations (e.g. React) are provided via the preset/preview exports.

Copilot · 2026-02-23T15:52:01Z

+  storyId: string
+  children: React.ReactNode
+}) {
+  const profilerId = `Story(${storyId})`


The profiler ID format Story(${storyId}) is inconsistent with the pattern used elsewhere in the codebase. The React collector and previous implementation don't show this exact format being used. Verify this ID matches what the CollectorManager expects for profiler tracking.

Suggested change

const profilerId = `Story(${storyId})`

const profilerId = storyId

Copilot · 2026-02-23T15:52:01Z

      return {
        ...state,
+        // Reset hasReactProfiler on story change — it will be set again if a PROFILER_UPDATE arrives
+        hasReactProfiler: currentProfilers ? state.hasReactProfiler : false,


The logic for resetting hasReactProfiler on story change is flawed. It checks if currentProfilers exists (truthy), but should check if the current story has profilers. If switching from a story with profilers to one without, currentProfilers could still be truthy (containing the old story's profilers), causing hasReactProfiler to remain true incorrectly. Should be: hasReactProfiler: currentProfilers && currentProfilers.length > 0 ? state.hasReactProfiler : false

Suggested change

hasReactProfiler: currentProfilers ? state.hasReactProfiler : false,

hasReactProfiler: currentProfilers && currentProfilers.length > 0 ? state.hasReactProfiler : false,

Copilot · 2026-02-23T15:52:01Z

+// ============================================================================
+
+/** Maximum time (ms) to wait for #storybook-root to appear in the DOM. */
+const ROOT_DISCOVERY_TIMEOUT_MS = 5_000


A 5-second timeout for root discovery is excessive for most use cases. Even slow-mounting frameworks typically render within 1-2 seconds. This creates a potential 5-second observer leak if the root never appears. Consider reducing to 2000ms (2 seconds) to balance async framework support with resource cleanup.

Suggested change

const ROOT_DISCOVERY_TIMEOUT_MS = 5_000

const ROOT_DISCOVERY_TIMEOUT_MS = 2_000

Rajdeepc · 2026-02-24T11:14:08Z

📦 Canary Release

Package Version
@github-ui/storybook-addon-performance-panel 1.0.1-canary.e4e58ab
npm install @github-ui/storybook-addon-performance-panel@1.0.1-canary.e4e58ab
Published from 64bce0d
@Rajdeepc - let me know how this canary looks for y'all!

Hi @mattcosta7 this looks good from my side. I’ve enabled it in our core setup and it’s working well.

As we roll it out more broadly, I’ll keep an eye out for any additional extension points or gaps and follow up with concrete suggestions if needed.

When you’re ready to cut a major release, it would be great to share this more widely with the community as well — I think there’s real value here beyond just our use case.

Copilot

Pull request overview

Copilot reviewed 39 out of 41 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-24T14:56:36Z

+  observeContainer(element: HTMLElement): void {
+    this.containerCleanup?.()
+    this.containerCleanup = this.manager.observeContainer(element)


The observeContainer method receives a cleanup function from this.manager.observeContainer() but doesn't return it. This prevents callers (like the React decorator's useLayoutEffect) from properly cleaning up the MutationObserver when the effect re-runs or the component unmounts. Change the return type from void to () => void and return the cleanup function.

Suggested change

observeContainer(element: HTMLElement): void {

this.containerCleanup?.()

this.containerCleanup = this.manager.observeContainer(element)

observeContainer(element: HTMLElement): () => void {

this.containerCleanup?.()

const cleanup = this.manager.observeContainer(element)

this.containerCleanup = cleanup

return cleanup

Copilot · 2026-02-24T14:56:37Z

  useLayoutEffect(() => {
-    const manager = managerRef.current
-    if (!enabled || !contentRef.current || !manager) return
-    return manager.observeContainer(contentRef.current)
+    const core = coreRef.current
+    if (!enabled || !contentRef.current || !core) return
+    core.observeContainer(contentRef.current)
  }, [enabled])


The observeContainer method returns a cleanup function, but it's not being returned from the useLayoutEffect. This will prevent proper cleanup when the effect re-runs or when the component unmounts. The cleanup function should be returned to ensure the MutationObserver is properly disconnected.

@copilot open a new pull request to apply changes based on this feedback

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot · 2026-02-24T15:19:20Z

@mattcosta7 I've opened a new pull request, #52, to work on those changes. Once the pull request is ready, I'll request review from you.

…ator Co-authored-by: mattcosta7 <8616962+mattcosta7@users.noreply.github.com>

Fix missing MutationObserver cleanup in useLayoutEffect

mattcosta7 · 2026-02-24T21:14:39Z

📦 Canary Release

Package Version
@github-ui/storybook-addon-performance-panel 1.0.1-canary.e4e58ab
npm install @github-ui/storybook-addon-performance-panel@1.0.1-canary.e4e58ab
Published from 64bce0d
@Rajdeepc - let me know how this canary looks for y'all!
Hi @mattcosta7 this looks good from my side. I’ve enabled it in our core setup and it’s working well.

As we roll it out more broadly, I’ll keep an eye out for any additional extension points or gaps and follow up with concrete suggestions if needed.

When you’re ready to cut a major release, it would be great to share this more widely with the community as well — I think there’s real value here beyond just our use case.

@Rajdeepc 1.1.0 is cut now that has this in it

We'll take a look at improving the setup to allow for extensible decorators / metrics panels per framework (happy to take PRs on that too)!

When you’re ready to cut a major release, it would be great to share this more widely with the community as well

yes! We'll be trying to share it more and happy to see it used more broadly! Definitely keep us in the loop with your usage and value you find, as well as any gaps!

mattcosta7 temporarily deployed to github-pages-preview February 22, 2026 21:52 — with GitHub Actions Inactive

mattcosta7 temporarily deployed to github-pages-preview February 22, 2026 21:57 — with GitHub Actions Inactive

mattcosta7 temporarily deployed to github-pages-preview February 22, 2026 21:59 — with GitHub Actions Inactive

mattcosta7 self-assigned this Feb 22, 2026

mattcosta7 temporarily deployed to github-pages-preview February 22, 2026 22:01 — with GitHub Actions Inactive

mattcosta7 added 3 commits February 22, 2026 22:12

Add Universal Storybook cross-link to React storybook sidebar

af41249

mattcosta7 force-pushed the universal-split branch from 97bb487 to af41249 Compare February 22, 2026 22:13

mattcosta7 temporarily deployed to github-pages-preview February 22, 2026 22:15 — with GitHub Actions Inactive

mattcosta7 mentioned this pull request Feb 22, 2026

More examples #35

Merged

fix: restore portless dep, revert layout.module.css style change

5140282

mattcosta7 temporarily deployed to github-pages-preview February 22, 2026 22:36 — with GitHub Actions Inactive

Merge branch 'main' into universal-split

8254107

mattcosta7 temporarily deployed to github-pages-preview February 22, 2026 22:39 — with GitHub Actions Inactive

Merge branch 'main' into universal-split

c517954

mattcosta7 temporarily deployed to github-pages-preview February 23, 2026 04:24 — with GitHub Actions Inactive

Rajdeepc mentioned this pull request Feb 23, 2026

Support non-React Storybook frameworks (Web Components, Lit, Vue, etc.) #48

Open

Rajdeepc reviewed Feb 23, 2026

View reviewed changes

Rajdeepc mentioned this pull request Feb 23, 2026

chore: performance storybook addon for 2nd gen adobe/spectrum-web-components#6042

Merged

17 tasks

Merge branch 'main' into universal-split

0e25515

mattcosta7 temporarily deployed to github-pages-preview February 23, 2026 14:15 — with GitHub Actions Inactive

mattcosta7 added 2 commits February 23, 2026 14:55

respond to some pr comments

0b64f49

fix auto-discovery duplication

4ae4209

mattcosta7 temporarily deployed to github-pages-preview February 23, 2026 15:07 — with GitHub Actions Inactive

Merge branch 'main' into universal-split

e4e58ab

mattcosta7 temporarily deployed to github-pages-preview February 23, 2026 15:46 — with GitHub Actions Inactive

mattcosta7 added the canary label Feb 23, 2026

mattcosta7 requested a review from a team as a code owner February 23, 2026 15:49

Copilot AI review requested due to automatic review settings February 23, 2026 15:49

mattcosta7 temporarily deployed to production February 23, 2026 15:49 — with GitHub Actions Inactive

Copilot started reviewing on behalf of mattcosta7 February 23, 2026 15:49

View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

mattcosta7 requested a review from Copilot February 24, 2026 14:49

Copilot started reviewing on behalf of mattcosta7 February 24, 2026 14:50

View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

Update packages/storybook-addon-performance-panel/package.json

3e82ebb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

mattcosta7 had a problem deploying to production February 24, 2026 15:09 — with GitHub Actions Error

Update packages/examples-html/stories/LayoutThrashing.stories.ts

4be2daf

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

mattcosta7 temporarily deployed to production February 24, 2026 15:10 — with GitHub Actions Inactive

mattcosta7 temporarily deployed to github-pages-preview February 24, 2026 15:12 — with GitHub Actions Inactive

Initial plan

311d826

Copilot AI mentioned this pull request Feb 24, 2026

Fix missing MutationObserver cleanup in useLayoutEffect #52

Merged

Copilot AI and others added 2 commits February 24, 2026 15:22

Fix useLayoutEffect cleanup for MutationObserver in performance-decor…

557fe8e

…ator Co-authored-by: mattcosta7 <8616962+mattcosta7@users.noreply.github.com>

Merge pull request #52 from github/copilot/sub-pr-41

d6c4f43

Fix missing MutationObserver cleanup in useLayoutEffect

mattcosta7 temporarily deployed to production February 24, 2026 16:02 — with GitHub Actions Inactive

mattcosta7 temporarily deployed to github-pages-preview February 24, 2026 16:04 — with GitHub Actions Inactive

mattcosta7 removed the canary label Feb 24, 2026

Merge branch 'main' into universal-split

c0abaed

mattcosta7 deployed to github-pages-preview February 24, 2026 17:28 — with GitHub Actions

View deployment

mattcosta7 merged commit 7cb624f into main Feb 24, 2026
14 checks passed

mattcosta7 deleted the universal-split branch February 24, 2026 17:31

github-actions Bot mentioned this pull request Feb 24, 2026

chore: version packages #40

Merged

	// Public API for manual per-story usage (framework-agnostic)
	// Public API for manual per-story usage using universal, framework-agnostic decorators.
	// Framework-specific integrations (e.g. React) are provided via the preset/preview exports.

	const profilerId = `Story(${storyId})`
	const profilerId = storyId

	hasReactProfiler: currentProfilers ? state.hasReactProfiler : false,
	hasReactProfiler: currentProfilers && currentProfilers.length > 0 ? state.hasReactProfiler : false,

	const ROOT_DISCOVERY_TIMEOUT_MS = 5_000
	const ROOT_DISCOVERY_TIMEOUT_MS = 2_000

Conversation

mattcosta7 commented Feb 22, 2026

Summary

What changed

Core extraction (core/preview-core.ts)

Decorator split

New entry points

Other changes

Testing

Depends on

Uh oh!

Rajdeepc commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Rajdeepc left a comment

Choose a reason for hiding this comment

Uh oh!

Rajdeepc Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

mattcosta7 Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Rajdeepc Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

mattcosta7 Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Rajdeepc Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

mattcosta7 Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

mattcosta7 commented Feb 23, 2026

Uh oh!

github-actions Bot commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Canary Release

Uh oh!

mattcosta7 commented Feb 23, 2026

📦 Canary Release

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Rajdeepc commented Feb 24, 2026

📦 Canary Release

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

mattcosta7 Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Core extraction (`core/preview-core.ts`)

Rajdeepc commented Feb 23, 2026 •

edited

Loading

github-actions Bot commented Feb 23, 2026 •

edited

Loading

mattcosta7 commented Feb 24, 2026 •

edited

Loading