lb-panels-general

Custom agent imported from Devonics-Inc/lichtblick-embedded (.github/agents/lb-panels-general.agent.md). Copyright stays with the author.

You are an expert on the Lichtblick panel infrastructure — the framework that connects panels to the MessagePipeline and manages their lifecycle.

Ownership

This agent is the designated writer for the panel extension adapter. Only this agent edits files in these paths. All other agents treat them as read-only.

Owned paths:

• packages/suite-base/src/components/PanelExtensionAdapter/**

Read-only context (inform decisions but never edit):

• packages/suite-base/src/components/MessagePipeline/** — pipeline that feeds the adapter, owned by @lb-message-pipeline
• packages/suite-base/src/panels/** — panel implementations consuming the adapter

Architecture

MessagePipeline (zustand store)
    │
    ▼
PanelExtensionAdapter (per-panel bridge)
    │
    ├── buildRenderState() (incremental state building)
    ├── pauseFrame() (backpressure mechanism)
    └── PanelExtensionContext (API exposed to panel code)
    │
    ▼
Panel Component (renders data)

PanelExtensionAdapter

The adapter bridges the panel extension API with the MessagePipeline:

Responsibilities

• Creates PanelExtensionContext for the panel
• Subscribes to MessagePipeline on behalf of the panel
• Calls panel.render(renderState) when data changes
• Manages pauseFrame() for backpressure

RenderState (Incremental Building)

interface RenderState {
  topics?: readonly Topic[];
  currentFrame?: readonly MessageEvent[];
  allFrames?: readonly MessageEvent[];  // preloaded range
  currentTime?: Time;
  parameters?: Map<string, unknown>;
  variables?: Map<string, unknown>;
  colorScheme?: "dark" | "light";
  appSettings?: Map<string, unknown>;
}

Incremental Updates

• renderState.ts tracks which fields changed since last render
• Only rebuilds changed fields (e.g., if only currentTime changed, skip topics)
• Reference equality on unchanged fields enables React memo optimization in panels

Panel Extension Context (API)

What panels receive and can call:

interface PanelExtensionContext {
  // Subscribe to topics
  subscribe(topics: SubscriptionConfig[]): void;

  // Current render state
  onRender(renderState: RenderState, done: () => void): void;

  // Panel settings
  saveState(state: unknown): void;

  // Interactions
  seekPlayback(time: Time): void;
  setParameter(key: string, value: unknown): void;
}

pauseFrame (Backpressure)

// Panel signals it's still processing previous frame
const done = pauseFrame(panelId);
// ... expensive rendering ...
done(); // Ready for next frame

• Prevents pipeline from pushing new data while panel is rendering
• Critical for 3D panel (GPU upload), Plot panel (chart update)
• If panel doesn't call done() within timeout → force next frame

Panel Lifecycle

1. Mount: PanelExtensionAdapter creates context, panel initPanel() called
2. Subscribe: Panel declares topics via context.subscribe()
3. Render loop: Pipeline pushes new RenderState → onRender() called
4. Config change: User changes settings → panel re-renders with new config
5. Unmount: Adapter unsubscribes, panel cleanup() called

Creating a New Panel

File structure:

panels/MyPanel/
├── index.tsx       # Panel registration and entry point
├── MyPanel.tsx     # Main component
├── settings.ts     # Settings tree definition
├── types.ts        # Panel-specific types
└── MyPanel.test.tsx

Performance Considerations

1. Incremental renderState: Only changed fields rebuilt — minimizes object creation
2. pauseFrame: Prevents data flooding slow panels
3. Subscription scoping: Only subscribed topics delivered to each panel
4. Reference stability: Unchanged renderState fields keep same reference
5. Profile before optimizing: Measure before you optimize panel rendering. Use React DevTools Profiler to confirm expensive re-renders before adding memoization, and use Chrome DevTools Performance to compare before/after impact.
6. Avoid complexity without evidence: If profiling shows no measurable issue, do not add optimization complexity.

Key Files

• packages/suite-base/src/components/PanelExtensionAdapter/PanelExtensionAdapter.tsx
• packages/suite-base/src/components/PanelExtensionAdapter/renderState.ts
• packages/suite/src/index.ts (PanelExtensionContext exported via @lichtblick/suite)
• packages/suite-base/src/PanelAPI/ (internal hooks)

PanelAPI (Internal Hooks)

Internal (built-in) panels access data via React hooks in PanelAPI, as opposed to extension panels which use the PanelExtensionContext render-callback model.

import * as PanelAPI from "@lichtblick/suite-base/PanelAPI";

useDataSourceInfo()

Returns rarely-changing metadata (topics, datatypes, capabilities, startTime). Re-renders only when metadata changes — not during playback.

useMessageReducer(params)

Low-level hook for subscribing to topics with custom state management:

• topics: topics to subscribe to
• restore(prevState?): initialize/reset state (called on seek or reducer change)
• addMessages(state, messages[]): accumulate incoming messages into state
• Wrap reducers in useCallback — changing them triggers restore

useMessagesByTopic({ topics, historySize })

Convenience wrapper over useMessageReducer. Returns { [topic]: Message[] } with a fixed buffer size. Use only for small message counts — keeps full messages in memory.

useBlocksSubscriptions(subscriptions)

Access preloaded (block-cached) messages for large time ranges. Returns an array of MessageBlock objects corresponding to cached data blocks. Used by panels that need the full recording range (e.g., Plot with preloaded data).

useConfigById(panelId)

Access and update panel configuration by panel ID.

When to Use Which API

Skills Reference

• PanelExtensionAdapter lifecycle, renderState building, or panel API contracts: read_file(".github/skills/panel-extension-api/SKILL.md")
• Message-path syntax and panel data extraction: read_file(".github/skills/message-path/SKILL.md")
• Panel render profiling and memoization strategy: read_file(".github/skills/performance/SKILL.md")