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.

4.2 KB
Raw Blame

Scene chrome agent guide (frontend/src/layout/scenes)

This directory owns the scene action surfaces:

  • ScenePanel (SceneLayout.tsx): the per-scene action/info side panel. Scenes fill it with <ScenePanelActionsSection>, <ScenePanelInfoSection>, <ScenePanelLabel>, <ScenePanelDivider>. This is the legacy action surface.
  • SceneMenuBar (components/SceneMenuBar.tsx): the Mac-style menu bar above <SceneTitleSection> that consolidates those actions into File / Edit / View / Metadata / Staff only menus. This is the new action surface, gated behind the SCENE_MENU_BAR feature flag. Under the today-rail-nav flag the menus move into the title row after the scene name, so scenes still render it above <SceneTitleSection>.

We are mid-migration (ScenePanel to SceneMenuBar). Until the flag ships everywhere, both surfaces must stay in sync.

ScenePanel is deprecated under today-rail-nav. That redesign will remove the side panel's Info tab, which renders ScenePanel, and the SceneMenuBar takes over every action. Keep the dual-write while the flag-off UI still ships, but build no new surface on ScenePanel and treat it as scheduled for removal.

Rule: every scene action goes in the SceneMenuBar

When you add, edit, or remove any action/feature on a scene's ScenePanel (a button, toggle, link, destructive op, metadata input; anything in <ScenePanelActionsSection> / <ScenePanelInfoSection>), you must make the same change in that scene's SceneMenuBar. A feature that only exists on the ScenePanel is invisible to every user with SCENE_MENU_BAR on.

This is a dual-write, not a move: keep the ScenePanel entry (flag-off path) and add the menu bar entry (flag-on path). Don't delete ScenePanel actions while the flag is still rolling out.

Title actions are a shortcut, never the only home

Every action a user can reach from the actions prop of <SceneTitleSection> must also be in that scene's SceneMenuBar. The menu bar is the complete list of a scene's actions. The title row shows a few of them as a shortcut. Usage decides which actions the title row shows, and which ones stay only in the menus. Promote or demote an action on usage data, not on how important it looks.

If the scene has no SceneMenuBar yet, create one

Scenes get a co-located <Resource>SceneMenuBar component (CohortSceneMenuBar, DashboardSceneMenuBar, NotebookSceneMenuBar, etc). If the scene you're touching doesn't have one, add it:

  1. Create <Resource>SceneMenuBar.tsx next to the scene. It returns null unless the flag is on:

    export function CohortSceneMenuBar({ id }: { id?: CohortType['id'] }): JSX.Element | null {
      const { featureFlags } = useValues(featureFlagLogic)
      if (!featureFlags[FEATURE_FLAGS.SCENE_MENU_BAR]) {
        return null
      }
      return <CohortSceneMenuBarInner id={id} />
    }
    
  2. Build the menus with the primitives from ~/layout/scenes/components/SceneMenuBar, mirroring the actions already on the scene's ScenePanel into the canonical menu set (File / Edit / View / Metadata / Staff only).

  3. Render it in the scene immediately above <SceneTitleSection>, alongside the existing <ScenePanel>:

    <CohortSceneMenuBar id={id} />
    <ScenePanel>…</ScenePanel>
    <SceneTitleSection … />
    

Reference implementations: scenes/cohorts/CohortSceneMenuBar.tsx, products/dashboards/frontend/DashboardSceneMenuBar.tsx, scenes/notebooks/NotebookSceneMenuBar.tsx.

Before you write menu code, read the skill

The component taxonomy, canonical menu order, destructive-action styling, opensFloatingUi, rich-input (SceneMenuBarPopover + TagsCombobox) wiring, empty-menu handling, and optimistic-save patterns all live in the /scene-menu-bar skill (.agents/skills/scene-menu-bar/SKILL.md). Invoke it before adding or moving menu items. This guide is the when/why; the skill is the how.

Instrumentation is automatic

SceneMenuBar.tsx captures scene menu bar shown / menu opened / item clicked centrally, so you don't wire analytics per scene. Just give items a stable data-attr (${RESOURCE_TYPE}-menubar-<action>) so the captured item is meaningful.