Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(toolbar): explain extension tools on hover and caption each tool (#123749)

Rafael Audibert55eee2f31fab
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index c68eac1f0349..46312c45fd11 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -16878,6 +16878,42 @@ snapshots:
hash: v1.k794b7964.70e51d3fec2423e3f206a1f632545c683aa8f8a735cc0821c341f7cee593c6a0.cw2jI_P0--u-15-_tVum1o2kaUNfzGnK4o26sfpDfgs
scenes-other-toolbar--web-vitals-dark--light:
hash: v1.k794b7964.3c566aecd79bbe202c1bcf6af7b246d76e554f0730c62b4dff4bad3108dec363.C7lmKRFw4Yayu7T32zX6UwODbv2qqfLYPQHhM8-vzVU
+ scenes-other-toolbar-extension--actions--dark:
+ hash: v1.k794b7964.47c97a9638417b1f05291ee7c26258e29f0538b7aa9b240ca9a42124e4f69031.ipAMvyWBifJCU7w2cHpwNexJ16akcTr2n-T9q8rqF8E
+ scenes-other-toolbar-extension--actions--light:
+ hash: v1.k794b7964.1f668e8bc1678e763755c0f5fa57095fed97bff884c43269db70606fbd72e6e2.-Jabtw4BHGCfRtzWC0si_6PLzG4i485L3C9rG4-DCjE
+ scenes-other-toolbar-extension--events--dark:
+ hash: v1.k794b7964.6951e40266854f9186ecd9e129694a71a4cd2b8292434a19adb320e4d939ef79.UqE6cLf5i95heKK0ueDxFmZtoIunyKj2asiFeRy-BzA
+ scenes-other-toolbar-extension--events--light:
+ hash: v1.k794b7964.5aab0502ebffb4e3aaccd7068180c126f99e10168611932d0c96fd0f7574a247.aeeY5VObbfHz3EbIYneGxHRmx0fHoHKbrFFyB_JU3PY
+ scenes-other-toolbar-extension--experiments--dark:
+ hash: v1.k794b7964.b00d3139e5a2ba88542fbef3797a72de6808e6ded3faa667a7c873a3e8ce8d26.byvlPPPXZNZ6GpC3DM94D4vrWKlOZDnhBluUSmZBZqw
+ scenes-other-toolbar-extension--experiments--light:
+ hash: v1.k794b7964.e3115faf60178e70f22fd5b94f08714a513b660762bf3101f2a8f77ddc760d94.-SbW7x9Bz73JOswYlwvgx4vkamQtdx3Cxzgq8ZWPHkw
+ scenes-other-toolbar-extension--feature-flags--dark:
+ hash: v1.k794b7964.cbed94c6ab2310c5981ae51f686b4e72e2f089a6b0f241781b7f501e698b3e49.HpMZUPuzhYkRGMyh4ACxT9Yxtl1Pxv_O5rR4C9tnyBc
+ scenes-other-toolbar-extension--feature-flags--light:
+ hash: v1.k794b7964.6d3760a66d6dd9016bc0479ecb0e32d1910acbc1997df7772c9255223ae27a34.YMqjcAbIJSwc0YHOPlZHqMq4T9yNbeP4Ujb6isEJrP4
+ scenes-other-toolbar-extension--heatmap--dark:
+ hash: v1.k794b7964.9e90ae389acba7acc5c8feec155491b537ba3baaa347eb0b5330ffb12499d4fb.VUffPogQJoMuKDMRtEnuNNJGtmtcbFY9djuyg2QUMv4
+ scenes-other-toolbar-extension--heatmap--light:
+ hash: v1.k794b7964.c208dda39564a36ae2df7160c95fc2d1c678c837f116c476e8c280aa21cead7b.a7tgkHiw-B6z6B5GtiU5xJA6ShzG5BtGcJohH-Efbf4
+ scenes-other-toolbar-extension--home--dark:
+ hash: v1.k794b7964.83bb52fa616a926259ed466d52ee44bfbb076e41e486aaa2101b88fcf1073fa9.KVpR75JkFzZxvH4RezINchlhG83HTJVnDh8KuYP45y0
+ scenes-other-toolbar-extension--home--light:
+ hash: v1.k794b7964.5aaf3bfe058525aab8bf9cee279529a387a8320bcb49442903c219ab56bc6708.Gl3k1xR9fmum6gj8kwBk80HsbmOcCRgx8khaN3aqjHg
+ scenes-other-toolbar-extension--inspect--dark:
+ hash: v1.k794b7964.f523aa26fdd35a0f804300387caaef4f6bb3afe031dbfab0ca3f59f081e8b841.fl-FLu4PPNA0mXO3E0ooB38y1JGyUKJSARFXQr5loHE
+ scenes-other-toolbar-extension--inspect--light:
+ hash: v1.k794b7964.9080f397105a58badfbedf57fd0d9431a1199168d322be392526f54908389332.ezL_ylAVnS0jm43jSNudSvDq2UsrHLCXe3TasTwzqqw
+ scenes-other-toolbar-extension--more--dark:
+ hash: v1.k794b7964.7fc0cdc145f2aafdb6e85bddbdd1da8c03833df98d07a84a9ad2ea19853da2b9.miuZD5EGMeFPM-ZZW0T20YDVJURjse-35EFK1dlV8tI
+ scenes-other-toolbar-extension--more--light:
+ hash: v1.k794b7964.4390e6d302ece40cc0434daeb0a348820fd0320928562977b3d92e2d26e7ffdf.eQWNMIp7D-sclUMAkcncr7MkVFLQkZLDnMPH60jFvvM
+ scenes-other-toolbar-extension--web-vitals--dark:
+ hash: v1.k794b7964.d11f7d8f53eb47cb215236d5f3e5575b7f927c9ccc86d69ef332bd0d32a92b78.nLsLJd4XpYfs9nmWheR8f4FRfOGynhwT06OtMbAN8gk
+ scenes-other-toolbar-extension--web-vitals--light:
+ hash: v1.k794b7964.359b0bb9673b02483ba075c403627a50b464f8ab5dacbedf55edc3d62a340721.N5zZFfSviHABKxfqoSFeY-qOhODsfCFqxL3_TPEZwE0
scenes-other-toolbarlaunch--default--dark:
hash: v1.k794b7964.e40308bf4cd225c11272879842feec6c42e817868081bc9e38ac7395dc37a2fd.0UqNVZGTldUPnS_tl6Auj2I_LjYTRPYffIPGWzA6-mc
scenes-other-toolbarlaunch--default--light:
diff --git a/frontend/src/lib/lemon-ui/LemonSegmentedButton/LemonSegmentedButton.tsx b/frontend/src/lib/lemon-ui/LemonSegmentedButton/LemonSegmentedButton.tsx
index b81de2c60bf7..cfabf6bd0f96 100644
--- a/frontend/src/lib/lemon-ui/LemonSegmentedButton/LemonSegmentedButton.tsx
+++ b/frontend/src/lib/lemon-ui/LemonSegmentedButton/LemonSegmentedButton.tsx
@@ -21,6 +21,10 @@ export type LemonSegmentedButtonOption<T extends React.Key> = { value: T } & (
export interface LemonSegmentedButtonProps<T extends React.Key> {
value?: T
onChange?: (newValue: T, e: React.MouseEvent) => void
+ /** Called with the option under the pointer, and with `null` when the pointer leaves the control. */
+ onOptionHover?: (value: T | null) => void
+ /** Called with the option that has keyboard focus, and with `null` when focus leaves the control. */
+ onOptionFocus?: (value: T | null) => void
options: LemonSegmentedButtonOption<T>[]
disabledReason?: string
size?: LemonButtonProps['size']
@@ -37,6 +41,8 @@ interface LemonSegmentedButtonCSSProperties extends React.CSSProperties {
export function LemonSegmentedButton<T extends React.Key>({
value,
onChange,
+ onOptionHover,
+ onOptionFocus,
options,
disabledReason,
size,
@@ -77,7 +83,18 @@ export function LemonSegmentedButton<T extends React.Key>({
)}
/>
)}
- <ul>
+ <ul
+ onMouseLeave={onOptionHover ? () => onOptionHover(null) : undefined}
+ onBlur={
+ onOptionFocus
+ ? (e) => {
+ if (!e.currentTarget.contains(e.relatedTarget)) {
+ onOptionFocus(null)
+ }
+ }
+ : undefined
+ }
+ >
{options.map((option) => {
const optionDisabledReason = option.disabledReason ?? disabledReason
@@ -90,6 +107,8 @@ export function LemonSegmentedButton<T extends React.Key>({
option.value === value && 'LemonSegmentedButton__option--selected'
)}
ref={option.value === value ? selectionRef : undefined}
+ onMouseEnter={onOptionHover ? () => onOptionHover(option.value) : undefined}
+ onFocus={onOptionFocus ? () => onOptionFocus(option.value) : undefined}
>
<LemonButton
type={option.value === value ? 'primary' : 'secondary'}
diff --git a/frontend/src/toolbar/extension/ExtensionFeatureList.tsx b/frontend/src/toolbar/extension/ExtensionFeatureList.tsx
deleted file mode 100644
index ab5a8ffe41f5..000000000000
--- a/frontend/src/toolbar/extension/ExtensionFeatureList.tsx
+++ /dev/null
@@ -1,36 +0,0 @@
-import { useActions } from 'kea'
-
-import { IconExternal } from '@posthog/icons'
-
-import { LemonButton } from 'lib/lemon-ui/LemonButton'
-
-import { PAGE_TOOLS } from './extensionPageTools'
-import { extensionPanelLogic } from './extensionPanelLogic'
-import { usePageToolDisabledReason } from './usePageToolDisabledReason'
-
-export function ExtensionFeatureList({ origin }: { origin: string }): JSX.Element {
- const { openFeature } = useActions(extensionPanelLogic)
- const disabledReason = usePageToolDisabledReason()
-
- return (
- <div className="flex flex-col gap-1">
- <div className="text-secondary text-xs">Open in PostHog for {new URL(origin).host}</div>
- {PAGE_TOOLS.map(({ feature, ...tool }) =>
- feature ? (
- <LemonButton
- key={feature.key}
- fullWidth
- icon={tool.icon}
- sideIcon={<IconExternal />}
- disabledReason={disabledReason({ ...tool, feature })}
- tooltip={`${tool.description}. Opens in PostHog.`}
- onClick={() => openFeature(feature.key, feature.path)}
- data-attr={`toolbar-extension-feature-${feature.key}`}
- >
- {tool.label}
- </LemonButton>
- ) : null
- )}
- </div>
- )
-}
diff --git a/frontend/src/toolbar/extension/ExtensionPageToolbar.tsx b/frontend/src/toolbar/extension/ExtensionPageToolbar.tsx
index ec7ab1808781..85c200c47510 100644
--- a/frontend/src/toolbar/extension/ExtensionPageToolbar.tsx
+++ b/frontend/src/toolbar/extension/ExtensionPageToolbar.tsx
@@ -4,42 +4,35 @@ import { LemonBanner } from 'lib/lemon-ui/LemonBanner'
import { Spinner } from 'lib/lemon-ui/Spinner'
import { extensionAuthLogic } from './extensionAuthLogic'
-import { ExtensionFeatureList } from './ExtensionFeatureList'
import { ExtensionPageToolbarTools } from './ExtensionPageToolbarTools'
-export function ExtensionPageToolbar({ origin }: { origin: string }): JSX.Element {
+export function ExtensionPageToolbar(): JSX.Element {
const { authStatus } = useValues(extensionAuthLogic)
const { authenticate } = useActions(extensionAuthLogic)
if (authStatus === 'authenticated') {
- return <ExtensionPageToolbarTools origin={origin} />
+ return <ExtensionPageToolbarTools />
}
if (authStatus === 'signed-out' || authStatus === 'failed') {
return (
- <>
- <LemonBanner
- type={authStatus === 'failed' ? 'warning' : 'info'}
- action={{
- children: 'Connect',
- onClick: () => authenticate(true),
- 'data-attr': 'toolbar-extension-connect',
- }}
- >
- {authStatus === 'failed'
- ? "Couldn't connect the toolbar to this project. Connect again, and finish any step PostHog shows in the new tab."
- : 'Connect the toolbar to this project to use its tools on this page.'}
- </LemonBanner>
- <ExtensionFeatureList origin={origin} />
- </>
+ <LemonBanner
+ type={authStatus === 'failed' ? 'warning' : 'info'}
+ action={{
+ children: 'Connect',
+ onClick: () => authenticate(true),
+ 'data-attr': 'toolbar-extension-connect',
+ }}
+ >
+ {authStatus === 'failed'
+ ? "Couldn't connect the toolbar to this project. Connect again, and finish any step PostHog shows in the new tab."
+ : 'Connect the toolbar to this project to use its tools on this page.'}
+ </LemonBanner>
)
}
return (
- <>
- <div className="flex items-center gap-2 text-secondary text-xs">
- <Spinner />
- Connecting the toolbar to this project…
- </div>
- <ExtensionFeatureList origin={origin} />
- </>
+ <div className="flex items-center gap-2 text-secondary text-xs">
+ <Spinner />
+ Connecting the toolbar to this project…
+ </div>
)
}
diff --git a/frontend/src/toolbar/extension/ExtensionPageToolbarTools.tsx b/frontend/src/toolbar/extension/ExtensionPageToolbarTools.tsx
index d806f369df4b..25f910227ecc 100644
--- a/frontend/src/toolbar/extension/ExtensionPageToolbarTools.tsx
+++ b/frontend/src/toolbar/extension/ExtensionPageToolbarTools.tsx
@@ -1,5 +1,5 @@
import { useActions, useMountedLogic, useValues } from 'kea'
-import { useMemo } from 'react'
+import { useMemo, useState } from 'react'
import { IconExternal, IconX } from '@posthog/icons'
@@ -14,7 +14,6 @@ import { ExtensionActionsList } from './ExtensionActionsList'
import { ExtensionEventsMenu } from './ExtensionEventsMenu'
import { ExtensionExperimentEditor } from './ExtensionExperimentEditor'
import { ExtensionExperimentsList } from './ExtensionExperimentsList'
-import { ExtensionFeatureList } from './ExtensionFeatureList'
import { ExtensionFlagsMenu } from './ExtensionFlagsMenu'
import { ExtensionHeatmapMenu } from './ExtensionHeatmapMenu'
import { ExtensionInspectedElement } from './ExtensionInspectedElement'
@@ -22,6 +21,7 @@ import { ExtensionMoreMenu } from './ExtensionMoreMenu'
import { extensionPageToolbarConnectionLogic } from './extensionPageToolbarConnectionLogic'
import { PAGE_TOOLS, PageToolDefinition, PageToolMode } from './extensionPageTools'
import { extensionPanelLogic } from './extensionPanelLogic'
+import { ExtensionToolHint } from './ExtensionToolHint'
import { ExtensionWebVitalsMenu } from './ExtensionWebVitalsMenu'
import { usePageToolDisabledReason } from './usePageToolDisabledReason'
@@ -33,8 +33,7 @@ function ToolBody({ mode }: { mode: PageToolMode }): JSX.Element {
return (
<>
<div className="text-xs text-secondary">
- Hover an element on the page to see its selector and actions, or click it to keep it selected.
- Press Esc to stop.
+ Click an element to keep it selected. Press Esc to stop.
</div>
<ExtensionInspectedElement />
</>
@@ -62,8 +61,11 @@ function ToolHeader({ tool }: { tool: PageToolDefinition }): JSX.Element {
const { feature } = tool
return (
- <div className="flex items-center gap-1">
- <h3 className="m-0 flex-1 truncate text-sm font-semibold">{tool.label}</h3>
+ <div className="flex items-start gap-1">
+ <div className="flex min-w-0 flex-1 flex-col">
+ <h3 className="m-0 truncate text-sm font-semibold">{tool.label}</h3>
+ <p className="m-0 text-xs text-secondary">{tool.description}</p>
+ </div>
{feature && (
<LemonButton
size="xsmall"
@@ -84,12 +86,15 @@ function ToolHeader({ tool }: { tool: PageToolDefinition }): JSX.Element {
)
}
-export function ExtensionPageToolbarTools({ origin }: { origin: string }): JSX.Element {
+export function ExtensionPageToolbarTools(): JSX.Element {
useMountedLogic(extensionPageToolbarConnectionLogic)
const { mode, connectionStatus, selectorCounter } = useValues(extensionPageToolbarConnectionLogic)
const { setMode, connectPage, requestSelectorCount } = useActions(extensionPageToolbarConnectionLogic)
const disabledReason = usePageToolDisabledReason()
const activeTool = PAGE_TOOLS.find((tool) => tool.mode === mode)
+ const [hoveredMode, setHoveredMode] = useState<PageToolMode | null>(null)
+ const [focusedMode, setFocusedMode] = useState<PageToolMode | null>(null)
+ const hintTool = PAGE_TOOLS.find((tool) => tool.mode === (hoveredMode ?? focusedMode)) ?? null
// The page counts selector matches for every editor in the panel.
const counter = useMemo<SelectorMatchCounter>(
() => ({ count: selectorCounter.count, request: requestSelectorCount }),
@@ -98,16 +103,18 @@ export function ExtensionPageToolbarTools({ origin }: { origin: string }): JSX.E
return (
<SelectorCountContext.Provider value={counter}>
- <div className="flex flex-col gap-2">
+ <div className="flex flex-1 flex-col gap-2">
<LemonSegmentedButton
fullWidth
size="small"
value={activeTool?.mode}
onChange={(toolMode) => setMode(toolMode === mode ? 'none' : toolMode)}
+ onOptionHover={setHoveredMode}
+ onOptionFocus={setFocusedMode}
options={PAGE_TOOLS.map((tool) => ({
value: tool.mode,
icon: tool.icon,
- tooltip: tool.label,
+ tooltip: activeTool ? tool.label : undefined,
disabledReason: disabledReason(tool) ?? undefined,
'data-attr': `toolbar-extension-mode-${tool.mode}`,
}))}
@@ -129,28 +136,7 @@ export function ExtensionPageToolbarTools({ origin }: { origin: string }): JSX.E
<ToolBody mode={activeTool.mode} />
</>
) : (
- <>
- <div className="flex flex-col gap-1">
- {PAGE_TOOLS.map((tool) => (
- <LemonButton
- key={tool.mode}
- fullWidth
- icon={tool.icon}
- disabledReason={disabledReason(tool)}
- onClick={() => setMode(tool.mode)}
- data-attr={`toolbar-extension-open-${tool.mode}`}
- >
- <span className="flex min-w-0 flex-col">
- <span>{tool.label}</span>
- <span className="text-xs font-normal text-secondary whitespace-normal">
- {tool.description}
- </span>
- </span>
- </LemonButton>
- ))}
- </div>
- <ExtensionFeatureList origin={origin} />
- </>
+ <ExtensionToolHint tool={hintTool} />
)}
</div>
</SelectorCountContext.Provider>
diff --git a/frontend/src/toolbar/extension/ExtensionPanel.stories.tsx b/frontend/src/toolbar/extension/ExtensionPanel.stories.tsx
new file mode 100644
index 000000000000..9ef2dd8f25ff
--- /dev/null
+++ b/frontend/src/toolbar/extension/ExtensionPanel.stories.tsx
@@ -0,0 +1,102 @@
+import { MOCK_DEFAULT_USER, MOCK_TEAM_ID } from 'lib/api.mock'
+
+import './__mocks__/fakeExtensionBrowser'
+
+import { Meta, StoryObj } from '@storybook/react'
+
+import { mswDecorator } from '~/mocks/browser'
+
+import { configureFakeExtensionBrowser } from './__mocks__/fakeExtensionBrowser'
+import { STORY_PAGE_URL, pageToolbarState } from './__mocks__/pageToolbarState'
+import { ExtensionPanel } from './ExtensionPanel'
+import type { PageToolbarMode } from './pageToolbarBridge'
+
+type StoryArgs = { mode: PageToolbarMode }
+
+const meta: Meta<StoryArgs> = {
+ title: 'Scenes-Other/Toolbar extension',
+ parameters: {
+ layout: 'fullscreen',
+ viewMode: 'story',
+ mockDate: '2026-01-15 10:01:00',
+ },
+ decorators: [
+ mswDecorator({
+ get: {
+ '/api/users/@me/': MOCK_DEFAULT_USER,
+ '/api/user/toolbar_entitlements': { entitlements: { toolbar_heatmaps: true } },
+ '/api/organizations/:organization_id/projects/:id/': {
+ app_urls: ['https://hedgebox.example.com'],
+ data_attributes: ['data-attr'],
+ },
+ },
+ }),
+ ],
+ render: ({ mode }) => {
+ const uiHost = window.location.origin
+ configureFakeExtensionBrowser({
+ tabUrl: STORY_PAGE_URL,
+ pageState: pageToolbarState(mode),
+ storage: {
+ posthogUiHost: uiHost,
+ posthogToolbarTokens: {
+ [`${uiHost}|${MOCK_TEAM_ID}`]: { accessToken: 'pha_story', refreshToken: null, clientId: 'story' },
+ },
+ },
+ })
+ // The width of the Chrome side panel when it opens.
+ return (
+ <div className="w-[360px] border-r">
+ <ExtensionPanel />
+ </div>
+ )
+ },
+}
+export default meta
+
+type Story = StoryObj<StoryArgs>
+
+export const Home: Story = {
+ args: { mode: 'none' },
+ parameters: { testOptions: { waitForSelector: 'text=Hover a tool to see what it does' } },
+}
+
+export const Inspect: Story = {
+ args: { mode: 'inspect' },
+ parameters: { testOptions: { waitForSelector: 'text=Started trial' } },
+}
+
+export const Heatmap: Story = {
+ args: { mode: 'heatmap' },
+ parameters: { testOptions: { waitForSelector: 'text=Compare plans' } },
+}
+
+export const Actions: Story = {
+ args: { mode: 'actions' },
+ parameters: { testOptions: { waitForSelector: 'text=Clicked contact sales' } },
+}
+
+export const FeatureFlags: Story = {
+ args: { mode: 'flags' },
+ parameters: { testOptions: { waitForSelector: 'text=checkout-button-copy' } },
+}
+
+export const Events: Story = {
+ args: { mode: 'events' },
+ parameters: { testOptions: { waitForSelector: 'text=trial started' } },
+}
+
+export const WebVitals: Story = {
+ args: { mode: 'web-vitals' },
+ parameters: { testOptions: { waitForSelector: 'text=1.64s' } },
+}
+
+export const Experiments: Story = {
+ args: { mode: 'experiments' },
+ parameters: { testOptions: { waitForSelector: 'text=Trial button color' } },
+}
+
+export const More: Story = {
+ args: { mode: 'more' },
+ parameters: { testOptions: { waitForSelector: 'text=1.300.0' } },
+}
diff --git a/frontend/src/toolbar/extension/ExtensionPanel.tsx b/frontend/src/toolbar/extension/ExtensionPanel.tsx
index 56370dcad9c6..508e83c7f39f 100644
--- a/frontend/src/toolbar/extension/ExtensionPanel.tsx
+++ b/frontend/src/toolbar/extension/ExtensionPanel.tsx
@@ -90,7 +90,7 @@ function ExtensionPanelBody({ panelState }: { panelState: ExtensionPanelState })
</LemonBanner>
)
case 'ready':
- return <ExtensionPageToolbar origin={panelState.origin} />
+ return <ExtensionPageToolbar />
}
}
diff --git a/frontend/src/toolbar/extension/ExtensionToolHint.tsx b/frontend/src/toolbar/extension/ExtensionToolHint.tsx
new file mode 100644
index 000000000000..81bf46a245da
--- /dev/null
+++ b/frontend/src/toolbar/extension/ExtensionToolHint.tsx
@@ -0,0 +1,17 @@
+import type { PageToolDefinition } from './extensionPageTools'
+
+export function ExtensionToolHint({ tool }: { tool: PageToolDefinition | null }): JSX.Element {
+ return (
+ <div className="flex flex-1 flex-col items-center justify-center gap-1 px-4 text-center" aria-live="polite">
+ {tool ? (
+ <>
+ <span className="text-2xl text-secondary">{tool.icon}</span>
+ <h3 className="m-0 text-sm font-semibold">{tool.label}</h3>
+ <p className="m-0 text-xs text-secondary">{tool.description}</p>
+ </>
+ ) : (
+ <p className="m-0 text-xs text-secondary">Hover a tool to see what it does</p>
+ )}
+ </div>
+ )
+}
diff --git a/frontend/src/toolbar/extension/__mocks__/fakeExtensionBrowser.ts b/frontend/src/toolbar/extension/__mocks__/fakeExtensionBrowser.ts
new file mode 100644
index 000000000000..eab7805d0666
--- /dev/null
+++ b/frontend/src/toolbar/extension/__mocks__/fakeExtensionBrowser.ts
@@ -0,0 +1,68 @@
+import type { ExtensionPort } from '../extensionBrowser'
+import type { PageToolbarMessage, PageToolbarState } from '../pageToolbarBridge'
+
+// Stories render the side panel outside an extension. `extensionBrowser.ts` reads `browser` when the module loads, so
+// a story imports this module before any panel module.
+
+interface FakeExtensionConfig {
+ tabUrl: string
+ pageState: PageToolbarState
+ storage: Record<string, unknown>
+}
+
+let config: FakeExtensionConfig | null = null
+
+export function configureFakeExtensionBrowser(next: FakeExtensionConfig): void {
+ config = next
+}
+
+function fakeEvent(): { addListener: () => void; removeListener: () => void } {
+ return { addListener: () => undefined, removeListener: () => undefined }
+}
+
+function fakePort(): ExtensionPort {
+ const listeners: ((message: unknown) => void)[] = []
+ const send = (message: PageToolbarMessage): void => {
+ setTimeout(() => listeners.forEach((listener) => listener(message)))
+ }
+ return {
+ name: 'posthog-toolbar-page',
+ postMessage: (message) => {
+ const request = message as { type?: string; tool?: string; command?: { type: string; mode?: string } }
+ if (request.type === 'start' && config) {
+ send({ type: 'state', state: config.pageState })
+ } else if (request.tool === 'session' && request.command?.type === 'set-mode') {
+ send({ type: 'patch', patch: { mode: request.command.mode as PageToolbarState['mode'] } })
+ }
+ },
+ disconnect: () => undefined,
+ onMessage: { addListener: (listener) => listeners.push(listener), removeListener: () => undefined },
+ onDisconnect: fakeEvent(),
+ }
+}
+
+;(globalThis as unknown as { browser: unknown }).browser = {
+ tabs: {
+ query: async () => [{ id: 1, url: config?.tabUrl }],
+ create: async () => ({ id: 2 }),
+ remove: async () => undefined,
+ connect: fakePort,
+ sendMessage: async () => true,
+ onActivated: fakeEvent(),
+ onRemoved: fakeEvent(),
+ onUpdated: fakeEvent(),
+ },
+ windows: { getCurrent: async () => ({ id: 1 }) },
+ storage: {
+ local: {
+ get: async (key: string) => ({ [key]: config?.storage[key] }),
+ set: async (items: Record<string, unknown>) => {
+ Object.assign(config?.storage ?? {}, items)
+ },
+ },
+ },
+ scripting: { executeScript: async () => [{}] },
+ runtime: { onMessage: fakeEvent(), onConnect: fakeEvent(), getURL: (path: string) => `/${path}` },
+ permissions: { contains: async () => true, request: async () => true },
+ action: { onClicked: fakeEvent() },
+}
diff --git a/frontend/src/toolbar/extension/__mocks__/pageToolbarState.ts b/frontend/src/toolbar/extension/__mocks__/pageToolbarState.ts
new file mode 100644
index 000000000000..969cb193c449
--- /dev/null
+++ b/frontend/src/toolbar/extension/__mocks__/pageToolbarState.ts
@@ -0,0 +1,193 @@
+import { DEFAULT_HEATMAP_FILTERS } from 'lib/components/IframedToolbarBrowser/utils'
+
+import type { ActionForm } from '~/toolbar/types'
+
+import type { PageToolbarMode, PageToolbarState } from '../pageToolbarBridge'
+
+export const STORY_PAGE_URL = 'https://hedgebox.example.com/pricing'
+
+export function pageToolbarState(mode: PageToolbarMode): PageToolbarState {
+ return {
+ mode,
+ inspect: {
+ element: {
+ tagName: 'button',
+ actionStep: {
+ event: '$autocapture',
+ tag_name: 'button',
+ text: 'Start free trial',
+ selector: '[data-attr="pricing-start-trial"]',
+ href: null,
+ url: STORY_PAGE_URL,
+ },
+ stats: { count: 412, clickCount: 398, rageclickCount: 9, deadclickCount: 5, rank: 1 },
+ actions: [{ id: 2, name: 'Started trial' }],
+ },
+ isSelected: true,
+ },
+ selectorCounts: {},
+ heatmap: {
+ wildcardHref: STORY_PAGE_URL,
+ autoWildcardEnabled: false,
+ wildcardHrefTooSpecific: false,
+ wildcardHrefEndsWithSlash: false,
+ commonFilters: { date_from: '-7d' },
+ heatmapFilters: DEFAULT_HEATMAP_FILTERS,
+ heatmapColorPalette: 'default',
+ heatmapFixedPositionMode: 'fixed',
+ viewportRange: { min: 1152, max: 1408 },
+ rawHeatmapLoading: false,
+ heatmapsCollection: 'enabled',
+ scrollDepthPosthogJsError: null,
+ clickmapsEnabled: true,
+ clickmapLoading: false,
+ processingProgress: null,
+ matchLinksByHref: true,
+ countedElements: [
+ { text: 'Start free trial', tagName: 'button', count: 398 },
+ { text: 'Compare plans', tagName: 'a', count: 211 },
+ { text: 'Contact sales', tagName: 'a', count: 87 },
+ ],
+ clickCount: 696,
+ canLoadMoreElementStats: false,
+ loadedElementStatsCount: 3,
+ loadingAllElementStats: false,
+ areaSelectionActive: false,
+ areaFilter: null,
+ savingHeatmap: false,
+ saveProgress: null,
+ saveResult: null,
+ },
+ actions: {
+ allActionsLoading: false,
+ actions: [
+ { id: 1, name: 'Viewed pricing' },
+ { id: 2, name: 'Started trial' },
+ { id: 3, name: 'Clicked contact sales' },
+ ],
+ selectedActionId: null,
+ actionForm: { name: null, steps: [{}] } as ActionForm,
+ formRevision: 0,
+ actionFormElementsChains: {},
+ inspectingElement: null,
+ saving: false,
+ saveResult: null,
+ },
+ flags: {
+ available: true,
+ loading: false,
+ flags: [
+ {
+ key: 'new-pricing-page',
+ id: 11,
+ value: true,
+ currentValue: true,
+ hasOverride: false,
+ variants: [],
+ payloadOverride: undefined,
+ },
+ {
+ key: 'checkout-button-copy',
+ id: 12,
+ value: 'control',
+ currentValue: 'test',
+ hasOverride: true,
+ variants: [
+ { key: 'control', name: 'Control', rolloutPercentage: 50 },
+ { key: 'test', name: 'Test', rolloutPercentage: 50 },
+ ],
+ payloadOverride: undefined,
+ },
+ {
+ key: 'annual-billing-toggle',
+ id: 13,
+ value: false,
+ currentValue: false,
+ hasOverride: false,
+ variants: [],
+ payloadOverride: undefined,
+ },
+ ],
+ countFlagsOverridden: 1,
+ impersonatedDistinctId: null,
+ payloadErrors: {},
+ mutationPending: false,
+ mutationError: null,
+ mutationRevision: 0,
+ },
+ events: {
+ available: true,
+ selectedEventTypes: ['posthog', 'custom'],
+ hidePostHogProperties: false,
+ hidePostHogFlags: false,
+ relativeTimestamps: false,
+ isPaused: false,
+ bufferedCount: 0,
+ totalCount: 4,
+ filteredCount: 4,
+ countsByType: { posthog: 3, custom: 1, snapshot: 0 },
+ rows: [
+ { uuid: 'event-4', event: 'trial started', timestamp: '2026-01-15T10:00:42.000Z', pinned: false },
+ { uuid: 'event-3', event: '$autocapture', timestamp: '2026-01-15T10:00:41.000Z', pinned: false },
+ { uuid: 'event-2', event: '$web_vitals', timestamp: '2026-01-15T10:00:03.000Z', pinned: false },
+ { uuid: 'event-1', event: '$pageview', timestamp: '2026-01-15T10:00:00.000Z', pinned: false },
+ ],
+ expandedEventId: null,
+ expandedProperties: {},
+ expandedEventPayload: null,
+ },
+ webVitals: {
+ autocaptureEnabled: true,
+ pathname: '/pricing',
+ localWebVitals: { FCP: 812, LCP: 1640, INP: 96, CLS: 0.04 },
+ remoteWebVitals: { FCP: 1210, LCP: 2380, INP: 180, CLS: 0.08 },
+ },
+ experiments: {
+ loading: false,
+ experiments: [
+ { id: 21, name: 'Pricing headline' },
+ { id: 22, name: 'Trial button color' },
+ ],
+ webExperimentsDisabled: false,
+ selectedExperimentId: null,
+ experimentForm: { name: '', variants: {} },
+ formRevision: 0,
+ selectedVariant: '',
+ selectedElementType: 'all-elements',
+ inspectingElement: null,
+ addVariantAvailable: true,
+ removeVariantAvailable: false,
+ saving: false,
+ saveResult: null,
+ },
+ more: {
+ debugInfo: {
+ version: '1.300.0',
+ apiHost: 'https://us.i.posthog.com',
+ uiHost: null,
+ autocapture: true,
+ rageclicks: true,
+ deadClicks: true,
+ heatmaps: true,
+ sessionRecordingStarted: true,
+ sessionRecordingStatus: 'active',
+ sessionReplayUrl: 'https://us.posthog.com/project/1/replay/session-1',
+ surveysCount: 2,
+ },
+ debugInfoLoading: false,
+ piiMaskingEnabled: false,
+ piiMaskingColor: '#cccccc',
+ piiWarnings: [],
+ screenshot: {
+ taking: false,
+ open: false,
+ eventName: '',
+ suggestions: [],
+ suggestionsLoading: false,
+ selectedEventId: null,
+ uploading: false,
+ result: null,
+ },
+ },
+ }
+}